MPRIS - nesciens/xmms2-wiki GitHub Wiki

Version 1.0

MPRIS Media Player Remote Interfacing Specification

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 http://mpris.org/

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)

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

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

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

• / : Media Player identification

• /Player : Playback control

• /TrackList : TrackList management

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:

          

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 http://xmms2.org/wiki/MPRIS_Metadata .

Each dict entry is organized as follows

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

Arguments:

• 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:

• int: Number of elements in the TrackList

Introspection data:

          

Appends an URI in the TrackList.

Arguments:

• 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.

Arguments:

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

Introspection data:

          

Toggle playlist loop.

Arguments:

• boolean: TRUE to loop, FALSE to stop looping

Introspection data:

          

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

Arguments:

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

Introspection data:

          

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.

Arguments:

• 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 http://xmms2.org/wiki/MPRIS_Metadata .

       

Return the "media player"'s current capabilities.

          

RELATED:

          

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)

        

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

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.

          

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.