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 (and extensible) list
• Per-repo targeting - Install specific repos to specific targets
• Pinned versions - Pin repos to specific commits or tags for stability
• Lockfile support - Create reproducible installations across machines
• Diagnostics - Built-in doctor command to diagnose and fix issues

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 (tracking - auto-updates)
empeve add tomasklaen/uosc --rev main

# Add with specific tag (pinned - won't auto-update)
empeve add tomasklaen/uosc --rev v5.0.0

# Add with specific commit (pinned - won't auto-update)
empeve add somerepo/script --rev abc123def456...

# 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

# Install using lockfile (exact versions)
empeve install --locked

# Update all repos (skips pinned repos)
empeve update

# Update specific repo
empeve update uosc

Managing Scripts

# Show status of all repos and targets
empeve status

# Show detailed status with per-target script info
empeve status --verbose

# 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

Lockfile for Reproducibility

# Create lockfile with current commit SHAs
empeve lock

# Install using exact versions from lockfile
empeve install --locked

The lockfile (~/.config/empeve/empeve.lock) records the exact commit for each repo, enabling reproducible installations across machines.

Converting Local Scripts

# Convert unmanaged local scripts to git-managed repos
empeve import --convert-local

# Convert a specific script by name
empeve import --convert-local --script my-script

This creates a local git repository for your scripts, enabling version control and empeve management.

Diagnostics

# Run diagnostic checks
empeve doctor

# Auto-fix issues where possible
empeve doctor --fix

The doctor command checks:

• Directory permissions
• Symlink support
• Repository health
• Target configuration
• Orphaned assets

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 (tracking), tag, or commit (pinned)
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
local	Mark as local-only repo (for converted scripts)

Revision Types

empeve automatically detects the type of revision:

Pattern	Type	Behavior
Branch name (e.g., main)	Tracking	Updates automatically
Tag (e.g., v1.2.3)	Pinned	Stays at version
Commit SHA (40 chars)	Pinned	Stays at commit
(none)	Tracking	Follows default branch

External Catalogs

You can add custom script catalogs by creating TOML files in ~/.config/empeve/catalogs/:

# ~/.config/empeve/catalogs/my-scripts.toml
[meta]
name = "My Custom Catalog"
version = "1.0.0"

[[entries]]
repo = "myuser/my-script"
name = "my-script"
description = "My awesome mpv script"
category = "utility"

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 (skips pinned)
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
doctor	Diagnose and fix setup issues
lock	Create lockfile with current commits

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
├── empeve.lock          # Lockfile (optional)
├── catalogs/            # Custom catalogs
│   └── my-scripts.toml
└── repos/
    ├── tomasklaen_uosc/
    ├── po5_mpv_sponsorblock/
    └── local/           # Converted local scripts
        └── my-script/

~/.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!