Add 'adopt' command. This adopts a randomly picked track by changing

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index a35e7f7d192e77ce1f5609d1eb00f3ea5b560cd9..ba37e67120e11444f16d3a650126af66296663ae 100644 (file)
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -57,6 +57,10 @@ then the \fBdefault_rights\fR setting applies instead.
 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.
@@ -495,6 +499,26 @@ The time the track was played at.
 .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:
@@ -503,12 +527,6 @@ 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
@@ -518,6 +536,9 @@ The track was scratched.
 .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
@@ -536,6 +557,9 @@ The time the track was added to the queue.
 .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
@@ -553,6 +577,9 @@ keyword followed by (optionally) parameters.
 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