mpv-ipc

Start or connect to the mpv media player and control it via IPC.

A Ruby library that provides a simple interface for interacting with mpv via its JSON IPC protocol.

This gem supports multiple usage patterns:

• starting and managing an mpv instance (IPC server + connected client),
• connecting to an already running mpv process as a plain IPC client,
• writing Ruby-based mpv scripts that are automatically launched at startup.

Installation

$ gem install mpv-ipc

This gem requires mpv to be installed separately.

Usage

For full documentation, please see the RubyDocs.

Check out mpv's property documentation for more details on supported properties and their usage.

Standalone session

This gem can be used to create a standalone mpv session, which starts and manages its own mpv instance and communicates with it via JSON IPC.

require "mpv_ipc"

# Initialize a new mpv session with both a Server and a Client
mpv = MPV::Session.new

# Observe changes in properties
mpv.observe_property("volume") do |prop_event|
  puts "Volume changed to: #{prop_event.data}"
end

# Interact with mpv
mpv.get_property "pause"
mpv.set_property "volume", 50.0
mpv.command "loadfile", "video.mkv"

sleep 10

# Exit mpv gracefully
mpv.quit!

Internally, MPV::Session instantiates and wires together an MPV::Server and an MPV::Client.

IPC client

Alternatively, the library can be used as a plain JSON IPC client to connect to an already running mpv process. This makes it suitable for both:

• external control tools that attach to an existing mpv instance, and
• scripts started and managed by mpv, communicating with it over IPC.

To use the gem as an mpv script, place the Ruby file in mpv's script configuration directory (e.g. $HOME/.config/mpv/scripts) with a .run suffix. It will automatically start the script at launch and provide the script with an IPC connection via --mpv-ipc-fd.

#!/usr/bin/ruby

require "mpv_ipc/client"

# Connect to an existing mpv process via its IPC socket
mpv = MPV::Client.new("/var/run/mpv.socket")

# Or initialize a Client using the IPC connection provided by mpv
# when running as an mpv-managed script (via --mpv-ipc-fd)
# mpv = MPV::Client.script

# Add a listener for the "seek" event
mpv.register_event_listener("seek") do |event|
  pos = mpv.get_property!("percent-pos")
  mpv.command("show-text", "Pos: %.2f%%" % pos)
end

# Register keybindings for zooming
mpv.register_keybindings("+", "-") do |key_event|
  if key_event.hold?
    zoom = mpv.get_property!("video-zoom")
    mpv.set_property!("video-zoom", zoom.send(key_event.key, 0.1).clamp(-4, 4))
  end
end

# Observe changes in the "video-zoom" property
mpv.observe_property("video-zoom") do |prop_event|
  mpv.command("show-text", "Zoom: %.0f%%" % (2 ** prop_event.data * 100))
end

# Wait until the connection closes
mpv.wait

All event-related callbacks are executed sequentially on the same dedicated internal thread to preserve event order. Handlers that may take longer can delegate their work to another thread or a new one.

OSD messages

For more advanced overlays, you can also create and edit styled OSD messages using the bundled Ass text helpers, with custom fonts, colors, text styles, alignment, and other formatting.

title = Ass::Span.new("Now playing")
title.bold.size(28).color(:gold).outline(2, :black)

body = Ass::Span.new("Interstellar")
body.italic.size(24).color(:white).outline(2, :black)

text = Ass::Text.new(title, "\n", body).align(:top_right)
id = mpv.create_osd_message(text)

body.content = "Inception"
mpv.edit_osd_message(id, text)

Compatibility

This library currently targets Unix-like systems and has been tested on Linux. Some features depend on Unix-specific IPC and process behavior, so Windows compatibility has not been implemented or tested yet.

This gem is based on the original ruby-mpv project and the extended fork.

Although this implementation differs from the original, it remains partially compatible with its API.