ENOSUCHBLOG

Programming, philosophy, pedaling.

Mini-post: Introducing ruby-mpv

Jan 16, 2017 Tags: programming, ruby

Preword: I’ve decided to stop doing weekly muzak development posts, but I figured I would give a brief introduction to a new library that I spun off of muzak during its development.

First of all: mpv is a fantastic media player. It’s lightweight, flexible, embeddable, scriptable, and can be used for just about anything involving streams of audio and/or video. It’s simultaneously one of the most powerful programs in my toolbox and one of the easiest to use — not an easy feat.

I use it on a daily basis to watch YouTube videos (and every other source that youtube-dl supports) via the built-in ytdl_hook. I also have a few custom scripts to use mpv for things like video links in subreddits and pandora streaming. These take advantage of mpv’s excellent JSON IPC and Lars Gustäbel’s python-mpv library to provide fine-grained control of an mpv process.

This was all fine, but I wanted a (full) Ruby equivalent of python-mpv. Among other things, this meant supporting:

Real-time events (and callbacks for those events)
User control of arguments supplied to the mpv process
Isolation of the “client” from the “server” (for the situation in which an mpv process is already spawned and just needs to be connected to)

I found Stefan Dorn’s mpv-slave during my initial research, but it doesn’t seem to be actively developed and, more unfortunately, doesn’t support real-time events or client/server isolation.

Therefore, it was time for ruby-mpv:

require "mpv"

# an example class that we might want to interface with mpv
class Foo
  def bar(event)
    puts event
  end
end

foo = Foo.new

# a server/client pair
mpv = MPV::Session.new

# tell mpv to call this method from this object whenever an event occurs
mpv.callbacks << MPV::Callback.new(foo, :bar)

# issue a command to the mpv process
mpv.command "loadfile", "song.mp3", "append-play"

# terminate the MPV::Session
mpv.quit!

Internally, ruby-mpv is very simple - it’s just four classes:

MPV::Client - A “client” to an active mpv process, responsible for issuing commands and returning their responses, as well as propagating events via callback methods.
MPV::Server - A “server” that oversees an mpv process. Ensures that the process is spawned with the correct (user-supplied) arguments and remains alive.
MPV::Session - A client/server pair for when a new mpv process should be spawned for control. This is the most common use case.
MPV::Callback - An object/symbol pair that specifies a method to be called on the given object whenever MPV::Client receives an event. These can be added to a client instance via the callbacks accessor.

Full documentation of these classes is available on RubyDoc, or via yard:

$ git clone https://github.com/woodruffw/ruby-mpv
$ cd ruby-mpv
$ yard
$ ${BROWSER} doc/index.html

It’s also, of course, been published as a gem:

$ gem install mpv # require "mpv"

Happy hacking!

- William

Previously

Newer