.\"
.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-.\" General Public License for more details.
-.\"
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH disorder_protocol 5
.SH NAME
Requires the \fBadmin\fR right, and only works on local
connections.
.TP
+.B adopt \fIID\fR
+Adopts a randomly picked track, leaving it in a similar state to if it was
+picked by this user. Requires the \fBplay\fR right.
+.TP
.B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
List all the files and directories in \fIDIRECTORY\fR in a response body.
If \fIREGEXP\fR is present only matching files and directories are returned.
If \fIREGEXP\fR is present only matching files are returned.
.TP
.B get \fITRACK\fR \fIPREF\fR
-Getsa preference value.
+Gets a preference value.
On success the second field of the response line will have the value.
.IP
If the track or preference do not exist then the response code is 555.
.TP
.B new \fR[\fIMAX\fR]
Send the most recently added \fIMAX\fR tracks in a response body.
-If the argument is ommitted, the \fBnew_max\fR most recent tracks are
+If the argument is omitted, the \fBnew_max\fR most recent tracks are
listed (see \fBdisorder_config\fR(5)).
.TP
.B nop
The response contains the queue ID of the track.
Requires the \fBplay\fR right.
.TP
+.B playafter \fITARGET\fR \fITRACK\fR ...
+Add all the tracks in the \fITRACK\fR list to the queue after \fITARGET\fR
+(which should be a track ID).
+If \fITARGET\fR is the empty string then the listed tracks are put
+at the head of the queue.
+.IP
+Currently the success result does \fInot\fR include the new track IDs.
+.IP
+Requires the \fBplay\fR right.
+.TP
.B playing
Report what track is playing.
.IP
.B playlist-get \fIPLAYLIST\fR
Get the contents of a playlist, in a response body.
Requires permission to read that playlist and the \fBread\fR right.
+If the playlist does not exist the response is 555.
.TP
.B playlist-get-share \fIPLAYLIST\fR
Get the sharing status of a playlist.
.B reconfigure
Request that DisOrder reconfigure itself.
Requires the \fBadmin\fR right.
+.IP
+Not all configuration options can be modified during the lifetime of the
+server; of those that can't, some will just be ignored if they change while
+others will cause the new configuration to be rejected.
+See \fBdisorder_config\fR(5) for details.
.TP
.B register \fIUSERNAME PASSWORD EMAIL
Register a new user.
Setting the volume requires the \fBvolume\fR right.
.SH RESPONSES
Responses are three-digit codes.
-The first digit distinguishes errors from succesful responses:
+The first digit distinguishes errors from successful responses:
.TP
.B 2
Operation succeeded.
.B scratched
The user that scratched the track.
.TP
+.B origin
+The origin of the track. Valid origins are:
+.RS
+.TP 12
+.B adopted
+The track was originally randomly picked but has been adopted by a user.
+.TP
+.B picked
+The track was picked by a user.
+.TP
+.B random
+The track was randomly picked.
+.TP
+.B scheduled
+The track was played from a scheduled action.
+.TP
+.B scratch
+The track is a scratch sound.
+.RE
+.TP
.B state
The current track state.
Valid states are:
.B failed
The player failed (exited with nonzero status but wasn't scratched).
.TP
-.B isscratch
-The track is actually a scratch.
-.TP
-.B no_player
-No player could be found for the track.
-.TP
.B ok
The track was played without any problems.
.TP
.B started
The track is currently playing.
.TP
+.B paused
+Track is playing but paused.
+.TP
.B unplayed
In the queue, hasn't been played yet.
.TP
.TP
.B wstat
The wait status of the player in decimal.
+.PP
+Note that \fBorigin\fR is new with DisOrder 4.3, and obsoletes some old
+\fBstate\fR values.
.SH NOTES
Times are decimal integers using the server's \fBtime_t\fR.
.PP
The parameters are quoted in the usual DisOrder way.
Currently the following keywords are used:
.TP
+.B adopted \fIID\fR \fIUSERNAME\fR
+\fIUSERNAME\fR adopted track \fIID\fR.
+.TP
.B completed \fITRACK\fR
Completed playing \fITRACK\fR
.TP
.B playing \fITRACK\fR [\fIUSERNAME\fR]
Started playing \fITRACK\fR.
.TP
+.B playlist_created \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is created.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_deleted \fIPLAYLIST\fR
+Sent when a playlist is deleted.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_modified \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is modified (either its contents or its sharing status).
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
.B queue \fIQUEUE-ENTRY\fR...
Added \fITRACK\fR to the queue.
.TP
To simplify client implementation, \fBstate\fR commands reflecting the current
state are sent at the start of the log.
.RE
-.TB
+.TP
.B user_add \fIUSERNAME\fR
A user was created.
.TP