Skip to content
nesciens edited this page Apr 15, 2018 · 2 revisions


Version 1.0

MPRIS Media Player Remote Interfacing Specification

Current version and official website

This page documents MPRIS version 1.0, which is now outdated. The most current specification of versions 2.1 or newer can be found on



The "TrackList" must:

  • Hold an ordered list of locations of the media files as URIs (e.g. file://, http://, mms:// ...).
  • Keep the list in an ordered fashion. The order can be changed at any time trough e.g. sorting algorithms, in which case the "Media Player" must send information about the reordering with the "TrackListChange" signal.

The "Tracklist" holds "Metadata" about media:


  • "Metadata" represents the informations associated with a media, such as its name, its performer, its length ...
  • "Metadata" is an array of dict entries in the form (string, variant) eg: {sv}.
  • There is only one mandatory field : location
  • The list of optional fields is on MPRIS_Metadata
  • Stores an url to the media (local files are represented as a file:// url)


Naming conventions

Each player requests an unique name beginning with org.mpris. For example:

  • org.mpris.audacious
  • org.mpris.bmp
  • org.mpris.vlc
  • org.mpris.xmms2

The Interface

All methods must be accessed through the interface org.freedesktop.MediaPlayer

The Object Hierarchy

  • / : Media Player identification
  • /Player : Playback control

The Methods

/ (Root) object methods


Identify the "media player" as in "VLC 0.9.0", "bmpx 0.34.9", "Audacious 1.4.0" ...

Return value:

  • string: Returns a string containing the media player identification.

Introspection data:



Makes the "Media Player" exit.

Introspection data:



Returns a struct that represents the version of the MPRIS spec being implemented, organized as follows:

  • uint16 major version (Existing API change)
  • uint16 minor version (API addition)

Introspection data:


/TrackList object methods

Note that if CAN_HAS_TRACKLIST is false, the methods described below must be implemented as no-ops, except GetMetadata (which is valid only if given argument is 0), GetCurrentTrack (which always returns 0), GetLength (which will return 0 or 1), and AddTrack


Gives all meta data available for element at given position in the TrackList, counting from 0.

Guidelines for field names are at .

Each dict entry is organized as follows

  • string: Metadata item name
  • variant: Metadata value.


  • int: Position in the TrackList of the item of which the metadata is requested

Return value:

  • string - variant dict: Metadata.

Introspection data:



Return the position of current URI in the TrackList The return value is zero-based, so the position of the first URI in the TrackList is 0. The behavior of this method is unspecified if there are zero elements in the TrackList.

Return value:

  • int: Position in the TrackList of the active element.

Introspection data:



Number of elements in the TrackList

Return value:

Introspection data:



Appends an URI in the TrackList.


  • string: The uri of the item to append.
  • boolean, TRUE if the item should be played immediately, FALSE otherwise

Return value:

  • int: 0 means Success

Introspection data:



Removes an URI from the TrackList.


  • int: Position in the tracklist of the item to remove.

Introspection data:



Toggle playlist loop.


  • boolean: TRUE to loop, FALSE to stop looping

Introspection data:



Toggle playlist shuffle / random. It may or may not play tracks only once.


  • boolean: TRUE to play randomly / shuffle playlist, FALSE to play normally / reorder playlist

Introspection data:


/Player object methods


Goes to the next element (What if we're at the end? -- NOTE Nothing terrible needs to happen, the player should just ignore it. However UIs, and maybe not only UIs, can receive a hint as to whether there is a next track using the Caps API)

Introspection data:



Goes to the previous element (what if we're at the beginning? See above)

Introspection data:



If playing : pause. If paused : unpause

Introspection data:



Stop playing.

Introspection data:



If playing : rewind to the beginning of current track, else : start playing.

Introspection data:



Toggle the current track repeat.


  • boolean: TRUE to repeat the current track, FALSE to stop repeating.

Introspection data:



Return the status of "Media Player" as a struct of 4 ints:

  • First integer: 0 = Playing, 1 = Paused, 2 = Stopped.
  • Second interger: 0 = Playing linearly , 1 = Playing randomly.
  • Third integer: 0 = Go to the next element once the current has finished playing , 1 = Repeat the current element
  • Fourth integer: 0 = Stop playing once the last element has been played, 1 = Never give up playing

Return value:

  • (iiii): Status

Introspection data:



Gives all meta data available for the currently played element.

Guidelines for field names are at .



Return the "media player"'s current capabilities.




CAN_GO_NEXT There is a current next track, or at least something that equals to it (that is, the remote can call the 'Next' method on the interface, and expect something to happen, heh)
CAN_GO_PREV Same as for NEXT, just previous track/something
CAN_PAUSE Can currently pause. This might not always be possible, and is yet another hint for frontends as to what to indicate
CAN_PLAY Whether playback can currently be started. This might not be the case if e.g. the playlist is empty in a player, or similar conditions. Here, again, it is entirely up to the player to decide when it can play or not, and it should signalize this using the caps API.
CAN_SEEK Whether seeking is possible with the currently played stream (UIs/frontends can then enable/disable seeking controls)
CAN_PROVIDE_METADATA Whether metadata can be acquired for the currently played stream/source using GetMetadata at all.
CAN_HAS_TRACKLIST Whether the media player can hold a list of several items

Note that the caps are a bitfield, currently defined as:

         NONE                  = 0,          CAN_GO_NEXT           = 1 << 0,          CAN_GO_PREV           = 1 << 1,          CAN_PAUSE             = 1 << 2,          CAN_PLAY              = 1 << 3,          CAN_SEEK              = 1 << 4,          CAN_PROVIDE_METADATA  = 1 << 5,          CAN_HAS_TRACKLIST     = 1 << 6


Sets the volume (argument must be in [0;100])



Returns the current volume (must be in [0;100])



Sets the playing position (argument must be in [0;<track_length>] in milliseconds)



Returns the playing position (will be [0;<track_length>] in milliseconds)


The signals

Signals must be emitted from org.freedesktop.MediaPlayer interface.

/Player object signals


Signal is emitted when the "Media Player" plays another "Track". Argument of the signal is the metadata attached to the new "Track"



Signal is emitted when the status of the "Media Player" change. The argument has the same meaning as the value returned by GetStatus.



Signal is emitted when the "Media Player" changes capabilities, see GetCaps method.


/TrackList object signals


Signal is emitted when the "TrackList" content has changed:

  • When one or more elements have been added
  • When one or more elements have been removed
  • When the ordering of elements has changed

The argument is the number of elements in the TrackList after the change happened.


Clone this wiki locally
You can’t perform that action at this time.