MPRIS

From XMMS2
Jump to: navigation, search

Mpris.png

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 [[1]]

Definitions

"TrackList"

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"

  • "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
"location"
  • Stores an url to the media (local files are represented as a file:// url)

D-Bus

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

Identity

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:

  <method name="Identity">
    <arg type="s" direction="out"/>
  </method>

Quit

Makes the "Media Player" exit.

Introspection data:

  <method name="Quit">
  </method>

MprisVersion

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:

  <method name="MprisVersion">
    <arg type="(qq)" direction="out"/>
  </method>

/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

GetMetadata

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:

 <method name="GetMetadata">
   <arg type="i" direction="in" />
   <arg type="a{sv}" direction="out" />
 </method>

GetCurrentTrack

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:

  <method name="GetCurrentTrack">
    <arg type="i" direction="out" />
  </method>

GetLength

Number of elements in the TrackList

Return value:

Introspection data:

  <method name="GetLength">
    <arg type="i" direction="out" />
  </method>

AddTrack

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:

  <method name="AddTrack">
    <arg type="s" direction="in" />
    <arg type="b" direction="in" />
    <arg type="i" direction="out" />
  </method>

DelTrack

Removes an URI from the TrackList.

Arguments:

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

Introspection data:

  <method name="DelTrack">
    <arg type="i" />
  </method>

SetLoop

Toggle playlist loop.

Arguments:

  • boolean: TRUE to loop, FALSE to stop looping

Introspection data:

  <method name="SetLoop">
    <arg type="b" />
  </method>

SetRandom

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:

  <method name="SetRandom">
    <arg type="b" />
  </method>

/Player object methods

Next

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:

  <method name="Next">
  </method>

Prev

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

Introspection data:

  <method name="Prev">
  </method>

Pause

If playing : pause. If paused : unpause

Introspection data:

  <method name="Pause">
  </method>

Stop

Stop playing.

Introspection data:

  <method name="Stop">
  </method>

Play

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

Introspection data:

  <method name="Play">
  </method>

Repeat

Toggle the current track repeat.

Arguments:

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

Introspection data:

  <method name="Repeat">
    <arg type="b" />
  </method>

GetStatus

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:

  <method name="GetStatus">
  <arg type="(iiii)" direction="out"/>
  </method>

GetMetadata

Gives all meta data available for the currently played element.

Guidelines for field names are at http://xmms2.org/wiki/MPRIS_Metadata .

 <method name="GetMetadata">
   <arg type="a{sv}" direction="out" />
 </method>

GetCaps

Return the "media player"'s current capabilities.

  <method name="GetCaps">
    <arg type="i" direction="out" />
  </method>

RELATED:

  <signal name="CapsChange">
    <arg type="i" />
  </signal>


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

VolumeSet

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

  <method name="VolumeSet">
  <arg type="i"/>
  </method>

VolumeGet

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

  <method name="VolumeGet">
  <arg type="i" direction="out"/>
  </method>

PositionSet

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

  <method name="PositionSet">
  <arg type="i"/>
  </method>

PositionGet

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

  <method name="PositionGet">
  <arg type="i" direction="out"/>
  </method>

The signals

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

/Player object signals

TrackChange

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

  <signal name="TrackChange">
    <arg type="a{sv}"/>
  </signal>

StatusChange

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

  <signal name="StatusChange">
   <arg type="(iiii)"/>
  </signal>

CapsChange

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

  <signal name="CapsChange">
    <arg type="i" />
  </signal>

/TrackList object signals

TrackListChange

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.

  <signal name="TrackListChange">
    <arg type="i" />
  </signal>