mpvrc is an unofficial command-line tool and library for controlling the mpv video player via its JSON IPC socket interface. Generally designed as a scriptable playback controller and a real-time interactive REPL in addition to a TLS-encrypted HTTP API for remote control. mpvrc has you covered for anything that is even vaguely related to controlling a MPV instance.
The project is equipped with various neat features such as, but not limited to:
- Full playback control: play, pause, stop, seek, skip, and playlist management
- Interactive REPL: vi-style editing, command history, and keyboard shortcuts
- HTTP server: TLS-encrypted remote control with token authentication
- Library API: use MRC as a Rust crate in your own projects
It's also async-first, for high-performance concurrency.
- MPV with IPC support (any recent version)
- Rust 1.92.0+ (or Nix for shell-based development)
# Clone and build using a recent cargo version
$ git clone https://github.com/notashelf/mpvrc.git
$ cd mpvrc
# Build in release mode
$ cargo build --releaseThe recommended way of building mpvrc is using Nix to acquire a developer shell.
# Clone and build using cargo from the provided shell
$ git clone https://github.com/notashelf/mpvrc.git
$ cd mpvrc
$ nix develop
$ cargo build --releaseYou can also get mpvrc from https://crates.io.
# Install to ~/.cargo/bin
$ cargo install mpvrc --lockedUsing mpvrc is quite simple. Start mpv with an IPC socket first:
# `/tmp/mpvsocket` is the default socket path for mpvrc
$ mpv --idle --input-ipc-server=/tmp/mpvsocketThen, once the socket is up, you may use mpvrc to control MPV.
# Play/pause
$ mpvrc play
$ mpvrc pause
# Navigation
$ mpvrc next
$ mpvrc prev
# Seek 2 minutes forward
$ mpvrc seek 120
# Add files to playlist
$ mpvrc add ~/Videos/movie.mkv ~/Videos/episode1.mkv
# View playlist
$ mpvrc list
# Interactive mode
$ mpvrc interactiveUsage: mpvrc [OPTIONS] <COMMAND>
Options:
-s, --socket <PATH> Path to MPV IPC socket [default: /tmp/mpvsocket]
-y, --yes Skip confirmation prompts for destructive commands
-d, --debug Enable debug logging
-h, --help Print help
-V, --version Print version
| Command | Description | Example |
|---|---|---|
play [index] |
Start/resume playback | mpvrc play or mpvrc play 2 |
pause |
Pause playback | mpvrc pause |
stop |
Stop and quit MPV | mpvrc stop |
next |
Skip to next playlist item | mpvrc next |
prev |
Skip to previous item | mpvrc prev |
seek <seconds> |
Seek to position in seconds | mpvrc seek 120 |
add <files...> |
Add files to playlist | mpvrc add a.mp3 b.mp3 |
remove [index] |
Remove item (default: current) | mpvrc remove 0 |
move <from> <to> |
Move playlist item | mpvrc move 0 3 |
clear |
Clear playlist | mpvrc clear |
list |
Show playlist | mpvrc list |
prop <props...> |
Get property values | mpvrc prop volume |
interactive |
Enter interactive REPL | mpvrc interactive |
completion <shell> |
Generate shell completions | mpvrc completion zsh |
Generate completions for your shell:
# Zsh
$ mpvrc completion zsh > ~/.zsh/completions/_mpvrc
# Bash
$ mpvrc completion bash > /etc/bash_completion.d/mpvrc
# Fish
$ mpvrc completion fish > ~/.config/fish/completions/mpvrc.fish$ mpvrc interactive
Entering interactive mode. Type 'help' for commands or 'exit' to quit.
Socket: /tmp/mpvsocket
mpv> play
mpv> seek 60
mpv> list
0 | Episode 1 | /path/to/episode1.mkv
> 1 | Episode 2 | /path/to/episode2.mkv
2 | Episode 3 | /path/to/episode3.mkv
mpv> exitKeyboard shortcuts in interactive mode:
Ctrl+C- Interrupt current commandCtrl+L- Clear screenCtrl+D- Exit (EOF)
Run MRC as a TLS-encrypted HTTP server for remote control:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
openssl pkcs12 -export -out identity.pfx -inkey key.pem -in cert.pemexport TLS_PFX_PATH="./identity.pfx"
export TLS_PASSWORD="your_password"
export AUTH_TOKEN="your_secret_token"mpvrc server --bind 127.0.0.1:8080 --socket /tmp/mpvsocketcurl -k -H "Authorization: Bearer your_secret_token" \
-d "play" https://127.0.0.1:8080/Add MRC to your Cargo.toml:
[dependencies]
mpvrc = "0.2"
tokio = { version = "1", features = ["full"] }
serde_json = "1"Control MPV from Rust:
use mpvrc::{get_property, playlist_next, set_property};
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Set volume
set_property("volume", &json!(75), None).await?;
// Get current filename
if let Some(filename) = get_property("filename", None).await? {
println!("Now playing: {}", filename);
}
// Skip to next track
playlist_next(None).await?;
Ok(())
}| Variable | Description | Required |
|---|---|---|
TLS_PFX_PATH |
Path to PKCS#12 certificate | Server |
TLS_PASSWORD |
Password for PKCS#12 file | Server |
AUTH_TOKEN |
Bearer token for authentication | Server |
Use -s or --socket to specify a different MPV socket:
# As of 0.3.0, mvrc supports custom socket path
$ mpvrc -s /var/run/mpv/socket playThe recommended developer setup for working with mpvrc is using Nix. Use
nix develop or direnv allow to enter a reproducible devshell with the
expected tooling, then work with Rust sources as usual:
# Build
$ cargo build
# Release build
$ cargo build --release
# Run tests
$ cargo test
# Lint
$ cargo clippy --all-targets# Verify MPV is running with IPC
ls -la /tmp/mpvsocket
# Restart MPV with correct socket path
mpv --idle --input-ipc-server=/tmp/mpvsocketmpvrc -d interactive
# or
RUST_LOG=debug mpvrc interactiveThis project is made available under Mozilla Public License (MPL) version 2.0. See LICENSE for more details on the exact conditions. An online copy is provided here.
