View source for DBus-spec

Specification for a Common, Desktop neutral, Media Player D-Bus interface

= Definitions =

== "Media Player" ==

An application, either with GUI or GUI-less (or which allows for both modes of operation) which is capable of playing back audio streams. The means by which it does accomplish that (e.g. which audio backend to use, and which output method) is completely up to the application, and is not part of the MPRIS.
<br/><br/>
The "Media Player" '''must''':
* Be able to play back at least local storage file streams.
* Be able to play back at least one stream at a time (as in, without having a concept of a "Tracklists", and possibly even being capable of holding several at the same time)

The "Media Player" '''can''', but does not '''need''' to:
* Be capable of holding one or more "Tracklists" at a time.

== "Tracklist" ==

A list of media files which resides within the "Media Player", and whose implementation is opaque to the remote interface.

The "Tracklist" '''must''':
* Hold a list of locations of the media files as URIs (e.g. file:// or <nowiki>http://</nowiki>). The implementation of this can be opaque, which means, it does not neccesarily need to store URIs, but upon remote request, it must be able to return an URI for a given media file.
* 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 trough it's remote interface

The "Tracklist" '''can''', but does not '''need''' to:
* Hold "Metadata" about media files

== "Metadata" ==

"Metadata" is data that the files carry within themselves as a means of self-identification (commonly known as "tags"), or data that has been retrieved about the files trough other means, e.g. an internet service that provides additional data about particular media files.

Furthermore, "Metadata" can be split into two categories:

1) Technical metadata (as in, bitrate, samplerate, length of the track/media file)

2) Informational metadata (as in, artist, album, title, genre etc)

= Current State =
As of current, MPRIS is a '''draft''', even though libmpris exists and works (although it is still being worked on).
<br/><br/>
It being a draft means that basically everything can still change until we say we're at version 1 of MPRIS, but it is '''rather unlikely''' that the specified DBus interface will change (see below).
<br/><br/>
Also, we consider BMPx to be a reference implementation of MPRIS. (We might, however, in the future write a simple media player which will replace BMPx as the MPRIS reference application, since BMPx is rather heavyweight and complex.)


Please refer to http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

This is my attempt to create a specification for media players to use, for other applications to be able to interact with '''ANY''' Media Player '''YOU''' want to use on '''ANY''' desktop '''YOU''' want to use.

This is in the spirit of http://www.freedesktop.org and uses code and ideas from this project.

= D-Bus =

== The Service ==

org.freedesktop.MediaPlayer

== The Object Paths ==

* /

== The Methods ==

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

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

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

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

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

   <method name="PlayNext">
   </method>

   <method name="PlayPrev">
   </method>

   <method name="PlayPause">
   </method>

   <method name="PlayStop">
   </method>

   <method name="PlayCurrent">
   </method>

   <method name="SendStatus">
   </method>

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

== The signals ==

   <signal name="TrackChange">
   </signal>

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

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

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