vikingowl/empeve
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be61df8a0b7bb5dd1762641e6eeec0c173da898
empeve/README.md
vikingowl 6f714e58fa Implement comprehensive improvement roadmap (Phases 0-4) 
Phase 0 - Quick fixes:
- Fix catalog entries() return type (removed extra indirection)
- Fix welcome string (mpv-mgr → empeve)
- Fix HEAD detachment on update (branch-aware fast-forward)
- Add fetch_rev with branch detection

Phase 1 - Git model ("rev means rev"):
- Add RevType enum (Commit/Tag/Branch/Default)
- Add UpdateResult enum for update outcomes
- Implement clone_with_rev for proper revision checkout
- Pinned repos (commits/tags) skip auto-update

Phase 2 - Discovery & install fidelity:
- Support init.lua and named entry points for multi-file scripts
- Better asset mapping with prefix matching for configs
- Proactive target directory creation

Phase 3 - UX and quality-of-life:
- Add --verbose flag to status command
- Add 'empeve doctor' diagnostic command
- Improve error messages with actionable hints

Phase 4 - Feature expansion:
- External TOML catalog system (extensible)
- Import --convert-local for local script management
- Lockfile support for reproducible installations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-15 03:44:37 +01:00

328 lines
8.1 KiB
Markdown
Raw Blame History

# empeve - plugin manager for mpv
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
A plugin manager for [mpv](https://mpv.io/) 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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`
```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/`:
```toml
# ~/.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](LICENSE) for details.
## Acknowledgments
Inspired by [vim-plug](https://github.com/junegunn/vim-plug) and the mpv scripting community.
Popular scripts in the browse catalog come from amazing creators - check out their repos!
Reference in New Issue View Git Blame Copy Permalink