# 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)
- [On-Screen Controller UI Settings](#on-screen-controller-ui-settings)
- [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)
- [Keyring & Sudo Password](#keyring--sudo-password)
- [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 (separate arm64 and x86_64 binaries) - macOS 13+

**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 reserve 100% for a successfully completed job; extraction and configuration remain below 100%
**Retry Logic:** 3 attempts with exponential backoff (1s, 2s, 3s)
**Automatic Shortcuts:** Desktop and menu shortcuts created
**File Associations:** Each managed MPV card offers **Install File Associations** and **Remove File Associations**, scoped to that installation path. It runs the installed mpv's native `--register` command, verifies the executable and supported-file registrations, and opens Windows Default apps for file-type selection. This is the operation provided by the downloaded archive's `mpv-register.bat`.
**Config Backups:** Automatic backup before installation
**Version Management:** Track installed versions for updates
**Verified IINA Mounts:** Read-only private mount root, exact `hdiutil -plist` device binding, and bundle ID/signature/architecture validation

### Uninstallation

**Clean Removal:** Removes manager-owned application payload files while preserving configuration and unrelated content
**Ownership Proof:** Windows portable installs use a transactional exact-file manifest; populated unowned destinations fail closed
**Busy Files:** Before Windows uninstall removes anything, it checks every owned file for write/delete access. A running player, locked file or read-only file stops removal with instructions to close the app and retry. Later external changes can still cause removal failures; the ownership inventory is retained for retry.
**Desktop Shortcut Removal:** Shortcuts removed from desktop and menu
**File Association Removal:** Uninstall invokes mpv's native `--unregister` only when the selected executable owns the native registration and the expected entries remain intact. Another installation's active registration is retained.

---

## 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
- Restore/delete accepts only flat regular backup files and uses
  descriptor-relative access so symlinked intermediate directories cannot
  redirect the operation

**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
- Config and language forms validate all supplied values before writing and
  commit their `mpv.conf` fields in one cross-process-serialized atomic update
- Config Apply sends only changed controls and displays existing custom dropdown
  values. Clearing screenshot text options resets the global option to mpv
  defaults; omitted fields and named-profile settings remain intact.

### 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

## On-Screen Controller UI Settings

The Web UI exposes a generalized **UI Settings** page for the installed ModernZ or uOSC controller. The TUI
detects the active controller and provides either **ModernZ UI Settings** or **uOSC UI Settings** under MPV
Configuration Options. ModernZ-only guidance is never shown for uOSC.

Managed ModernZ installations use resolution-independent scaling by default:

```ini
vidscale=no
scalewindowed=1.0
scalefullscreen=1.0
```

The Web and TUI editors describe this as **Consistent size (recommended)**. Users can instead follow mpv's
`osd-scale-by-window` policy or always scale with the player window, and can set separate windowed/fullscreen size
multipliers. Matching multipliers avoid a visual jump when entering fullscreen; 1.25–2.0 values are available for
manual HiDPI adjustment.

Component updates preserve the complete existing `modernz.conf` or `uosc.conf` byte for byte, including comments,
unknown future options, permissions, and all user customizations. Before committing an update, the manager stages and
validates the new UI files and creates a timestamped `*.pre-update-*.bak` copy beside an existing config. Verified
clean templates are retained under `.mpv-manager/ui-baselines/` so a future migration can distinguish old defaults
from user edits.

Legacy ModernZ configs whose effective `vidscale` is still `auto` receive a persistent one-time migration prompt in
both Web and TUI modes. Users can apply consistent sizing or explicitly keep the current behavior; only `vidscale` is
changed, so custom windowed/fullscreen multipliers remain intact. Versioned decisions are persisted in
`mpv-manager.json`. Known settings with values incompatible with the current editor are reported globally and on the
UI Settings page rather than silently rewritten.

Applying that migration is a crash-recoverable two-resource transaction: a
bounded intent journal captures the exact original `modernz.conf`, the script
path stays cross-process locked until the manager decision is durable, and
startup either retains the committed setting or restores the original bytes.

---

## 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 - Display-attached OpenGL adapters
- vulkaninfo - Vulkan-visible adapters
- lspci - PCI display and 3D controllers
- sysfs DRM (fallback)

The three command sources are aggregated rather than short-circuited. Model
names retain embedded trademark text, PCI IDs resolve through the system
database with a vendor fallback, and per-adapter codec matches are combined on
hybrid systems.

**Windows:**
- PowerShell Get-WmiObject - GPU model and vendor detection
- Embedded model-catalog 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](PLATFORM_GUIDES/WINDOWS.md)
- [Linux Platform Guide](PLATFORM_GUIDES/LINUX.md)
- [macOS Platform Guide](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:**
- Verify the Ed25519-signed component manifest against embedded release keys
- Reject manifests outside embedded key epochs, revoked keys, build freshness,
  or the persisted highest-accepted publication/version
- Download once with visual progress, signed exact-size, and BLAKE3 checks
- Verify exact product/component/version/platform identity before handoff
- Stage the running and configured PATH installations as one durable transaction
- Use a copied post-exit helper with never-absent platform replacement, verified
  backup rollback, and startup recovery
- Record helper commit/rollback/failure durably and reconcile it into Tasks on
  the next normal start; helper handoff itself is shown as pending final outcome
- Hash/size-check candidates immediately before every identity execution
- Web mode closes automatically and asks the user to restart; TUI relaunches on
  the original terminal and acknowledges health only after its first rendered frame

**Release provenance:** unattended tag generation requires a committed,
reviewed provenance lock with exact upstream versions/URLs/digests and uses the
six pipeline-local manager binaries. It produces an unsigned candidate for a
separately administered OIDC-authenticated signing service; the application
pipeline never receives the Ed25519 private key.

**Features:**
- Streaming progress updates via SSE
- Active/recent snapshot reconciliation on every SSE connect/reconnect
- Bounded per-client event queues with terminal/status delivery priority
- Graceful shutdown closes persistent streams before the HTTP deadline
- Three download attempts with bounded linear backoff
- MB/MB display during download
- Cross-process update lock and unique journal/staging paths
- Non-dismissible Web restart notice with backend-owned shutdown
- Transactional primary/secondary outcomes

UI Settings autosaves are ordered independently per option key, so a slow
older response cannot overwrite a newer value or reset. Regional-language
navigation similarly assigns one monotonic request owner and ignores stale
responses/controllers after a newer language is selected.

### Command-line and PATH lifecycle

- CLI parsing rejects trailing positionals, conflicting subcommand/`--mode`
  combinations, mutually exclusive update flags, and flags used in the wrong
  mode.
- A custom CLI destination is supported only by Windows portable MPV methods;
  other methods fail before download because their package/app/component
  installers own the destination.
- Verbose and debug modes mirror structured logs to stderr from startup.
- “Add MPV Manager to PATH” uses one reversible operation. Unix maintains one
  marked, idempotent PATH block and two command names; Windows writes
  `mpv-manager.exe`/`mpv-install.exe` and updates the current-user registry
  PATH. A failure restores the previous files, shell/registry value, and
  manager state instead of reporting partial success.

Configuration values containing quoted `#` characters round-trip through the
MPV, hotkey, ModernZ, and uOSC editors. Script-option files retain their BOM,
newline convention, permissions, and ownership, and symlink targets are not
silently replaced. Per-key hotkey edits and removals affect every duplicate
binding; the literal `#` key is rejected in favor of mpv's `SHARP` spelling so
it cannot serialize as a comment.

### MPV Client Updates

Windows FFmpeg updates stage and byte-verify a sibling AMD64 PE before touching
the live executable. Binary activation and persisted version metadata commit
together; failures restore the previous executable and retain the recovery
copy if restoration itself cannot complete.

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

Discovery never launches a Windows candidate executable. Detected apps are
reconciled by canonical method/path identity, so multiple installations using
one method remain distinct; inconclusive package/filesystem probes preserve
existing records. Linux discovery commands are time/output bounded and run in
a stable C locale.

MPC-QT downloads use a unique temporary directory, removed after the installer
finishes or the operation fails/cancels. Older `mpc-qt-setup.exe` files in the
MPV root are excluded from MPV ownership and removed after a guarded MPV install
or update commits, including old or partial downloads. Cleanup inspects and
deletes the same regular file handle; directories and links remain untouched.
A locked file produces a warning and can be retried on the next install/update.
It remains excluded from ownership so cleanup failure does not block installation.

MPC-QT completion is reported only after the elevated installer exits
successfully and `mpc-qt.exe` is found in a documented Program Files or
uninstall-registry location.

**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:**
- Canonical ISO 639-1 code when available, otherwise ISO 639-2/3 (for example `hif` and `fil`)
- English name
- Native name
- Region/country
- Text direction (ltr/rtl)
- Regional variants (en-US, zh-CN, etc.)
- Integrity-checked common-code coverage and unique, prefix-consistent locale IDs

### 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
- Active install/update/config workers are cancelled and joined before Escape
  returns or Ctrl+C quits; their remaining output is drained first
- “Change MPV UI” requires selection of the exact installed app and performs a
  UI-only transaction rather than rerunning the app installer
- UI installs and updates retain managed-path rollback evidence in a durable
  journal; startup restores interrupted replacements before normal operation
- uOSC archives are fully preflighted in private staging and may contain only
  the reviewed script/module/font/config layout
- Enter/Escape used by a list filter are consumed by the filter before any
  selected action can run

**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

### Tasks and background operations

- Install, update, uninstall, adopt, and UI-change jobs stream progress through SSE.
- Cancellation remains visibly `Stopping…` until the worker has actually stopped; active leases are not released early.
- Irreversible commit boundaries reject late cancellation instead of claiming that a committed operation was cancelled.
- Shared resource leases serialize manager state, MPV config/UI trees, install targets, app identities, and package-manager mutations, including direct configuration APIs.
- Physical success followed by tracking failure is shown as **Needs reconciliation**, persisted in task history, and includes corrective guidance.
- Shared job history serializes complete read/modify/write cycles across
  processes, uses unique durable replacements, and quarantines malformed JSON
  for inspection before accepting new terminal records.
- TUI install/update/uninstall history is recorded only after installed-app metadata persistence reaches its final outcome.
- TUI cancellation shares the worker-owned terminal model: cancellation waits
  for worker acknowledgement and stream drain before navigation or process exit.

### 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

**Supported Modal Types:**
1. **shutdown** - Close MPV.Rocks Installer
2. **update-manager** - Update MPV Manager to a new version
3. **update-manager-success** - Post-update restart notice
4. **remove-file-associations** - Remove file associations (Windows)
5. **reset-config** - Reset MPV configuration
6. **restore-config** - Restore configuration backup
7. **delete-backup** - Delete a configuration backup
8. **clear-logs** - Clear the application log

### 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>
```

---

## Keyring & Sudo Password

Package manager operations (apt, dnf, pacman, zypper, snap, some flatpak/brew operations) need root privileges. The keyring feature stores the sudo password securely so installs and updates don't stall on an interactive password prompt.

**How it works:**
- The sudo password is stored in the system keyring under the service name `mpv-manager`
- `RunSudoCommand` (`pkg/installer/command_runner.go`) reads it with a bounded operation, validates it with bounded `sudo -S -v`, and then runs commands with cached sudo credentials
- With no keyring available or no stored password, it falls back to regular interactive sudo

**Backends** (`pkg/keyring/keyring.go`):
- Linux: the freedesktop Secret Service login/default collection (`secret-service`), implemented by GNOME Keyring and current KDE Wallet integrations
- macOS: Keychain (`keychain`); Windows: Credential Manager (`wincred`)
- There is no `pass` or application-managed file fallback
- Native operations use a 3-second application deadline and a one-operation gate; the underlying synchronous D-Bus call can outlive the deadline but cannot accumulate unbounded blocked goroutines
- Normal startup and package update discovery do not access the keyring

**Web UI:**
- `GET /api/keyring/status` - One bounded lookup for backend availability and whether a password is stored
- `POST /api/keyring/auth` - Validate with a 15-second `sudo` deadline and store the password (rate-limited: 5 attempts per 60 s)
- `DELETE /api/keyring/auth` - Clear the stored password
- Password modal (`internal/webassets/templates/password-modal.html` + `internal/webassets/static/password-modal.js`) prompts before sudo-required install methods (package, snap, flatpak, brew)

---

## Platform-Specific Features

### Windows Features

**File Associations:**
- **Install File Associations** runs the selected managed `mpv.exe` with `--no-config
  --load-scripts=no --register`, the native operation behind the archive's
  `mpv-register.bat`. It verifies App Paths, Applications/SupportedTypes, the
  file handler and capabilities before opening Windows Settings. Old RC3–RC5
  MPV Manager registration is retired after success.
- Native mpv registers for the current user when run normally, or all users
  when MPV Manager is already elevated. The Settings link matches that scope.
  The registrar provides file, protocol and autoplay handling plus its Start
  menu shortcut. Windows still handles the user's choice of default application.
- Native registration is shared by mpv installations; selecting another managed
  installation makes it the registered mpv path. Removal checks that path and
  the expected entries before invoking `--unregister`, preserving another active
  installation or a changed registration.
- Both native commands run with config/scripts disabled, a 30-second deadline,
  owned process cleanup and a commit guard. The batch file itself is not executed.

- Windows 11 versions supporting the application link open mpv’s page directly;
  older Windows versions may show the main Default apps page, where users search
  for mpv.
- Never elevate mutable install-tree register/unregister scripts
- Retire legacy shortcuts that targeted those scripts

**Shortcuts:**
- Desktop shortcuts with correct icons
- Start menu shortcuts
- Web-mode shortcuts reference an existing installed manager or the running
  portable executable. Creating a shortcut does not replace manager binaries.
- 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
- Optimized player selection requires the complete x86-64-v3 feature baseline;
  AVX2 alone does not select it. Windows ARM64 FFmpeg updates retain native ARM64.

### 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
- Embedded model-catalog 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

**Release Format (v1.3):**
- Separate raw arm64 and x86_64 executables
- No universal binary, `.app` bundle, or DMG is published
- A signed/notarized `.app` in a DMG is planned for the v1.4 Wails desktop migration

See [the macOS platform guide](PLATFORM_GUIDES/MACOS.md) for the current
artifact contract and the planned application-bundle direction.

**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:
- [Architecture](ARCHITECTURE.md) - System architecture and design
- [Platform Guides](PLATFORM_GUIDES/) - Platform-specific documentation
- [Testing Guide](TESTING.md) - Testing procedures and checklists
- [Troubleshooting Guide](TROUBLESHOOTING.md) - Common issues and solutions

### Boolean controls and job progress

Config and UI Settings use keyboard-accessible switches for binary Yes/No
options. Multi-value choices such as `auto` remain dropdowns. UI Settings saves
configuration-native `yes`/`no` values, supports reset and restores the saved
switch state after a failed write. Viewing progress opens the existing job
without requesting a conflicting app scan; terminal job handling refreshes lists.

Acknowledged job cancellation dismisses the running toast and offers task details.
Cancelling the install UI selection with Cancel or Escape restores keyboard focus
to the enabled Install button.

Job buttons also recover when a task finishes before its start response arrives;
late listeners read the retained terminal result so a failed operation can be
retried without refreshing the page.

Leaving a page closes its event stream and reconnect timer. Returning through
Back reconnects to the server snapshot, including jobs completed while away,
so cached pages cannot occupy connections needed by the current page.