Introduction

Clementine can be controlled remotely over DBus. DBus 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 DBus. Clementine supports MPRIS versions 1 and 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:

The bus name identifying the application you want to talk to: org.mpris.clementine
The object path identifying which part inside that application you want. We used / to list the methods on the root object.
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 DBus 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 DBus 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)