# Features Documentation

This document provides comprehensive information about all features in the MPV.Rocks Installer project.

## Table of Contents

- [Installation Features](#installation-features)
- [Configuration Features](#configuration-features)
- [System Information](#system-information)
- [Hardware Acceleration](#hardware-acceleration)
- [Update System](#update-system)
- [Language Preferences](#language-preferences)
- [Web UI Features](#web-ui-features)
- [Modal System](#modal-system)
- [Platform-Specific Features](#platform-specific-features)

---

## Installation Features

### Cross-Platform Installation

**Supported Platforms:**
- Windows (x86_64-v2) - Windows 10/11
- Linux (x86_64, arm64) - Various distributions
- macOS (arm64, x86_64, universal) - macOS 11+

**Installation Methods:**
- **Portable Binary** - Standalone MPV executable
- **Flatpak** - Sandboxed Linux package
- **Snap** - Universal Linux package
- **Homebrew** - macOS package manager
- **IINA** - macOS App Store (managed)

### Supported Applications

| Application | Type | Platforms | Methods |
|-----------|-------|-----------|----------|
| MPV | Media Player | All | Portable, Flatpak, Snap, Brew |
| Celluloid | Frontend | Linux | Portable, Flatpak, Snap, Brew |
| IINA | Frontend | macOS | IINA (managed) |
| MPC-QT | Frontend | Windows | Portable, Installer |
| Infuse | Frontend | iOS | Infuse (managed) |
| Jellyfin MPV | Frontend | All | Portable |

### Installation Features

**Streamed Output:** Real-time installation output displayed in TUI and Web UI via SSE
**Progress Tracking:** Visual progress bars for downloads
**Retry Logic:** 3 attempts with exponential backoff (1s, 2s, 3s)
**Automatic Shortcuts:** Desktop and menu shortcuts created
**File Associations:** Set MPV as default for video files (Windows)
**Config Backups:** Automatic backup before installation
**Version Management:** Track installed versions for updates

### Uninstallation

**Clean Removal:** Removes application and configuration files
**Registry Cleanup:** Windows registry entries removed (where applicable)
**Desktop Shortcut Removal:** Shortcuts removed from desktop and menu
**File Association Removal:** MPV removed as default (Windows)

---

## Configuration Features

### MPV Configuration Management

**Configuration File:** `~/.config/mpv/mpv.conf`

**Editable Settings:**
- Hardware Acceleration (hwdec)
- Video Output Driver (vo)
- Scale Filter (scale)
- Dither Algorithm (dither-depth-convert)
- Audio Language (alang)
- Subtitle Language (slang)

**Backup System:**
- Automatic backup on first write
- Backup location: `~/.config/mpv/conf_backups/`
- Timestamp format: `2006-01-02-150405_mpv.conf`
- Unlimited backup history
- Restore from any backup

**Configuration Operations:**
- **Reset to Recommended:** Restore default MPV configuration
- **Restore from Backup:** Load configuration from backup file
- **Apply Custom Settings:** Save user-defined settings
- **Config Preservation:** Existing settings preserved during updates

### Hardware Acceleration Configuration

**Platform-Specific Methods:**

**Windows:**
- nvdec, nvdec-copy (NVIDIA only)
- d3d11va, d3d11va-copy
- auto, auto-safe (NVIDIA only)
- vulkan, vulkan-copy
- no

**Linux:**
- nvdec, nvdec-copy (NVIDIA only)
- vaapi, vaapi-copy (AMD/Intel only)
- vulkan, vulkan-copy
- drm, drm-copy (AMD/Intel only)
- auto
- no

**macOS:**
- videotoolbox, videotoolbox-copy
- auto
- no

**Configuration Display:**
- Current HWA status (Enabled/Disabled)
- GPU vendor-specific coloring (AMD=Red, NVIDIA=Green, Intel=Blue)
- Method descriptions
- Compatibility warnings

---

## System Information

### System Information Page

**Overview:** Comprehensive system information display in Web UI

**Displayed Information:**
- **Processor:** Model, vendor, cores, architecture, CPU features
- **Operating System:** OS type, version, architecture, kernel
- **Graphics:** GPU model, vendor, VRAM, drivers
- **Memory:** Total, available, used
- **Storage:** Total, available, used
- **Installer:** Version, build date, build hash

**Architecture-Specific Display:**
- **x86:** AVX2, AVX512 support (conditional)
- **ARM:** NEON support (conditional)
- CPU Features box only shows relevant features

**Visual Enhancements:**
- OS Type: Capitalized (Linux/Windows/Darwin) with icons
- Architecture: Proper capitalization (AMD64, ARM64, x86)
- Distribution: Capitalized (Ubuntu, Fedora, etc.) with icons
- Distro Family: Capitalized (Debian, RHEL, Arch, etc.) with icons

---

## Hardware Acceleration

### GPU Codec Detection

**Supported Codecs (10 total):**
- AV2 (Advanced Video Coding)
- VVC (Versatile Video Coding)
- AV1
- VP9 (Video Processing 9)
- HEVC (High Efficiency Video Coding)
- VP8 (Video Processing 8)
- ProRes
- VC-1 (Video Codec 1)
- MPEG-2
- MPEG-4

**Detection Methods:**

**Linux:**
- glxinfo (primary) - Best format with Mesa + model + driver + codename
- vulkaninfo (secondary) - Multiple GPUs, good format
- lspci (fallback)
- sysfs DRM (fallback)

**Windows:**
- PowerShell Get-WmiObject - GPU model and vendor detection
- CSV lookup for codec support

**macOS:**
- CGO (primary) - VideoToolbox framework VTIsHardwareDecodeSupported()
- Model-based (fallback) - Apple Silicon specifications

### GPU Database

**Entries (37 total):**
- **AMD Radeon (16 entries):** Polaris through RDNA 4
- **Intel (11 entries):** Gen 6 through Xe2-HPG
- **NVIDIA (10 entries):** Kepler through Blackwell

**Multi-Level Matching:**
1. Exact model name match
2. Series name match
3. Primary codename match
4. Alternative codename match

### Platform-Specific HWA Options

See individual platform documentation for detailed HWA options:
- [Windows Platform Guide](docs/PLATFORM_GUIDES/WINDOWS.md)
- [Linux Platform Guide](docs/PLATFORM_GUIDES/LINUX.md)
- [macOS Platform Guide](docs/PLATFORM_GUIDES/MACOS.md)

---

## Update System

### Installer Updates

**Version Checking:**
- Automatic check on startup
- Comparison with latest release
- Update notification available indicator
- Version display with status (Update Available)

**Update Installation:**
- Download with visual progress bar
- BLAKE3 checksum verification
- Binary replacement in place
- PATH update
- Clean quit (user manually restarts)

**Features:**
- Streaming progress updates via SSE
- Retry logic with exponential backoff (3 attempts: 1s, 2s, 3s)
- MB/MB display during download
- Success messages with verification status
- Fallback to browser confirm on failure

### MPV Client Updates

**Update Detection:**
- Check for updates across all installed MPV clients
- Support for portable, Flatpak, Snap, Homebrew
- Package manager version detection
- Current version display

**Update Installation:**
- Update via package manager (where applicable)
- Download and replace portable binaries
- Update tracking per application
- Update available indicators

---

## Language Preferences

### Language Database

**Supported Languages:** 123+ languages from 7 language families

**Major Languages (33):**
Arabic, Chinese, Czech, Danish, Dutch, English, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Spanish, Swedish, Tamil, Telugu, Thai, Turkish, Vietnamese, Fijian Hindi, Filipino, Hebrew

**Language Data Structure:**
- ISO 639-1 language code (en, zh, es)
- English name
- Native name
- Region/country
- Text direction (ltr/rtl)
- Regional variants (en-US, zh-CN, etc.)

### Language Selection Features

**Web UI Features:**
- Major languages list (alphabetically sorted)
- Regional variants selection
- Search functionality with debounce
- Clear search button
- Results count badge
- Flag emoji display (country flags)
- Multiple selection support
- Priority ordering (audio/subtitle languages)

**TUI Features:**
- Language selection interface
- Regional variant selection
- Priority management
- Save/load from config

**Configuration Integration:**
- `alang` config value for audio languages
- `slang` config value for subtitle languages
- Comma-separated values: `alang=en,es,fr`
- Config preservation with automatic backups
- Retry logic with exponential backoff

### Flag Mapping

**Supported Flags:** 33 country flag emoji

**Flag Mapping:**
- Language code to country code (e.g., es → ES, en → US)
- Custom mappings for Czech (cs → CZ), Danish (da → DK), Greek (el → GR), Hebrew (he → IL), Swedish (sv → SE), Filipino (fil → PH)

**Flag Display:**
- Flag emoji shown in language selection
- Regional variants use parent language flag (en-US uses US flag)

---

## Web UI Features

### Dashboard

**Overview:** Centralized overview page for installer status and updates

**Features:**
- Installer version display with update indicator
- System quick links
- Installed apps list with status
- Client updates section
- Recent activity log
- App logos for visual identification
- Package manager versions
- "Up to Date" status indicators

### MPV Player Apps Page

**Overview:** Complete MPV client application catalog and management

**Features:**
- All MPV players (MPV, Celluloid, IINA, MPC-QT, Infuse, Jellyfin MPV)
- Install buttons for all available methods
- Platform-specific method filtering
- App-specific logos
- Update tracking
- Uninstall support
- File associations (Windows)

### System Information Page

**Overview:** Comprehensive system information display

**Features:**
- Processor details (model, vendor, cores, features)
- Operating system (type, version, kernel)
- Graphics information (GPU, VRAM, drivers)
- Memory, storage information
- Installer information (version, build info)
- Architecture-specific display
- Capitalized text with icons

### Hardware Acceleration Page

**Overview:** Hardware acceleration configuration interface

**Features:**
- Current HWA status display
- Platform/GPU-specific method filtering
- GPU vendor coloring (AMD=Red, NVIDIA=Green, Intel=Blue)
- Method descriptions
- Save to MPV configuration
- Apply and reset options

### Language Preferences Page

**Overview:** Language and regional variant configuration

**Features:**
- Major languages (33 total)
- Regional variants per language
- Search functionality
- Flag emoji display
- Multiple selection
- Priority ordering (audio/subtitle)
- Save/load from config
- Clear button
- Results count

### Configuration Pages

**Options Pages:**
- **MPV Config Options:** Reset, restore, hardware acceleration
- **Hardware Acceleration:** HWA method selection
- **Language Preferences:** Audio/subtitle languages

**Features:**
- Automatic config backups
- Restore from any backup
- Backup list with dates and paths
- Apply custom settings
- Reset to recommended

### Logs Page

**Overview:** Real-time and historical log viewing

**Features:**
- Live log streaming (tail -f style)
- Log level filtering
- Download log file
- Clear logs
- Automatic scroll to bottom on new entries

---

## Modal System

### Overview

Custom modal system to replace browser confirm dialogs with polished, consistent modals.

### Modal Types

**7 Supported Modal Types:**
1. **shutdown** - Close MPV.Rocks Installer
2. **update-installer** - Update installer to new version
3. **uninstall** - Uninstall an application
4. **remove-file-associations** - Remove file associations (Windows)
5. **reset-config** - Reset MPV configuration
6. **restore-config** - Restore configuration backup
7. **apply-config** - Apply configuration settings

### Modal Features

**Design:**
- Clean, responsive Tailwind CSS styling
- Smooth animations (slide-in/fade-out)
- Backdrop blur effect
- Danger action styling (red buttons)
- Close button (X)
- Click-outside-to-close
- Escape key support

**Functionality:**
- Fetches modal config from `/api/modal`
- Executes actions via POST requests
- Automatic page reload on success
- Fallback to browser confirm on failure
- Console logging for debugging

**Public API:**
```javascript
window.MPVRocksModal = {
    show: showModal,
    hide: hideModal,
    init: initModal
};
```

### Usage Examples

**Shutdown Modal:**
```html
<button data-modal="shutdown" hx-confirm="Close MPV.Rocks Installer?">
    Close App
</button>
```

**Uninstall Modal:**
```html
<button data-modal="uninstall" 
        data-modal-params='app_name=mpv&app_type=app&install_method=method-id'
        hx-confirm="Uninstall mpv?">
    Uninstall
</button>
```

---

## Platform-Specific Features

### Windows Features

**File Associations:**
- Install MPV as default for video files
- Remove file associations
- Fire-and-forget batch file operations
- UAC elevation for operations
- Batch file pause stripping

**Shortcuts:**
- Desktop shortcuts with correct icons
- Start menu shortcuts
- Icon extraction (icon-128.png → mpv-manager.ico)
- VBS script auto-extraction

**Console Auto-Resize:**
- Automatic resize to 120x40 on startup
- Full menu visibility
- Success messages displayed
- PowerShell resize command

**CPU Compatibility:**
- x86-64-v2 baseline for maximum compatibility
- Supports Sandy Bridge (2011) and later
- Eliminates access violation crashes

### Linux Features

**Package Manager Support:**
- APT version detection
- Flatpak integration
- Snap integration
- Homebrew (for compatibility testing)

**GPU Detection:**
- glxinfo primary detection
- vulkaninfo secondary
- VAAPI/VDPAU codec detection
- CSV lookup for codec support
- CPU iGPU filtering

**Configuration:**
- `~/.config/mpv/` config directory
- .desktop file creation for portable installs
- Flatpak/snap integration

### macOS Features

**Code Signing:**
- Apple Developer signing required for distribution
- Gatekeeper bypass instructions
- Certificate management

**Apple Silicon Support:**
- Native arm64 builds
- CGO-based VideoToolbox codec detection
- Model-based fallback for cross-compilation
- Universal binary support

**App Bundle:**
- .app bundle creation
- Dock icon
- Spotlight indexing
- LaunchServices registration

**Configuration:**
- `~/Library/Application Support/mpv/` for app config
- `~/.config/mpv/` for MPV config

---

## Quick Reference

### Configuration Keys

| Key | Value | Description |
|-----|--------|-------------|
| alang | en,es,fr | Audio language codes |
| slang | en,ja,ko | Subtitle language codes |
| hwdec | nvdec,vaapi | Hardware decoder method |
| vo | gpu,libmpv | Video output driver |
| scale | ewa_lanczos | Video scale filter |
| dither-depth-convert | error-diffusion | Dither algorithm |

### Installation Method IDs

| ID | Application | Platform | Description |
|----|-------------|----------|-------------|
| mpv-binary | MPV | All | Portable binary |
| mpv-flatpak | MPV | Linux | Flatpak package |
| mpv-snap | MPV | Linux | Snap package |
| mpv-brew | MPV | macOS | Homebrew package |
| celluloid-pkg | Celluloid | Linux | Flatpak package |
| iina-appstore | IINA | macOS | App Store |
| mpc-qt-installer | MPC-QT | Windows | Installer |

---

## Future Enhancements

### Planned Features

1. **Plugin System** - Extensibility for third-party installers
2. **Multi-Language UI** - Full internationalization
3. **Advanced Backup Management** - Keep last N backups, auto-cleanup
4. **Enhanced GPU Detection** - DirectX features, external GPUs
5. **Conflict Resolution** - Merge strategies for concurrent config edits
6. **Config Versioning** - Track changes, rollback support
7. **Runtime Configuration** - Configurable retry counts and backoff delays

### Performance Improvements

1. **Lazy Loading** - On-demand asset and data loading
2. **Caching** - Persistent cache for API responses
3. **Streaming** - Progressive loading for large operations
4. **Parallelism** - Increased concurrent operations

---

## Conclusion

This features documentation provides comprehensive information about all features in the MPV.Rocks Installer project. For implementation details, see:
- [Session Summaries](docs/SESSION_SUMMARIES.md) - Detailed development sessions
- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
- [Platform Guides](docs/PLATFORM_GUIDES/) - Platform-specific documentation
- [Testing Guide](docs/TESTING.md) - Testing procedures and checklists
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions