mpvrc - MPV Remote Control

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.

Features

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.

Prerequisites

1. MPV with IPC support (any recent version)
2. Rust 1.92.0+ (or Nix for shell-based development)

Installation

From source

# Clone and build using a recent cargo version
$ git clone https://github.com/notashelf/mpvrc.git
$ cd mpvrc

# Build in release mode
$ cargo build --release

With Nix

The 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 --release

From crates.io

You can also get mpvrc from https://crates.io.

# Install to ~/.cargo/bin
$ cargo install mpvrc --locked

Quick Start

1. Start MPV with IPC

Using 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/mpvsocket

2. Control playback

Then, 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 interactive

CLI Options

Usage: 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

Commands

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

Shell Completions

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

Interactive Mode

$ 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> exit

Keyboard shortcuts in interactive mode:

• Ctrl+C - Interrupt current command
• Ctrl+L - Clear screen
• Ctrl+D - Exit (EOF)

Server Mode

Run MRC as a TLS-encrypted HTTP server for remote control:

1. Generate TLS certificates

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.pem

2. Configure environment

export TLS_PFX_PATH="./identity.pfx"
export TLS_PASSWORD="your_password"
export AUTH_TOKEN="your_secret_token"

3. Start server

mpvrc server --bind 127.0.0.1:8080 --socket /tmp/mpvsocket

4. Send commands

curl -k -H "Authorization: Bearer your_secret_token" \
     -d "play" https://127.0.0.1:8080/

Library Usage

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(())
}

Configuration

Environment Variables

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

Custom Socket Path

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 play

Building & Development

The 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

Troubleshooting

Socket not found

# Verify MPV is running with IPC
ls -la /tmp/mpvsocket

# Restart MPV with correct socket path
mpv --idle --input-ipc-server=/tmp/mpvsocket

Debug output

mpvrc -d interactive
# or
RUST_LOG=debug mpvrc interactive

License

This 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.