Provides a base set of functionality for playlists: the enqueue,
dequeue, select, and list requests; the ENQUEUE, DEQUEUE,
SELECT, COUNT, and ITEM responses; and the file item type.
Playlist also allows use of the Ejected state from FileLoad,
but supercedes that feature’s requests and responses (see below).
Playlist has no dependencies.
Playlist conflicts somewhat with FileLoad: load from the
latter is replaced by select from the former, and eject by
select with no arguments.
Where INDEX occurs in the syntax of any below request or response,
it represents an integral playlist index, such that the first item
is indexed by 0, subsequent items are indexed by ascending positive
integers; in addition, the last item is indexed by -1, and precedent
items are indexed by ascending negative integers. Thus, in a 10-item
playlist, the first item may be indexed by -10 or 0; the next by
-9 or 1; and so on, with the penultimate item being indexed by 8
or -2, and the last item by 9 or -1.
A problem with using position indexes for playlist items is that
they are constantly changed by insertions and deletions. Worse, a
request to (say) delete an index i may be pre-empted by an insertion
or deletion that changes where i points to, causing the wrong
item to be deleted.
Each playlist item, when enqueued, must be supplied with a hash: a string of characters that uniquely identifies that item for the purposes of verifying further requests concerning the item. For simplicity, all hashes are generated by clients, which must ensure that they never assign two items the same hash; the server’s obligation is merely to reject any hashes that collide at the moment of insertion.
Useful hashes will try to distinguish between different items, different clients, and different periods of time. For example, one might base a hash on:
The item arguments;
The item type;
The client’s hostname and port;
Either the time of insertion (to a decent resolution) or a sequence number.
Of course, if the client is a human, any sufficiently unique identifier will do.
EjectedAs defined in the FileLoad feature.
dequeue — remove item from playlistdequeue <INDEX> <HASH>
Removes the item at index INDEX, if it has the hash HASH.
Fails if INDEX does not specify an item in the playlist, or if the
item at INDEX does not have hash HASH.
enqueue — insert item in playlistenqueue <INDEX> <HASH> <TYPE> <ARGUMENTS..>
Inserts the item with type TYPE such that any immediately subsequent
action on index INDEX on the playlist will reach this item. Thus,
for integral indexes, insertion at a positive index will place the
new item before any item occupying that index, and insertion at
a negative index after any occupant; consequently, use -1 to
insert at the end of the playlist.
A HASH (see above) must also be given. The command should be
rejected if the hash is presently in use. The server may reject
previously used hashes, but the client should take responsibility
for doing this itself.
The ARGUMENTS are interpreted according to TYPE. For the basic
file type of item, see below.
An ENQUEUE response should be sent announcing the (non-negative)
index, hash, type, and arguments of the inserted item.
list — announce playlistlist
Causes the server to announce, via a COUNT and zero or more
subsequent ITEM responses, the current state of the playlist.
select — change selectionselect [<INDEX> <HASH>]
If INDEX and HASH are not given, removes any current selection.
Else, selects the item at index INDEX if its hash is HASH.
Fails if INDEX does not specify an item in the playlist, or if the
item at INDEX does not have hash HASH.
COUNT — playlist sizeCOUNT <NUM>
Given before ITEM responses at the beginning of a response to a
list request, to inform clients of how many items are to follow.
DEQUEUE — item removed from playlistDEQUEUE <INDEX> <HASH>
The item formerly at index INDEX, with hash HASH, has been
removed.
Unless an ENQUEUE with the same HASH follows, HASH now no
longer points to an item. INDEX now points to the item, if any,
following the dequeued item.
ENQUEUE — item added to playlistENQUEUE <INDEX> <HASH> <TYPE> <ARGUMENTS…>
The index INDEX and hash HASH now point to an item of type
TYPE with arguments ARGUMENTS.
Any items occurring on or after INDEX now follow this new item,
and their positive indices have changed by 1. (Any items before
INDEX have now had their negative indices change by -1.) As such,
any attempt to reference items by index must be adjusted accordingly.
None of the other items' hashes are changed. Thus, clients should use hashes where possible.
If an ENQUEUE follows a DEQUEUE on the same HASH with the
same TYPE and ARGUMENTS, it likely represents an attempt by a
client to move an item.
ITEM — playlist itemITEM <INDEX> <HASH> <TYPE> <ARGUMENTS…>
ITEM is announced as part of the response to a list request.
Each part of the ITEM request has the same meaning as given in
ENQUEUE; the INDEX represents the item’s current index, not
its original.
SELECT — item selectedSELECT or SELECT <INDEX> <HASH>
With no index or hash, the playlist has no item selected. This
means that playback controls should not work, and the state
should be Ejected.
With an index and hash, the item at index INDEX and hash HASH
is selected. Playback controls should work, and the state should
not be Ejected.
This response must be sent when the selection changes or is cleared, and also must be sent as an initial response. It may also be sent at any other time, so long as its information is correct at time of sending.
fileA file item represents a file in a playlist. The file type
takes one argument, namely the absolute path of the file to load,
as interpreted by the load request.
Items with type file may be select-ed.