# MPV.Rocks Manager

A cross-platform Go application for installing and managing MPV media player on Windows, macOS, and Linux.

![MPV.Rocks](https://img.shields.io/badge/MPV.Rocks-Purple)

---

## Table of Contents

- [Features](#features)
- [Screenshots](#screenshots)
- [Installation](#installation)
- [Usage](#usage)
- [Updates](#updates)
- [Installation Methods](#installation-methods)
- [Configuration](#configuration)
- [Language Preferences](#language-preferences)
- [Security](#security)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)
- [Links](#links)
- [Acknowledgments](#acknowledgments)

---

## Features

✨ **Cross-Platform** - Support for Windows, macOS, and Linux

🌐 **Web UI** - Modern web interface with real-time updates (default launch option)

🖥️ **Terminal Interface (TUI)** - Easy to use terminal UI interface

📦 **Multiple Installation Methods** - Choose the best installation method and app for your needs

⚡ **Hardware Acceleration** - Pre-configured GPU decoding for smooth video playback

🎛️ **Custom UI Integration** - ModernZ and uOSC with update-safe config preservation, UI-specific Web/TUI editors, and predictable ModernZ scaling controls

🌍 **Language Preferences** - Audio and subtitle language priorities (120+ languages)

🔄 **Auto Updates** - Track and update MPV and related apps

📊 **System Information** - CPU, GPU, and platform detection

🗂️ **Config Management** - Automatic backup and restore with timestamps

⌨️ **Hotkey Presets** - One-click keybinding profiles (mpv Default, VLC, MPC-HC) with searchable shortcut browser

🔑 **Keyring Integration** - Sudo password stored securely in the system keyring for package manager installs

🔐 **Secure Downloads** - BLAKE3 hash verification for all downloads

### Web UI

The installer includes a modern web interface with real-time updates:

- 📊 Dashboard overview of installed MPV players with version info
- 🌎 Customize your audio and subtitle preferences
- 🛠️ Configure MPV settings and options from web browser
- 💻 System information page (CPU, GPU, platform details)
- 📥 Install, update, and uninstall apps directly from the browser
- 🎭 Platform-specific icons for visual identification

![MPV.Rocks Manager Web UI](assets/screenshots/web-dashboard.webp "Web UI Dashboard showing installed apps and system information")
![MPV.Rocks Manager Web UI](assets/screenshots/web-apps.webp "Web UI Showing available and installed apps and updates")
![MPV.Rocks Manager Web UI](assets/screenshots/web-languages-1.webp "Web UI for setting languages preferences")
![MPV.Rocks Manager Web UI](assets/screenshots/web-languages-2.webp "Web UI for setting languages preferences")
![MPV.Rocks Manager Web UI](assets/screenshots/web-config.webp "Web UI for changing MPV settings and screenshot settings")

### TUI

The terminal interface provides:

- 🖼️ Easy-to-use interface with keyboard navigation
- 📜 Real-time command output in a scrollable term window
- 🌎 Customize your audio and subtitle preferences
- 🛠️ Configure MPV settings and options from terminal
- 💻 System information on main menu (CPU, GPU, platform details)
- 📥 Install, update, and uninstall apps directly from the terminal
- 📝 All operations logged to `~/.config/mpv/mpv-manager.log`

![MPV.Rocks Manager TUI](assets/screenshots/tui-main-menu.webp "TUI showing the Main Menu")
![MPV.Rocks Manager TUI](assets/screenshots/tui-install.webp "TUI showing apps to install")
![MPV.Rocks Manager TUI](assets/screenshots/tui-languages-1.webp "TUI showing language selection")
![MPV.Rocks Manager TUI](assets/screenshots/tui-languages-2.webp "TUI showing language search results")
![MPV.Rocks Manager TUI](assets/screenshots/tui-screenshots.webp "TUI showing screenshots settings menu")
![MPV.Rocks Manager TUI](assets/screenshots/tui-config.webp "TUI showing MPV configuration")


### Hardware Acceleration Options

The installer automatically recommends the best hardware decoding method based on your OS and GPU:

**Windows:**
- **NVIDIA**: `nvdec-copy,auto` (recommended) - Best quality with fallback
- **AMD/Intel**: `vulkan,auto` (recommended) - Vulkan with fallback
- Other options: auto, auto-safe, nvdec, d3d11va, d3d11va-copy, vulkan-copy, no

**Linux:**
- **NVIDIA**: `nvdec,auto` (recommended) - NVDEC with fallback
- **AMD/Intel**: `auto` (recommended) - Auto-detection works well
- Other options: nvdec-copy, vaapi, vaapi-copy, vulkan, vulkan-copy, drm, drm-copy, no

**macOS:**
- `auto` (recommended for all GPUs) - VideoToolbox auto-detection
- Other options: videotoolbox, videotoolbox-copy, no

The `,auto` suffix provides a fallback mechanism - if the primary decoder fails, MPV falls back to automatic selection.

---

## Installation

### System Requirements

**CPU Compatibility:**

- **Windows x86_64**: x86-64-v2 (Sandy Bridge/Bulldozer 2011+)
  - Supported: Ryzen 1000+, Intel Core 2nd gen+
  - Required: POPCNT, SSE4.2

- **Linux x86_64**: x86-64-v2 or higher (Sandy Bridge/Bulldozer 2011+)

- **macOS Intel**: x86-64-v2 or higher (Sandy Bridge 2011+)

- **macOS Apple Silicon**: ARM64 (M1/M2/M3/M4)

**Operating Systems:**
- Windows 10 or later
- macOS 13 (Ventura) or later
- Linux (Nearly all distributions based on: Debian, Ubuntu, Fedora, Arch, OpenSUSE, etc.)


### Download

Visit https://mpv.rocks to download the binary for your platform.

### Arch Linux (AUR)

Community-maintained packages are available in the Arch User Repository:

- **[mpv-manager](https://aur.archlinux.org/packages/mpv-manager)** — Build from source
- **[mpv-manager-bin](https://aur.archlinux.org/packages/mpv-manager-bin)** — Pre-built binary
- **[mpv-manager-git](https://aur.archlinux.org/packages/mpv-manager-git)** — Git HEAD (development)

```bash
# Using paru
paru -S mpv-manager-bin

# Using yay
yay -S mpv-manager-bin
```

> **Note:** AUR builds have self-update disabled. Updates are managed by your package manager via `pacman -Syu`.

### Build from Source

```bash
git clone https://gitgud.io/mike/mpv-manager.git
cd mpv-manager

make deps
make build

./dist/mpv-manager
```

---

## Usage

### Web UI Mode (Default)

```bash
./mpv-manager
# or explicitly:
./mpv-manager web
```

The web interface will start and display a URL (typically http://localhost:6787).

### TUI Mode

```bash
./mpv-manager tui
```

Use arrow keys to navigate, Enter to select, and Ctrl+C to quit.

### CLI Mode

```bash
./mpv-manager cli --method mpv-binary --path /custom/path
```

CLI mode performs the same platform installer operation without starting the
Web UI or TUI. It validates that the method is available on the current OS,
streams installer output, supports Ctrl+C cancellation, records a successful
installation, and exits nonzero on fetch, validation, install, or persistence
failure. `--path` must be an absolute, writable, non-root destination; omit it
to use the configured/default install path.

### CLI Options

```bash
./mpv-manager --help          			# Show help
./mpv-manager --version       			# Show version
./mpv-manager tui             			# Start in TUI mode
./mpv-manager web             			# Start in Web UI mode (default)
./mpv-manager cli --method <method> # CLI installation
./mpv-manager tui --check-update  	# Check for manager updates
./mpv-manager tui --update       	# Update the manager
./mpv-manager --verbose      				# Verbose logging to console
./mpv-manager --debug         			# Detailed diagnostic output
./mpv-manager --web-port 8080 			# Custom port for Web UI
./mpv-manager --web-open=false 			# Don't auto-open browser
```

### Troubleshooting

If the installer crashes unexpectedly, run with debug mode:

```bash
./mpv-manager --debug
```

On Windows:
```powershell
.\mpv-manager-win-x86_64.exe --debug
```

**Common Issues:**

1. **Silent exit on Windows**
   - May be filesystem permissions or log file creation
   - Run with `--debug` to see error messages
   - Log locations:
     - Windows: `C:\Users\USER\mpv\portable_config\mpv-manager.log`
     - Linux/macOS: `~/.config/mpv/mpv-manager.log`

2. **CPU incompatibility**
   - Current binaries use x86-64-v2 baseline (Sandy Bridge 2011+)
   - Requires: POPCNT, SSE4.2
   - Supported: Ryzen 1000+, Intel Core 2nd gen+
   - If you get crashes, check if your CPU meets these requirements

3. **Windows Defender blocking**
   - May temporarily block the executable
   - Wait a few seconds and try again
   - Add exclusion for installer directory in Windows Defender

4. **GPU detection failures**
   - App will still work if GPU detection fails
   - Run with `--debug` to see GPU detection errors
   - GPU info is optional for basic functionality

5. **Web UI not loading**
   - Check if web server started (should show "Web UI running at http://localhost:port")
   - Ensure port isn't already in use
   - Refresh the page (F5 or Cmd+R)

---

## Updates

The installer handles updates for MPV and related applications.

### Manager Updates

Starting with v1.3, portable MPV Manager releases authenticate a signed release
manifest, stage and verify the complete update before exit, and use a copied
helper to replace the application only after the running process closes. If a
primary and configured secondary copy are both present, they commit or roll
back together.

Windows users upgrading from v1.2 or earlier must download v1.3 once and
replace the old executable manually. Those historical builds attempted to
rename their own running `.exe`, which Windows does not reliably allow. After
v1.3 is installed, later portable updates use the external-helper flow.

Package-manager builds delegate MPV Manager updates to their package manager
and disable raw self-update.

### Managed Apps

These track versions and can update automatically:

**Windows:**
- MPV Binary (mpv-binary, mpv-binary-v3)
- MPC-QT (mpc-qt)

**macOS:**
- MPV .app (mpv-app)
- IINA (iina)

**Package Manager Apps:**

These use system package managers:

- MPV via Homebrew (mpv-brew)
- MPV via Package Manager (mpv-package)
- MPV via Flatpak (mpv-flatpak)
- MPV via Snap (mpv-snap)
- Celluloid via Package Manager (celluloid-package)
- Celluloid via Flatpak (celluloid-flatpak)
- Celluloid via Snap (celluloid-snap)

### Config Updates

- **Load Latest Config**: Updates mpv.conf to the recommended version
- **Config Backup/Restore**: In "MPV Config Options" menu
  - Automatic backups with timestamps: `YYYY-MM-DD-HHMMSS_mpv.conf`
  - Stored in `~/.config/mpv/conf_backups/`
  - Select from list of backups to restore
  - Current config backed up before restore

### Update Behavior

**Managed Apps:**
- Downloads and installs the latest version
- Preserves your MPV configuration (doesn't overwrite mpv.conf)
- Updates version in installed_apps config

**Package Manager Apps:**
- Runs platform-specific update commands:
  - apt: `sudo apt update && sudo apt upgrade -y <APP>`
  - dnf: `sudo dnf makecache && sudo dnf upgrade -y <APP>`
  - pacman: `sudo pacman -Sy --noconfirm <APP>`
  - brew: `brew update && brew upgrade <APP>`
  - flatpak: `flatpak remote-ls --update && flatpak update <APP> -y`
  - snap: `sudo snap refresh <APP>`
- Shows live output in TUI/Web UI
- Preserves your MPV configuration

---

## Installation Methods

### Windows

- **MPC-QT** (recommended) - Easy GUI interface
- **MPV Binary** (recommended) - Managed installation (32-bit, 64-bit, AVX2, ARM64)

**Windows Features:**

**File Associations:**
- Batch files run in the background (non-blocking)
- Automatic UAC elevation for all operations
- Separate "Install" and "Remove File Associations" options
- Desktop shortcut created automatically
- After installation, choose **Install File Associations** on the MPV card in Player Apps. MPV Manager runs the installed mpv’s native `--register` operation (the same one used by the archive’s `mpv-register.bat`) and opens Windows Settings so you can choose file-type defaults. Run normally for registration in your user account; an already elevated manager uses mpv’s machine-wide registration.

**Console:**
- Auto-resized to 120x40 on startup
- Full menu visibility
- Success messages display correctly

**MPC-QT:**
- UAC prompt on install
- Silent uninstall with `/S` flag
- Clear status messages

**VBS Scripts:**
- Shortcut creation script auto-extracted to installer directory

### macOS

- **IINA** (recommended) - Modern MPV player for macOS
- **MPV .app** (recommended) - Official application bundle
- **MPV via Homebrew** - Command-line installation

### Linux

- **Celluloid** via Package Manager (recommended)
- **Celluloid Flatpak** (recommended)
- **MPV via Package Manager** (recommended)
- **MPV Flatpak** (for immutable distros)
- **MPV Snap**
- **MPV Binary** - Manual installation

---

## Configuration

The installer includes a pre-configured `mpv.conf` with optimized settings.

**Configuration includes:**
- Hardware acceleration enabled
- High quality scaling (spline36, ewa_lanczossharp, mitchell)
- GPU shaders (FSRCNNX upscaling, SSimDownscaler downscaling)
- uOSC modern on-screen controls
- Custom OSD with fonts, colors, and progress display
- Audio up to 200%, pitch correction
- Subtitle fuzzy loading, custom fonts and styling
- Auto-profiles for WEB-DL anime debanding, mini-encode detection

**Celluloid Configuration:**

For Celluloid (package manager and Flatpak):
- Auto-install `gsettings-desktop-schemas` if needed
- Configure Celluloid to load MPV config
- Disable MPV OSC to avoid conflict with Celluloid OSC
- Grant filesystem access to `~/.config/mpv/` for Flatpak

**Config Location:**
- Linux/macOS: `~/.config/mpv/mpv.conf`
- Windows portable: `C:\Users\USER\mpv\portable_config\mpv.conf`

**Backup:**
- Existing configs backed up with timestamp: `YYYY-MM-DD-mpv.conf.bak`
- Restore backups stored in `~/.config/mpv/conf_backups/`

---

## Language Preferences

Set audio and subtitle language priorities for MPV.

**How to use:**
1. Run `./mpv-manager` and select "Set Language Preferences"
2. Choose Audio or Subtitle languages
3. Select languages from the list (120+ available)
4. Filter by typing after pressing `/`
5. Add regional variants (e.g., English (US), English (UK))
6. Reorder with arrow keys
7. Confirm to apply

**Features:**
- 123+ languages with flag emojis
- Filter by name, local name, or code
- Regional variant support
- Priority ordering
- Saved to config file
- Updates mpv.conf with `alang` and `slang` settings

**Config location:**
- Linux/macOS: `~/.config/mpv/mpv-manager.json`
- Windows: `C:\Users\USER\mpv\portable_config\mpv-manager.json`

**MPV settings:**
- Audio priority: `alang=en,ja,fr`
- Subtitle priority: `slang=en,ja,fr`

---

## Security

The installer uses BLAKE3 cryptographic hashes to verify all downloads.

- BLAKE3 is faster and more secure than SHA256
- All downloaded files are verified against BLAKE3 hashes
- Complete coverage for uosc.zip and uosc.conf
- All 6 platform builds include verification (Linux AMD64/ARM64, Windows x86_64/ARM64, macOS Intel/ARM)

---

## Development

### Project Structure

```
mpv-manager/
├── cmd/
│   ├── mpv-manager/          # Main application
│   ├── generate-info/         # Release JSON generator
│   └── gen-checksums/        # BLAKE3 checksum generator
├── pkg/
│   ├── platform/             # Platform detection
│   ├── constants/           # Constants and config keys
│   ├── config/              # Configuration management
│   ├── version/             # Version management
│   ├── installer/           # Installation logic (platform-specific)
│   ├── locale/              # Language data (120+ languages)
│   ├── log/                # Logging infrastructure
│   ├── web/                # Web UI server and API
│   └── tui/                # TUI components (Bubbletea)
├── internal/
│   └── assets/             # Embedded config files (mpv.conf)
│   └── webassets/          # Web UI templates and static files
├── docs/                   # Comprehensive documentation
├── Makefile                # Build automation
├── go.mod                 # Go module definition
└── README.md              # This file
```

### Building

```bash
make build                       # Build for current platform
make build-linux                 # Build for Linux (amd64 + arm64)
make build-windows               # Build for Windows (x86_64 + arm64)
make build-macos                 # Build for macOS (Intel + ARM)
make build-all                   # Build ALL platforms
make release                     # Create release packages with checksums
make checksums                   # Generate BLAKE3 checksums

# Frontend contributors (Node.js 22 + npm)
make frontend-deps               # Install package-lock.json exactly
make frontend                    # Sync embedded htmx/Alpine and build Tailwind
```

Frontend dependency versions and update checks are documented in
[docs/FRONTEND_DEPENDENCIES.md](docs/FRONTEND_DEPENDENCIES.md). Release
binaries remain fully offline and do not load scripts from a CDN.

### Package Manager Builds

For distribution via package managers (Arch AUR, Homebrew, etc.), self-update should be disabled so the package manager handles updates:

```bash
# Build with self-update disabled (recommended for package managers).
# Official package recipes must also embed the public release-metadata key ring.
make build \
  MANIFEST_PUBLIC_KEYS='stable-2026-01=<base64-public-key>' \
  SELF_UPDATE_FLAG="-X 'gitgud.io/mike/mpv-manager/pkg/version.SelfUpdateDisabled=true'"

# Arch AUR convenience target
make build-aur
```

When `SelfUpdateDisabled=true`:
- Manager self-update is disabled in both Web UI and TUI
- The dashboard shows "Managed by Package Manager" instead of update controls
- MPV app updates (not manager updates) still work normally
- API endpoints return 403 Forbidden for manager update requests

**Cross-compilation:**
The Makefile supports building for all platforms from any OS:
- Linux builds: `make build-linux`
- Windows builds: `make build-windows`
- macOS builds: `make build-macos`
- All platforms: `make build-all`

### Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests
4. Ensure all tests pass
5. Submit a pull request

---

## Documentation

For detailed information about the project architecture, features, and development:

- 📚 [AGENTS.md](AGENTS.md) - Developer information, architecture, and implementation details for AI agents
- 📖 [docs/](docs/) - Comprehensive documentation directory with:
  - Architecture and design documentation
  - Platform-specific guides
  - Feature documentation
  - Testing procedures
  - Troubleshooting guides
  - Build and deployment guides

---

## License

MIT License - See [LICENSE](LICENSE) for details. Bundled dependency and
installed-script notices are listed in
[docs/THIRD_PARTY_NOTICES.md](docs/THIRD_PARTY_NOTICES.md).

---

## Links

- **Website**: https://mpv.rocks
- **GitGud**: https://gitgud.io/mike/mpv-manager
- **MPV**: https://mpv.io/
- **uOSC**: https://github.com/tomasklaen/uosc

---

## Acknowledgments

- [Bubble Tea v2](https://github.com/charmbracelet/bubbletea) - TUI framework
- [MPV](https://mpv.io/) - Media player
- [ModernZ](https://github.com/modernz/modernz) - Modern on-screen controller UI
- [uOSC](https://github.com/tomasklaen/uosc) - Modern on-screen controller
- [Thumbfast](https://github.com/po5/thumbfast) - Video thumbnail UI
- [Tailwind CSS](https://tailwindcss.com/) - Web UI styling
- [HTMX](https://htmx.org/) - Dynamic web interactions
- [Alpine.js](https://alpinejs.dev/) - Stateful Web UI components
- [BLAKE3](https://github.com/lukechampine/blake3) - Cryptographic hashing