API/Player Protocol

From ickStream Wiki
Jump to: navigation, search

Contents

Principles

This page describes the protocol which needs to be implemented by all devices offering a Playback service. It's not the protocol for the actual playback, it's the protocol which is used to specify what should be played and reporting status changes related to what's currently playing.

The protocol consist of four different areas:

  • Player configuration/information - Methods to change player configuration and view other information about the player
  • Playback control - Methods to change start/stop playback and navigate in the current playback queue
  • Playback queue management - Methods to manage current playback queue
  • Notifications - Notifications which are generated when different type of states changes


The player should maintain a state sequence number that's incremented every time the state is changed, for example:

  • When a command modifies current playback queue or move current played position in the current playback queue
  • When a command changes between play/pause or adjusts volume
  • When the player by itself either changes between play/pause or move position in current playback queue to next track

On longer terms this sequence number might be exposed in the protocol, but it won't be exposed before we know that a typical controller actually have a need for it.


The player needs to keep track of two different playback queues

  • The current playback queue - Contains the tracks in the order they are about to be played
  • The originally ordered playback queue - Contains the tracks in the order that should be used when shuffle is not active

Both these playback queues contains exactly the same tracks with related data, it's only the order of the tracks that differs. All modifications are done to the current playback queue and it's the player responsibility to update the originally ordered playback queue. Both can be retrieved with the getPlaybackQueue method. The main purpose of the originally ordered playback queue is to make it possible to restore the originally order when the user switches from a shuffled to a non shuffled mode with the setPlaybackQueueMode method. It's documented in more detail in each separate method how they affect the originally ordered playback queue.


The player keeps a reference to the playlist or dynamic playlist which have been used to fill the current playback queue, the purpose of this reference is only a service to controllers to make it possible for a controller to show which playlist that's currently playing and do modifications in the current playback queue and later save these in the playlist.

For an introduction about what's needed to implement a player, see the separate Creating a player page.

Methods

Player configuration/information

The player configuration section provides the functions:

Playback control

The playback control section provides the functions:

Playback queue management

The playback queue management section provides the following functions:

  • setDynamicPlaybackQueueParameters - Set the parameters to be used when filling playback queue when the dynamic playback queue mode is active
  • getPlaybackQueue - Get list of tracks currently in the playback queue
  • setPlaylistName - Set reference to playlist which have been used to fill the playback queue
  • addTracks - Add one or several tracks to the playback queue
  • removeTracks - Remove one or several tracks from the playback queue
  • moveTracks - Move one or several tracks in the playback queue
  • setTracks - Replace playback queue with a new set of tracks
  • shuffleTracks - Shuffle tracks in current playback queue

Notifications

The following notifications are generated from a player

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox