# 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** - Modern on-screen controller UIs like ModernZ and uosc (installed with MPV)

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

🔐 **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 10.14 (Mojave) 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 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 --check-update  			# Check for updates (TUI mode)
./mpv-manager --update       				# Update installer (TUI mode)
./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.

### 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
- File association setup launches after MPV binary install

**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:**
- 120+ 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
```

### 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)
make build 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.

---

## Links

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

---

## Acknowledgments

- [Bubbletea](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
- [BLAKE3](https://github.com/lukechampine/blake3) - Cryptographic hashing