mpv-kickstart

This mpv configuration serves as a solid foundation for your own setup. It aims for a lightweight, VLC-like desktop media-player experience without turning mpv into a large plugin bundle.

Requirements

• mpv 0.39 or newer. The bundled playlist manager requires mpv 0.39+.

Installation

To install these configuration files for your mpv player:

1. Locate your mpv configuration directory:
   • Windows: %APPDATA%\mpv
   • Linux and macOS: ~/.config/mpv
2. Clone this repository into that directory or copy the files manually.
3. Restart mpv.

Features and Plugins

• ModernZ: A clean and functional UI replacement for the default on-screen controller.
• thumbfast: Real-time, high-performance thumbnail previews while seeking.
• pause-indicator-lite: A minimal visual indicator for pausing and resuming.
• pip-lite: A lightweight Picture-in-Picture mode for multitasking.
• boxtowide: Automatic aspect ratio correction for 4:3 content.
• mpv-file-browser: Browse and open files or folders directly inside mpv without external dependencies.
• mpv-playlistmanager: Interactive playlist viewing, reordering, removing, saving, sorting, and shuffling.
• recent: Lightweight recently-played history and an interactive recent-files menu.

Automatic Plugin Updates

The bundled plugins are synchronized from their official upstream repositories every Monday by GitHub Actions. Plugin sources are declared in .github/plugin-sources.tsv, and tools/update-plugins.sh downloads or checks out each update and validates its Lua files before it can be committed.

The updater supports both single-file plugins and multi-file plugin bundles such as mpv-file-browser. Local script-opts customization is preserved. The updater only migrates known options when an upstream plugin removes or renames them. GitHub Actions dependencies are maintained separately by Dependabot.

To update and validate plugins manually:

bash tools/update-plugins.sh
bash tools/check.sh

CI validates shell scripts with ShellCheck, compiles every Lua file in the plugin tree for syntax errors, checks the plugin manifest and expected destinations, detects stale ModernZ options, and verifies that mpv.conf parses successfully.

Configuration Defaults

• Video: Quality-focused playback using vo=gpu-next, the high-quality profile, and automatic hardware decoding.
• Audio: Prefers 7.1, then 5.1, then stereo when the output device supports those layouts.
• Network: Lets mpv automatically enable caching when appropriate.
• Resume: Saves playback position on quit for a more traditional desktop-player experience.
• Tone Mapping: Uses BT.2446A for HDR-to-SDR conversion by default.

Customization

To learn more about how to tweak your mpv.conf file, check out these resources:

• Official mpv Manual: Configuration Files
• Community Guide: mpv-conf