Media Player controls for Lua with Mpris and DBus

Use the DBus Media Player Remote Interfacing Specification (Mpris) to control your media player (e.g. VLC, QuodLibet).

Installation

Using Luarocks

Probably, the easiest way to install this widget is to use luarocks:

luarocks install media_player

You can use the --local option if you don't want or can't install it system-wide

This will ensure that all its dependencies are installed.

NixOS

If you are on NixOS, you can install this package from nix-stefano-m-overlays.

Usage

NOTE

This library leverages GLib's GIO GDBusProxy objects via dbus_proxy. That means that you must use the code inside a GLib main event loop for it to work. For example, use it with Awesome WM or create your own event loop.

Require the media_player module and then create a media player interface for each player that implements the Mpris specification.

When creating a media player with a given NAME, the module will attempt to connect to a DBus destination called org.mpris.MediaPlayer2.<NAME>.

A media player is created with

MediaPlayer = require("media_player")
player = MediaPlayer:new(name)

Use the is_connected attribute on the player object to check whether the corresponding application can controlled.

For example, say that we want to control vlc, but the application has not been started. In this case is_connected will be false and trying to access any attribute on the Proxy object will result in an error.

Instead, when is_connected is true, you can, for example, use the PlayPause, Stop, Previous and Next methods to control the player.

For more detail, see also the dbus_proxy documentation.

The Position property and position_as_str method return the position of the track in microseconds and as HH:MM:SS respectively.

The Metadata property returns the current track's metadata in a table as per the metadata specification.

The info method returns a subset of the metadata in a table with the following keys:

album: name of the album
title: title of the song
year: song year
artists: comma-separated list of artists (may be just one artist)
length: total lenght of the track as HH:MM:SS

See the generated documentation for more detailed information.

An example using the Awesome Window Manager

Require the media_player module in your Awesome configuration file ~/.config/awesome/rc.lua and then create a media player interface for each player that implements the Mpris specification.

You can create as many players as you want and bind them to different keys.

If you want to display information about the current track, you can use Metadata or info to extract it and then use it e.g. with Awesome's naughty.notify.

For example:

MediaPlayer = require("media_player")
quodlibet = MediaPlayer:new("quodlibet")
vlc = MediaPlayer:new("vlc")

Then you can bind the keys. In this example, the basic controls are set up, plus a notification and bindings to quit the application.

awful.util.table.join(
  -- QuodLibet bound to the media keys
  awful.key({}, "XF86AudioPlay", function () quodlibet.is_connected and quodlibet:PlayPause() end),
  awful.key({}, "XF86AudioStop", function () quodlibet.is_connected and quodlibet:Stop() end),
  awful.key({"Control"}, "XF86AudioStop", function () quodlibet.is_connected and quodlibet:Quit() end),
  awful.key({}, "XF86AudioPrev", function () quodlibet.is_connected and quodlibet:Previous() end),
  awful.key({}, "XF86AudioNext", function () quodlibet.is_connected and quodlibet:Next() end),
  -- modkey + i shows useful information from QuodLibet
  awful.key({modkey}, "i", function ()
      local info = quodlibet.is_connected and quodlibet:info() or
          {title = "quodlibet", album = "not available"}
      naughty.notify({title=info.title, text=info.album})
  end)
  -- VLC bound to modkey + media keys
  awful.key({modkey}, "XF86AudioPlay", function () vlc.is_connected and vlc:PlayPause() end),
  awful.key({modkey}, "XF86AudioStop", function () vlc.is_connected and vlc:Stop() end),
  awful.key({"Shift", "Control"}, "XF86AudioStop", function () vlc.is_connected and vlc:Quit() end),
  awful.key({modkey}, "XF86AudioPrev", function () vlc.is_connected and vlc:Previous() end),
  awful.key({modkey}, "XF86AudioNext", function () vlc.is_connected and vlc:Next() end)
)

Since Awesome calls the functions without passing the object as first parameter, we must wrap the call to the object's methods in an anonymous function.

Documentation

The documentation can be generated using LDoc. Running ldoc . in the root of the repository will generate HTML documentation in the docs directory.

stefano-m / lua-media_player