empeve/README.md

mpv-mgr

A package manager for mpv scripts. Manage your mpv scripts declaratively with simple commands - add repos, install, update, and keep everything in sync.

Features

• Declarative config - Define your scripts in config.toml, run install to sync
• Git-based - Scripts are cloned from GitHub (or any git URL) with shallow clones
• Multi-target support - Manage multiple mpv configs (mpv, jellyfin-mpv-shim, celluloid, etc.)
• Smart discovery - Automatically finds scripts, configs, fonts, and shaders in repos
• Symlink installation - Scripts stay in sync with upstream, easy to update
• Browse catalog - Discover popular mpv scripts from a curated list
• Per-repo targeting - Install specific repos to specific targets

Installation

From source (recommended)

# Clone the repository
git clone https://somegit.dev/vikingowl/mpv-mgr.git
cd mpv-mgr

# Build and install
cargo install --path .

Requirements

• Rust 1.70+ (for building)
• Git (for cloning repositories)

Quick Start

# First run - detects mpv configs and prompts for setup
mpv-mgr status

# Browse popular scripts and add interactively
mpv-mgr browse -i

# Or add a specific repo
mpv-mgr add tomasklaen/uosc

# Install all configured repos
mpv-mgr install

# Update all repos to latest
mpv-mgr update

Usage

Adding Scripts

# Add from GitHub (user/repo shorthand)
mpv-mgr add tomasklaen/uosc

# Add with specific branch/tag
mpv-mgr add tomasklaen/uosc --rev v5.0.0

# Add only specific scripts from a multi-script repo
mpv-mgr add po5/mpv_sponsorblock --scripts sponsorblock.lua

Installing & Updating

# Install all configured repos
mpv-mgr install

# Force reinstall
mpv-mgr install --force

# Install specific repo only
mpv-mgr install uosc

# Update all repos
mpv-mgr update

# Update specific repo
mpv-mgr update uosc

Managing Scripts

# Show status of all repos and targets
mpv-mgr status

# List installed scripts
mpv-mgr list

# List with details
mpv-mgr list --detailed

# Remove a repo from config
mpv-mgr remove tomasklaen/uosc

# Remove and uninstall scripts
mpv-mgr remove tomasklaen/uosc --purge

# Clean orphaned scripts and repos
mpv-mgr clean

Browsing Popular Scripts

# Browse all curated scripts
mpv-mgr browse

# Filter by category
mpv-mgr browse ui
mpv-mgr browse playback
mpv-mgr browse subtitles

# Interactive mode - select and add repos
mpv-mgr browse -i

Multi-Target Support

mpv-mgr can manage multiple mpv configurations simultaneously:

# Filter operations to specific target
mpv-mgr --target mpv install
mpv-mgr --target jellyfin-mpv-shim list
mpv-mgr -t mpv status

Supported targets (auto-detected on first run):

• mpv - Standard mpv (~/.config/mpv)
• jellyfin-mpv-shim - Jellyfin MPV Shim
• celluloid - Celluloid (GNOME MPV frontend)
• mpv-flatpak - Flatpak mpv installation

Configuration

Config file location: ~/.config/mpv-mgr/config.toml

[settings]
use_symlinks = true    # Use symlinks instead of copying
shallow_clone = true   # Shallow clone repos (faster)

[[targets]]
name = "mpv"
path = "/home/user/.config/mpv"
enabled = true

[[targets]]
name = "jellyfin-mpv-shim"
path = "/home/user/.config/jellyfin-mpv-shim"
enabled = true

[[repos]]
repo = "tomasklaen/uosc"

[[repos]]
repo = "po5/mpv_sponsorblock"
targets = ["mpv"]  # Only install to mpv, not jellyfin

[[repos]]
repo = "jonniek/mpv-playlistmanager"
rev = "master"
scripts = ["playlistmanager.lua"]  # Only this script

Repo Options

Option	Description
repo	Repository identifier (user/repo or full git URL)
rev	Branch, tag, or commit to checkout
scripts	Only install specific scripts from the repo
targets	Only install to specific targets (default: all)
rename	Rename the script when installing
disabled	Disable without removing from config

Commands Reference

Command	Description
add <repo>	Add a repository to config
remove <repo>	Remove a repository from config
install	Clone repos and install scripts
update	Update all repositories
clean	Remove orphaned scripts and repos
status	Show status of repos and targets
list	List installed scripts
browse	Browse popular mpv scripts
import	Import existing scripts (coming soon)

Global Options

Option	Description
-c, --config <PATH>	Custom config file path
-t, --target <NAME>	Filter operations to specific target
-v, --verbose	Verbose output

How It Works

1. Repos are cloned to ~/.config/mpv-mgr/repos/
2. Scripts are symlinked to your mpv scripts directory
3. Assets (fonts, shaders, script-opts) are also symlinked
4. Updates pull latest changes, symlinks stay valid

~/.config/mpv-mgr/
├── config.toml
└── repos/
    ├── tomasklaen_uosc/
    └── po5_mpv_sponsorblock/

~/.config/mpv/scripts/
├── uosc -> ~/.config/mpv-mgr/repos/tomasklaen_uosc/src/uosc/
└── sponsorblock.lua -> ~/.config/mpv-mgr/repos/po5_mpv_sponsorblock/sponsorblock.lua

License

MIT License - see LICENSE for details.

Acknowledgments

Inspired by vim-plug and the mpv scripting community.

Popular scripts in the browse catalog come from amazing creators - check out their repos!