vikingowl
76fd3dda5d
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
236 lines
5.6 KiB
Markdown
236 lines
5.6 KiB
Markdown
# mpv-mgr
|
|
|
|
[](LICENSE)
|
|
[](https://www.rust-lang.org/)
|
|
|
|
A package 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 list
|
|
- **Per-repo targeting** - Install specific repos to specific targets
|
|
|
|
## Installation
|
|
|
|
### From source (recommended)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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`
|
|
|
|
```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](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!
|