Controlling Clementine from the commandline with DBus and MPRIS

Introduction

Clementine can be controlled remotely over D-Bus. D-Bus is a message bus that lets applications on Linux talk to each other. It replaces DCOP that was used by KDE 3 and Amarok 1.4.

This guide will show you how to control Clementine from the commandline and from Python scripts.

The specifications

MPRIS is a common API for controlling music players over D-Bus. Clementine supports MPRIS versions 1 and 2:

• MPRIS 1
• MPRIS 2

Using the command line

Clementine has two names on the bus: org.mpris.clementine (the MPRIS 1 interface) and org.mpris.MediaPlayer2.clementine (for MPRIS 2). You can use the qdbus application to explore which objects and methods are available on each one, for example:

$ qdbus org.mpris.clementine

/
/Player
/TrackList
/org
/org/mpris
/org/mpris/MediaPlayer2

$ qdbus org.mpris.clementine /

method QString org.freedesktop.MediaPlayer.Identity()
method void org.freedesktop.MediaPlayer.Quit()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method QVariantMap org.freedesktop.DBus.Properties.GetAll(QString interface_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()

$ qdbus org.mpris.clementine / org.freedesktop.MediaPlayer.Identity

Clementine 0.7

You can see that you need to give 3 things when you use qdbus:

1. The bus name identifying the application you want to talk to: org.mpris.clementine
2. The object path identifying which part inside that application you want. We used / to list the methods on the root object.
3. The method name that you want to call: org.freedesktop.MediaPlayer.Identity. The method name is only really Identify in this case - everything before the final dot is known as the interface name.

qdbus is great for finding out what methods are available on D-Bus objects. It also supports tab completion.

What song is playing now?

The GetMetadata MPRIS 1 method gives you information about the currently playing song:

$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.GetMetadata

album: Monty Python Sings
artist: Monty Python
arturl: file:///tmp/clementine-art-PE4553.jpg
audio-bitrate: 128
audio-samplerate: 44100
location: file:///stuff/Music/Monty Python/Monty Python Sings/Eric The Half A Bee.mp3
mtime: 129000
time: 129
title: Eric The Half A Bee
tracknumber: 14

Using MPRIS 2 to get metadata is a little more difficult because it's exposed as a D-Bus property instead of a method that returns information. You have to call the org.freedesktop.DBus.Properties.Get method and give it the name of the property you want to get as an argument:

$ qdbus org.mpris.MediaPlayer2.clementine /org/mpris/MediaPlayer2 org.freedesktop.DBus.Properties.Get org.mpris.MediaPlayer2.Player Metadata

mpris:artUrl: file:///tmp/clementine-art-PE4553.jpg
mpris:length: 129000000
mpris:trackid: /org/mpris/MediaPlayer2/Track/27
xesam:album: Monty Python Sings
xesam:artist: Monty Python
xesam:autoRating: 50
xesam:contentCreated: 2011-01-03T23:41:27
xesam:lastUsed: 2011-04-01T01:40:23
xesam:title: Eric The Half A Bee
xesam:trackNumber: 14
xesam:url: file:///stuff/Music/Monty Python/Monty Python Sings/Eric The Half A Bee.mp3

Both MPRIS 1 and MPRIS 2 work in Clementine so you can use whichever one you prefer, although MPRIS 1 is usually a bit more straightforward.

Controlling playback

The /Player object has a load of methods like Play, Pause, PlayPause, Stop, Next and Prev that can be used to control the player:

$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.Pause

Some methods, like VolumeSet, take an argument. You just pass this to qdbus after the method name:

$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.VolumeSet 50
$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.VolumeSet 100

See the MPRIS specifications for information about the other methods that Clementine supports.

Using Python

It's easy to use the dbus python module to control Clementine from a Python script.

import dbus

# Clementine lives on the Session bus
session_bus = dbus.SessionBus()

# Get Clementine's player object, and then get an interface from that object,
# otherwise we'd have to type out the full interface name on every method call.
player = session_bus.get_object('org.mpris.clementine', '/Player')
iface = dbus.Interface(player, dbus_interface='org.freedesktop.MediaPlayer')

# Call a method on the interface
metadata = iface.GetMetadata()
print metadata["title"]
print metadata["artist"]

Notice we're calling the same GetMetadata method as we did in the section above with the commandline. It gives us back a dictionary that contains the same information that qdbus printed out before.

Controlling the player is done in the same way, we just call a different method on that interface:

iface.Play()
iface.Pause()
iface.VolumeSet(50)