From Remuco

Contents 1 Introduction 2 Server Side API 2.1 Shell 2.1.1 Methods 2.1.1.1 Start 2.2 Server 2.2.1 Methods 2.2.1.1 Hello 2.2.1.2 UpdateState 2.2.1.3 UpdatePlob 2.2.1.4 UpdatePlaylist 2.2.1.5 UpdateQueue 2.2.1.6 Bye 3 Player Proxy Side API 3.1 Player 3.1.1 Methods 3.1.1.1 Control 3.1.1.2 RequestPlob 3.1.1.3 RequestPloblist 3.1.1.4 Bye

Introduction

This page specifies the server - player proxy - protocol version 2.

The protocol describes how the server and player proxies interact with each other. The interaction is based on D-Bus.

Server Side API

The server provides two D-Bus services: one to start the server (Shell service) and one to interact with the server (Server service).

Shell

The shell service is used to start the server. It is accessible via the following names:

• Service: net.sf.remuco.Shell
• Path: /net/sf/remuco/Shell
• Interface: net.sf.remuco.Shell

Methods

Start

Start the server and check server - player proxy compatibility.

Call this method once when the player proxy starts.

Input parameters:

Name	Type	Description
version	UINT32	The version of the server D-Bus API. Used to ensure server and player proxy have compatible versions. If there is a version mismatch, the server returns an error with code 2 and the message "incompatible server version". Set this to 2.

Server

The server service is used to interact with the server. Interaction basically means registering and unregistering players at the server and supply up-to-date player data (status, playlist, ...) to the server.

The server service is accessible via the following names:

• Service: net.sf.remuco.Server
• Path: /net/sf/remuco/Server
• Interface: net.sf.remuco.Server

Methods

Hello

Register a player at the server.

Call this method once when the player proxy starts.

Input parameters:

Name	Type	Description
player	STRING	Name of the media player. This name also specifies the name of the D-Bus service which must be provided by the player proxy. If for instance player is Foo, then the player proxy must be accessible via D-Bus with the following names: Service: net.sf.remuco.Foo Path: /net/sf/remuco/Foo Interface: net.sf.remuco.Foo Since the player name is also used for D-Bus names, it must conform to some D-Bus name restritcions. If the supplied name is not valid, an error is returned with code 1 and message "conveyed data is invalid".
flags	UINT32	Flags describing the player. Currently unused. Set this to 0.
rating	UINT32	Maximum rating the player accepts. Set this to 0 if the player does not support ratings.

UpdateState

Provide the server with status information about the player.

Call this method in a certain interval or whenever the status of the player changes.

Input parameters:

Name	Type	Description
player	STRING	Name of the player - must be the same used to say hello to the server.
playback	UINT32	Playback status. Value must be on of the following: 0 → stopped 1 → paused 2 → playing
volume	UINT32	Volume in percentage.
repeat	BOOLEAN	Whether repeat mode is enabled.
shuffle	BOOLEAN	Whether shuffle mode is enabled.
position	UINT32	Position of the current plob[1] in playlist or queue.
queue	BOOLEAN	Whether the player is currently playing from the queue or a regular playlist.

UpdatePlob

Provide the server with descriptive information about the current plob^[1].

Call this method in a certain interval or whenever the current plob changes.

Input parameters:

Name	Type	Description
player	STRING	Name of the player - must be the same used to say hello to the server.
id	STRING	Unique ID of the plob.
image	STRING	Path to an image related to the plob. Set to empty string if there is no image.
meta	DICT	Meta information about the plob arranged in a dictionary like structure. Keys and value must be strings. Use the following constants as keys: album artist bitrate comment genre length title track year rating → value must be something between "0" and the maximum rating used in method Hello tags → value must be a comma separated list of tags attached to the plob type → value must be one of the following audio video other There are no mandatory entries. Missing meta information is simply not displayed on the client. If there is no meta information available for the plob, it is a good idea to set at least the key title with a value like "Unknown".

UpdatePlaylist

Provide the server with the entries of the playlist.

Call this method in a certain interval or whenever the playlist changes.

Input parameters:

Name	Type	Description
player	STRING	Name of the player - must be the same used to say hello to the server.
ids	STRING ARRAY	List of unique IDs of the plobs in the playlist.
names	STRING ARRAY	List of names of the plobs in the playlist. A name is typically something like "Artist - Title".

UpdateQueue

Provide the server with the entries of the queue.

Call this method in a certain interval or whenever the queue changes (of course only if the player supports something like a queue).

Input parameters:

Name	Type	Description
player	STRING	Name of the player - must be the same used to say hello to the server.
ids	STRING ARRAY	List of unique IDs of the plobs in the queue.
names	STRING ARRAY	List of names of the plobs in the queue. A name is typically something like "Artist - Title".

Bye

Unregister a player from the server.

Call this method when the player proxy shuts down (not needed if the proxy shuts down because the server said bye).

Input parameters:

Name	Type	Description
player	STRING	Name of the player - must be the same used to say hello to the server.

Player Proxy Side API

Each player proxy must provide a D-Bus service as described below. This service is used by the server to interact with the player proxy.

Player

The B-Bus service must be accessible via the following names:

• Service: net.sf.remuco.Player
• Path: /net/sf/remuco/Player
• Interface: net.sf.remuco.Player

Player must be replaced by a specific player name. More precise: by the name used to say Hello to the server.

Methods

Control

Control the player.

Called by the server if a client issued a player control command.

Input parameters:

Name	Type	Description
control	UINT32	ID of the control command. May have one of the following values: 0 → a control command which must simply be ignored 1 → toggle play/pause 2 → stop playback 3 → switch to the next plob[1] 4 → switch to the previous plob 5 → jump to a specific plob (param_s contains the playlist to jump in and param_i contains the position in that playlist to jump to - if param_s is "__PLAYLIST__" or "__QUEUE__" this means to jump within the current playlist or queue, otherwise it specifies the unique ID of a certain ploblist which should be used as the new playlist) 6 → seek forward 7 → seek backward 8 → adjust the volume (param_i contains the new volume level (in percent)) 9 → rate the current plob (param_i contains the rating value) 10 → play a certain plob after the current one (param_s contains the unique ID of the plob to play next) 11 → currently unused, ignore this 12 → set tags of a plob (param_s contains the unique ID of the plob to set the tags for and the comma separated tags themselves in the following format: "ID:tag1,tag2,tag3,..") 13 → toggle repeat mode 14 → toggle shuffle mode
param_i	INT32	Optional integer argument. Meaning depends on control code (see above).
param_s	STRING	Optional string argument. Meaning depends on control code (see above).

RequestPlob

Get meta information about a plob.

Called by the server if a client requested information about a plob.

Input parameters:

Name	Type	Description
id	STRING	Unique ID of the plob. This is an ID supplied to the server previously by the player proxy when it called the server's UpdatePlaylist or UpdateQueue method or when the server requested a ploblist by calling the proxy's RequestPloblist method.

Output parameters:

Name	Type	Description
meta	DICT	Meta information about the specified plob. Format must be the same as described in the server's UpdatePlob method.

RequestPloblist

Get the contents of a ploblist. Next to plobs, a ploblist may also conatain nested ploblists.

Called by the server if a client requested to browse a ploblist.

Input parameters:

Name	Type	Description
id	STRING	Unique ID of the ploblist. This is either the empty string in which case all top level ploblists are requested or it is an ID supplied to the server when the server called this method previously.

Output parameters:

Name	Type	Description
nested_ids	STRING ARRAY	List of unique IDs of the ploblists nested within the specified ploblist. The IDs returned here may be later used by the server as method parameters when it calls this method or the Control method with the control command 5 (jump).
nested_names	STRING ARRAY	List of names of the ploblists nested within the specified ploblist.
nested_ids	STRING ARRAY	List of unique IDs of the plobs contained in the specified ploblist.
nested_ids	STRING ARRAY	List of names of the plobs contained in the specified ploblist. A name is typically something like "Artist - Title".

If the nested ploblists or contained plobs are not known, simply return empty string arrays or a ploblist containing one plob with a dummy ID and a name like "Content unkown".

Bye

Shutdown the proxy.

Called by the server if the player proxy should shut down. The reason for that may be that the server itself shuts down or that a user has requested the server to stop a certain player proxy.

During the resulting shut down process it is not necessary to call the server's Bye method.

There are no parameters involved in this method.

---

Footnotes

1. ↑ ^{1.1 1.2 1.3} Plob means playable object which can be a song, video, slide or anything else that can be played somehow.