View source for DBus-spec

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

<span style="color: red; font-weight: bold">THIS IS A DRAFT</span>

<span style="color: red; font-weight: bold">VLC DOES NOT USE THAT AT THIS MOMENT ALTHOUGH IT IS PLANNED</span>

'''TODO''': video? network? signals?

What follows has been largely stolen from http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

This is an attempt to create a specification for media players to use, for '''YOUR''' 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, most notably D-Bus : http://dbus.freedesktop.org and uses ideas from http://www.musicbrainz.org

= 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, like MPRIS or VLC, or Rhythmbox, or mplayer, or xine, or Totem, or anything '''YOU''' like.

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

== "Client" ==

The Client is an unspecified application that will interact with the "Media Player" using D-Bus protocol.
For example a Client could be a softphone, that pauses, or step the volume down, when a call is being received.
A Client could be an applet that nicely integrates in '''YOUR''' desktop environment, and let '''YOU''' control '''YOUR'''' "Media Player".

== "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 an ordered 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: ( to be implemented with a struct )
* Length in seconds
* (seekable?) (the management of unseekable should go in error management of SetStreamPos)
* codec defined as a fourcc (http://www.fourcc.org has only video codecs)
* bitrate
* samplerate
* (video?)
* (local/network?)
* (filesize?)

2) Informational metadata ( to be implemented as an array of dict entries )
* Name
* Artist
* Compilation/Album
* Unique Identifier as on http://musicbrainz.org
* Genre
* Comments specific to the "Media Player", like vorbis comments. On the base

= D-Bus =

== The Service ==

org.freedesktop.MediaPlayer

== The Object Hierarchy ==

* / : Media Player identification

* /Player : Playback control

* /TrackList : TrackList management

== The Methods ==


* /

Identity : Identify the "Media Player" as in "VLC 0.9.0", "bmpx 0.34.9", "Totem 2.16.2" ...

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

* /TrackList

GetMetadataForUri : Gives all meta data available for given URI (= MRL)

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

GetCurrentUri : Gives Current URI played by the "Media Player"

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

GetCurrentTitle : Gives Title of Current URI (Duplicate with GetMetadataForUri)

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

GetCurrentTrack : Position of Current URI in the "TrackList"

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

* /Player

PlayNext : Goes to the next element (what if we're at the end?)

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

PlayPrev : Goes to the previous element (what if we're at the beginning?)

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

PlayPause : If playing : pause. If paused : unpause. If stopped : start playing

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

PlayStop : Stop playing.

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

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

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

SendStatus : ?

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

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>

Quit : Makes the "Media Player" exit.
 
   <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>