Amarok/Archives/DBusFunctions
This page contains a draft of the D-Bus interface of Amarok 2 A Qt/C++ syntax is used instead of a XML interface definition because adding XML (+comments) to the wiki is not fun. Method names might change when we actually get around to implementing it.
Media Player Remote Interface Specification - an API that contains player control and playlist manipulation. Its been implemented by VideoLAN 0.9 so far.
Control interface
The interface org.kde.amarok.control provides methods to control the playback.
D-Bus methods
| bool isPlaying() | Returns true if Amarok is playing. |
| void play() | Tell Amarok to start playing. Does nothing if there is not anything to play. Unpauses paused songs. |
| void stop() | Tell Amarok to stop playing. Does nothing if Amarok is no playing. |
| void next() | Skip to the next song. Amarok will start playing the next song if it is currently playing. If Amarok is currently playing, but there is no next song, playback will stop. |
| void previous() | Change to the previous song. Amarok will start playing the previous song if it is currently playing. TODO: what happens if there is no previous song? |
| void stopAfterCurrentSong() | Stops playback after the current song has finished playing. Does nothing if Amarok is not playing any song. TODO: is there another way to implement this feature which does not require a special d-bus method? |
| void pause() | Pause playback. Does nothing if Amarok is not playing anything. Does nothing if Amarok is currently paused. TODO: can we pause streams? |
TODO: add methods for volume control/seeking
D-Bus signals
TODO: does it make more sense to sue one signal with an argument instead?
| void playing() | This signal is emitted when Amarok starts playing |
| void paused() | This signal is emitted when Amarok was paused |
| void stopped() | This signal is emitted when playback has stopped (both automatically and manually) |
Data interface
The interface org.kde.amarok.data provides method to access and change the metadata of songs.
D-Bus methods
| QString query(QString xmlquery) | Query Amarok's collections. The XML query will be based on the XML format Amarok uses to store smart playlists. It will be possible to define which values will be returned by Amarok. As all queries in Amarok are async, the return value is a generated key which can be used to identify the queryDone signal that was emitted for the query. |
| QMap<QString, QString> currentSong() | Get all known metadata for the current song. The keys of the map will be the field names that Nepomuk/Strigi use. |
| QMap<QString, QString> metaData(QString trackId) | Get all known metadata for the given track. TODO: decide if the argument should be Track::url(), Track::playableUrl(), Track::prettyUrl() or something else. |
| void setMetaData(QString trackId, QMap<QString, QString> metadata) | Set the metadata for the given track. See above for the meaning of trackId. Amarok will check all known the map for all known metadata. It will not change the track's metadata if the map does not contain a key. It will remove the tag from the track if the value of a key is empty, and change it to the value in the map otherwise. Amarok will do nothing if the trackId is unknown or if the track is not editable. |
D-Bus signals
| void queryDone(QString key, QList<QMap<QString, QString>> result) | This signal returns the results for a given query |
Playlist interface
TODO: add dbus methods/signals for manipulating the playlist