View source for Developer:Davaar:PlaylistService

= Architectural Overview =

The Playlist service provides the means for controlling a Playlist source. If a product's [[Developer:Davaar:ProductService|Product Service]] reports a source of type 'Playlist', then the device that bears that [[Developer:Cara:ProductService|Product Service]] is guaranteed to also bears the Playlist service.

The Playlist source stores a user-modifiable list of tracks, which can be played starting at any point. Unless repeat mode has been engaged, the playlist will play to the end then stop. Shuffle mode causes playback to skip randomly through the playlist.

Largely, this service provides a database of tracks. You can read, insert, and delete entries in the playlist. Each entry in the playlist is given unique id.  This unique id is completely unrelated to the play order of the playlist.  The id of 0 is special and represents the empty playlist.

To insert, provide the id you wish to insert 'after' and the associated uri and metadata. The track is inserted into the correct position and the id of the new track is returned.  To insert in the first position in the playlist, insert after the special id of 0.

There are two read actions. One to read a single entry and the other to read a list of entries.

In the first, the uri and metadata of the requested id are returned. This operation can fail if the requested id does not exist in the playlist.

In the second, ReadList, a list of space separated decimal id's is provided and information concerning each is these tracks is returned in an xml format. ReadList does not fail. Requests for ids that are not in the playlist are silently ignored.

There are two variants of delete allowing the deletion of a single track or the deletion of the entire playlist. The former requires the id of the entry to delete. The latter takes no parameters. Both variants always succeed.


== IdArray ==

The Playlist service has a state variable called IdArray. This IdArray is a [http://en.wikipedia.org/wiki/Base64 base64] encoded array of 32 bit, big endian integers. It represents the ids as they are ordered in the playlist. An empty IdArray indicates an empty playlist.

For example the IdArray of:

<pre>0x00 0x00 0x00 0x02 0x00 0x00 0x00 0x14 0x00 0x00 0x00 0x13</pre> 

indicates a playlist of 3 tracks with the id's of 2, 20, and 19 in that order.

Control point authors are interested in both: 

* the order of tracks in the playlist, and
* the metadata of those tracks

Whether you acquire the IdArray via [[Developer:Davaar:PlaylistService#Events|events]] or [[Developer:Davaar:PlaylistService#Polling|polling]], you immediately know the order of the ids in the playlist.  What you don't necessarily know is the metadata for those ids.  

As the metadata for a large playlist can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience.  In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist.  Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the DS on completion of the insert action).  This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the playlist, the DS will event all subscribers the current IdArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, IdArray, reads the id array directly. This action also returns an IdArrayToken, which should be saved and periodically passed to a second action, IdArrayChanged, which reports whether or not your copy of the IdArray is out of date. If it is, calling IdArray again will ensure you have an up to date version.

= API Reference =

[http://oss.linn.co.uk/trac/browser/Main/LibUpnpCil/Services/Linn/Playlist.xml Playlist Service Description (XML)]

= Migration Guide =

In bute, playlist handling was part of the Media service.  All playlist functionality has moved to the Playlist service.  

In addition to this two major things have changed in Cara:

* Bute playlists relied on a sequence number to ensure consistency of the playlist.  This has been completely abandoned in favour of permanently unique track ids.  Actions now succeed or fail solely on the existence of that id -- not whether you hold the correct sequence number.  
* Bute playlist actions referenced the index or position of a track inside a playlist.  Cara playlist actions reference the unique id -- which is completely unrelated to it's position.  You can only determine the position of an id via the IdArray.  This means that multiple control points can successfully modify the playlist at the same time in a sensible fashion.

Bute playlist handling code will need to be refactored in line with the above.  However, our experience is that the resulting code will be substantially simpler and more efficient.