empeve/README.md

empeve - plugin manager for mpv

A plugin 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/empeve.git
cd empeve

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

# Browse popular scripts and add interactively
empeve browse -i

# Or add a specific repo
empeve add tomasklaen/uosc

# Install all configured repos
empeve install

# Update all repos to latest
empeve update

Usage

Adding Scripts

# Add from GitHub (user/repo shorthand)
empeve add tomasklaen/uosc

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

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

Installing & Updating

# Install all configured repos
empeve install

# Force reinstall
empeve install --force

# Install specific repo only
empeve install uosc

# Update all repos
empeve update

# Update specific repo
empeve update uosc

Managing Scripts

# Show status of all repos and targets
empeve status

# List installed scripts
empeve list

# List with details
empeve list --detailed

# Remove a repo from config
empeve remove tomasklaen/uosc

# Remove and uninstall scripts
empeve remove tomasklaen/uosc --purge

# Clean orphaned scripts and repos
empeve clean

Browsing Popular Scripts

# Browse all curated scripts
empeve browse

# Filter by category
empeve browse ui
empeve browse playback
empeve browse subtitles

# Interactive mode - select and add repos
empeve browse -i

Multi-Target Support

empeve can manage multiple mpv configurations simultaneously:

# Filter operations to specific target
empeve --target mpv install
empeve --target jellyfin-mpv-shim list
empeve -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/empeve/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/empeve/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/empeve/
├── config.toml
└── repos/
    ├── tomasklaen_uosc/
    └── po5_mpv_sponsorblock/

~/.config/mpv/scripts/
├── uosc -> ~/.config/empeve/repos/tomasklaen_uosc/src/uosc/
└── sponsorblock.lua -> ~/.config/empeve/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!