Controlling Clementine from the commandline with DBus and MPRIS
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.
MPRIS is a common API for controlling music players over D-Bus. Clementine supports MPRIS versions 1 and 2:
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 reallyIdentifyin 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.
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.
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.
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)