Add comprehensive README with badges and documentation
- Project description and feature highlights - Installation instructions (from source) - Quick start guide and usage examples - Full commands reference with options - Multi-target support documentation - Configuration file format and options - How it works explanation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
236
README.md
Normal file
236
README.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# mpv-mgr
|
||||
|
||||
[](LICENSE)
|
||||
[](https://www.rust-lang.org/)
|
||||
[](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 <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!
|
||||
Reference in New Issue
Block a user