diff --git a/README.md b/README.md new file mode 100644 index 0000000..c6aaba7 --- /dev/null +++ b/README.md @@ -0,0 +1,236 @@ +# mpv-mgr + +[![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/) +[![GitHub](https://img.shields.io/badge/GitHub-cnachtigall%2Fmpv--mgr-lightgrey.svg)](https://github.com/cnachtigall/mpv-mgr) + +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://github.com/cnachtigall/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 ` | Add a repository to config | +| `remove ` | 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 ` | Custom config file path | +| `-t, --target ` | 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!