Developer:Davaar:PlaylistService

Architectural Overview

The Playlist service provides the means for controlling a Playlist source. If a product's Product Service reports a source of type 'Playlist', then the device that bears that 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 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:

0x00 0x00 0x00 0x02 0x00 0x00 0x00 0x14 0x00 0x00 0x00 0x13

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

Actions

IdArray

Report the current id array.

The IdArray is an ordered array of ids that represent each track in the playlist.

This action also reports a Token, which can be used to quickly detect if the id array has changed since it was last read (see IdArrayChanged).

IdArrayChanged

Check to see if the id array has changed since gathering the specified Token. This Token must have been previously collected from the IdArray action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

TracksMax

Report the maximum number of tracks in the id array.

Id

Report the Id of the current track. If the reported id is zero, the playlist is empty.

ProtocolInfo

Report the Playlist source protocol info.

Read

Given a track Id, report its associated Uri and Metadata.

ReadList

Given a space separated list of track Id's, report their associated Uri and Metadata in the following xml form:

 <TrackList>
   <Entry>
     <Id></Id>
     <Uri></Uri>
     <Metadata></Metadata>
   </Entry>
 </TrackList>

TransportState

Report the current transport state, which can be: 'Playing', 'Paused', 'Stopped', or 'Buffering'.

Play

Begin playback from the current position.

Pause

Pause the current track. This will be converted to Stop if the track cannot be paused e.g. internet radio.

Stop

Stop playback and move the current position to the start of the current track.

Next

Move the current position to the start of the next track in the playlist.

Previous

Move the current position to the start of the next track in the playlist.

SeekId

Move the current position to the start of the track represented by the given Id.

SeekIndex

Move the current position to the start of the track with the given Index into the playlist.

This action should only be used by primitive control points that do not have a rich way of representing the playlist to the user.

SeekSecondAbsolute

Seek to an absolute second within the current track. This is only available if the current track has a finite length.

SeekSecondRelative

Seek to a relative second within the current track. This is only available if the current track has a finite length.

Repeat

Report the state of repeat mode.

SetRepeat

Set the state of repeat mode.

Shuffle

Report the state of shuffle mode.

SetShuffle

Set the state of shuffle mode.

Technical Details

   Domain  : av.openhome.org
   Name    : Playlist
   Version : 1

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.