NAME
       disorder_protocol - DisOrder communication protocol

DESCRIPTION
       The  DisOrder  client and server communicate via the protocol described
       in this man page.

       The protocol is usually modified in each new version of the server.

MESSAGE STRUCTURE
       A line is a sequence of printable Unicode characters encoded  in  UTF-8
       and  terminated  by the octet 0x0A.  Note that unlike some other proto-
       cols, a carriage  return  is  not  used  as  part  of  the  end-of-line
       sequence.

       A  command  message consists of a command line followed, in some cases,
       by a body.  Similarly a response message consists of  a  response  line
       followed sometimes by a body.

       A  body  consists of a sequence of dot-stuffed lines followed by a line
       containing a single full stop character.  Dot-stuffing means  that  any
       line  in  the  body  starting  with  a full stop have another full stop
       inserted at the start prior to transmission, and  removed  again  after
       reception.

       Whether  a command message includes a body depends on the specific com-
       mand being sent; see below for details.  This is  also  true  of  reply
       messages, although it is guaranteed that if the is a response body then
       the reply status code (see below) will end with the digit 3.

       Command lines, and some response lines, are split into fields.   Fields
       are separated by one or more spaces and may be unquoted or quoted.

       An unquoted field can contain any (non-control) characters except for a
       space, quotation mark or apostrophe.  They  are  always  at  least  one
       character long.

       A quoted field begins with a quotation mark or apostrophe and is termi-
       nated by the same character.  Any occurrence of the  backslash  or  the
       surrounding  quotation  mark  must be escaped.  The full set of escapes
       permitted is:

       \\     Backslash

       \"     Quotation mark

       \'     Apostrophe

       \n     Line feed

COMMANDS
       Commands always have a command name as the first field of the line.

       All commands require the connection to have been already  authenticated
       unless stated otherwise.  See AUTHENTICATION below.  If not stated oth-
       erwise, the read right is sufficient to execute the command.

       adduser USERNAME PASSWORD [RIGHTS]
              Create a new user with the given username and password.  The new
              user's  rights  list  can  be  specified;  if it is not then the
              default_rights setting  applies  instead.   Requires  the  admin
              right, and only works on local connections.

       adopt ID
              Adopts a randomly picked track, leaving it in a similar state to
              if it was picked by this user.  Requires the play right.

       allfiles DIRECTORY [REGEXP]
              List all the files and directories in DIRECTORY  in  a  response
              body.   If REGEXP is present only matching files and directories
              are returned.

       confirm CONFIRMATION
              Confirm user registration.  CONFIRMATION  is  as  returned  from
              register  below.   This  command logs the user in.  The response
              contains the logged-in username.

       cookie COOKIE
              Log a user back in using a cookie created with make-cookie.  The
              response contains the username.

       deluser USERNAME
              Delete the named user.  Requires the admin right, and only works
              on local connections.

       dirs DIRECTORY [REGEXP]
              List all the directories in DIRECTORY in a  response  body.   If
              REGEXP is present only matching directories are returned.

       disable [now]
              Disable  further  playing.   If  the  optional  now  argument is
              present then the current track is stopped.  Requires the  global
              prefs right.

       edituser USERNAME PROPERTY VALUE
              Set  a  user  property.   With  the admin right any username and
              property may be specified.   Otherwise  the  userinfo  right  is
              required and only the email and password properties may be set.

              User properties are syntax-checked before setting.  For instance
              email must contain an "@" sign or you will get an error.   (Set-
              ting  an  empty value for email is allowed and removes the prop-
              erty.)

              See USER PROPERTIES below.

       enable Re-enable further playing,  and  is  the  opposite  of  disable.
              Requires the global prefs right.

       enabled
              Report  whether  playing  is  enabled.   The second field of the
              response line will be yes or no.

       exists TRACK
              Report whether the named track exists.  The second field of  the
              response line will be yes or no.

       files DIRECTORY [REGEXP]
              List  all  the files in DIRECTORY in a response body.  If REGEXP
              is present only matching files are returned.

       get TRACK PREF
              Gets a preference value.  On success the  second  field  of  the
              response line will have the value.

              If  the  track or preference do not exist then the response code
              is 555.

       get-global KEY
              Get a global preference.

              If the preference does not exist then the response code is 555.

       length TRACK
              Get the length of the track in seconds.  On success  the  second
              field of the response line will have the value.

       log    Send  event  log  messages in a response body.  The command will
              never terminate.  Any further data sent to the  server  will  be
              discarded  (explicitly;  i.e. it will not accumulate in a buffer
              somewhere).

              See EVENT LOG below for more details.

       make-cookie
              Returns an opaque string that can be used by the cookie  command
              to log this user back in on another connection (until the cookie
              expires).

       move TRACK DELTA
              Move a track in the queue.  The track may be  identified  by  ID
              (preferred)  or  name (which might cause confusion if it's there
              twice).  DELTA should be an negative  or  positive  integer  and
              indicates how many steps towards the head of the queue the track
              should be moved.

              Requires one of the move mine, move random or  move  any  rights
              depending on how the track came to be added to the queue.

       moveafter TARGET ID ...
              Move  all  the tracks in the ID list after ID TARGET.  If TARGET
              is the empty string then the listed tracks are put at  the  head
              of  the  queue.   If  TARGET  is  listed in the ID list then the
              tracks are moved to just after the first non-listed track before
              it, or to the head if there is no such track.

              Requires  one  of  the move mine, move random or move any rights
              depending on how the tracks came to be added to the queue.

       new [MAX]
              Send the most recently added MAX tracks in a response body.   If
              the  argument  is  omitted,  the  new_max most recent tracks are
              listed (see disorder_config(5)).

       nop    Do nothing.  Used by disobedience(1)  as  a  keepalive  measure.
              This command does not require authentication.

       part TRACK CONTEXT PART
              Get  a  track name part.  Returns an empty string if a name part
              cannot be constructed.

              CONTEXT is one of sort or display and PART  is  usually  one  of
              artist, album or title.

       pause  Pause the current track.  Requires the pause right.

       play TRACK
              Add a track to the queue.  The response contains the queue ID of
              the track.  Requires the play right.

       playafter TARGET TRACK ...
              Add all the tracks in the TRACK list to the queue  after  TARGET
              (which  should  be  a  track ID).  If TARGET is the empty string
              then the listed tracks are put at the head of the queue.

              Currently the success result does not include the new track IDs.

              Requires the play right.

       playing
              Report what track is playing.

              If the response is 252 then the rest of the response  line  con-
              sists of track information (see below).

              If the response is 259 then nothing is playing.

       playlist-delete PLAYLIST
              Delete  a playlist.  Requires permission to modify that playlist
              and the play right.

       playlist-get PLAYLIST
              Get the contents of a playlist, in a  response  body.   Requires
              permission  to  read  that  playlist and the read right.  If the
              playlist does not exist the response is 555.

       playlist-get-share PLAYLIST
              Get the sharing status of a playlist.  The result will  be  pub-
              lic,  private  or  shared.   Requires  permission  to  read that
              playlist and the read right.

       playlist-lock PLAYLIST
              Lock a playlist.  Requires permission to  modify  that  playlist
              and  the  play right.  Only one playlist may be locked at a time
              on a given connection and the lock  automatically  expires  when
              the connection is closed.

       playlist-set PLAYLIST
              Set the contents of a playlist.  The new contents should be sup-
              plied in a command body.  Requires  permission  to  modify  that
              playlist and the play right.  The playlist must be locked.

       playlist-set-share PLAYLIST SHARE
              Set  the  sharing  status  of  a  playlist to public, private or
              shared.  Requires permission to modify  that  playlist  and  the
              play right.

       playlist-unlock
              Unlock the locked playlist.

       playlists
              List  all playlists that this connection has permission to read.
              Requires the read right.

       prefs TRACK
              Send back the preferences for TRACK in a  response  body.   Each
              line  of the response has the usual line syntax, the first field
              being the name of the pref and the second the value.

       queue  Send back the current queue in a response body, one track  to  a
              line,  the  track  at  the head of the queue (i.e. next to be be
              played) first.  See below for the track information syntax.

       random-disable
              Disable  random  play  (but  don't  stop  the  current   track).
              Requires the global prefs right.

       random-enable
              Enable random play.  Requires the global prefs right.

       random-enabled
              Report  whether random play is enabled.  The second field of the
              response line will be yes or no.

       recent Send back the current recently-played list in a  response  body,
              one  track  to a line, the track most recently played last.  See
              below for the track information syntax.

       reconfigure
              Request that DisOrder reconfigure itself.   Requires  the  admin
              right.

              Not  all  configuration options can be modified during the life-
              time of the server; of those  that  can't,  some  will  just  be
              ignored  if they change while others will cause the new configu-
              ration to be rejected.  See disorder_config(5) for details.

       register USERNAME PASSWORD EMAIL
              Register a new user.  Requires the register right.   The  result
              contains  a confirmation string; the user will be be able to log
              in until this has been presented back to the server via the con-
              firm command.

       reminder USERNAME
              Send  a  password reminder to user USERNAME.  If the user has no
              valid email address, or no password, or a reminder has been sent
              too recently, then no reminder will be sent.

       remove ID
              Remove  the  track identified by ID.  Requires one of the remove
              mine, remove random or remove any rights depending  on  how  the
              track came to be added to the queue.

       rescan [wait] [fresh]
              Rescan  all roots for new or obsolete tracks.  Requires the res-
              can right.

              If the wait flag is present then the response is  delayed  until
              the  rescan  completes.   Otherwise the response arrives immedi-
              ately.  This is primarily intended for testing.

              If the fresh flag is present a rescan is already underway then a
              second  rescan  will  be started when it completes.  The default
              behavior is to piggyback on the existing rescan.

              NB that fresh is currently disabled in  the  server  source,  so
              using this flag will just provoke an error.

       resolve TRACK
              Resolve  a  track name, i.e. if this is an alias then return the
              real track name.

       resume Resume the current track after a pause  command.   Requires  the
              pause right.

       revoke Revoke  the  current login's cookie.  It will not be possible to
              use the cookie in the future.

       rtp-address
              Report the RTP broadcast (or multicast)  address,  in  the  form
              ADDRESS PORT.  This command does not require authentication.

       scratch [ID]
              Remove  the  track  identified  by  ID, or the currently playing
              track if no ID is specified.  Requires one of the scratch  mine,
              scratch  random or scratch any rights depending on how the track
              came to be added to the queue.

       schedule-add WHEN PRIORITY ACTION ...
              Schedule an event for the future.

              WHEN is the time when it should happen,  as  a  timestamp.   See
              TIMESTAMPS below.  It must refer to a time in the future.

              PRIORITY  is  the  event priority.  This can be normal, in which
              case the event will be run at startup if its time has  past,  or
              junk  in which case it will be discarded if it is found to be in
              the past at  startup.   The  meaning  of  other  values  is  not
              defined.

              ACTION  is  the  action to perform.  The choice of action deter-
              mines the meaning of the remaining arguments.  Possible  actions
              are:

              play   Play  a  track.   The  next  argument  is the track name.
                     Requires the play right.

              set-global
                     Set a global preference.  The next argument is the  pref-
                     erence name and the final argument is the value to set it
                     to (omit it to unset  it).   Requires  the  global  prefs
                     right.

              You need the right at the point you create the event.  It is not
              possible to create scheduled events in expectation of  a  future
              change in rights.

       schedule-del EVENT
              Deletes  a  scheduled  event.  Users can always delete their own
              scheduled events; with the admin right you can delete any event.

       schedule-get EVENT
              Sends the details of scheduled event EVENT in a  response  body.
              Each  line  is  a  pair  of strings quoted in the usual way, the
              first being the key ane the second  the  value.   No  particular
              order is used.

              Scheduled  events are considered public information.  Right read
              is sufficient to see details of all events.

       schedule-list
              Sends the event IDs of all scheduled events in a response  body,
              in  no particular order.  Use schedule-get to get the details of
              each event.

       search TERMS
              Search for tracks matching the search terms.   The  results  are
              put in a response body, one to a line.

              The  search  string is split in the usual way, with quoting sup-
              ported, into a list of terms.  Only tracks  matching  all  terms
              are included in the results.

              Any  terms  of the form tag:TAG limits the search to tracks with
              that tag.

              All other terms are interpreted as individual words  which  must
              be present in the track name.

              Spaces  in  terms don't currently make sense, but may one day be
              interpreted to allow searching for phrases.

       set TRACK PREF VALUE
              Set a preference.  Requires the prefs right.

       set-global KEY VALUE
              Set a global preference.  Requires the global prefs right.

       shutdown
              Requests server shutdown.  Requires the admin right.

       stats  Send server statistics in plain text in a response body.

       tags   Send the list of currently known tags in a response body.

       unset TRACK PREF
              Unset a preference.  Requires the prefs right.

       unset-global KEY
              Unset a global preference.  Requires the global prefs right.

       user USERNAME RESPONSE
              Authenticate as user USERNAME.  See AUTHENTICATION below.

       userinfo USERNAME PROPERTY
              Get a user property.  See USER PROPERTIES below.

       users  Send the list of currently known users in a response body.

       version
              Send back a response with  the  server  version  as  the  second
              field.

       volume [LEFT [RIGHT]]
              Get or set the volume.

              With  zero  parameters just gets the volume and reports the left
              and right sides as the 2nd and 3rd fields of the response.

              With one parameter sets both sides to the same value.  With  two
              parameters  sets  each  side  independently.  Setting the volume
              requires the volume right.

RESPONSES
       Response lines start with a  three-digit  status  code  followed  by  a
       space.   The meaning the response and the interpretation of the rest of
       the line depends on that code.

       The first digit distinguishes errors from successful responses:

       2      Operation succeeded.

       5      Operation failed.

       The second digit breaks down the origin of the response:

       0      Generic responses not specific to the handling of the command.

       1      51x errors indicate that the user had  insufficient  rights  for
              the command.

       3      Authentication responses.

       5      Responses specific to the handling of the command.

       The third digit provides extra information about the response:

       0      Text part is just commentary, intended to be human-readable.

       1      Text  part  is  a  constant  result (e.g. version).  It will not
              change on a subsequent use of the same command on the same  con-
              neciton.

       2      Text part is a potentially variable result.

       3      Text part is just commentary; a dot-stuffed body follows.

       4      Text  part  is  just  commentary; an indefinite dot-stuffed body
              follows.  (Used for log.)

       5      Used with "harmless" errors, for instance a preference not being
              found.  The text part is commentary.

       9      The  text  part  is  just  commentary  (but  would normally be a
              response for this command) e.g. playing.

       Result strings (not bodies) intended for machine parsing (i.e. xx1  and
       xx2 responses) are structure into fields in the the same way as command
       lines.

AUTHENTICATION
       When a connection is made the server sends a 231  response  before  any
       command is received.  This contains a protocol generation, an algorithm
       name and a challenge encoded in hex, in  the  fields  of  the  response
       line.

       The current protocol generation is 2.

       The  possible  algorithms  are  (currently)  sha1,  sha256,  sha384 and
       sha512.  Completely upper-case names such as SHA1 etc work as synonyms.

       The user response consists of the selected hash of the user's  password
       concatenated with the challenge, encoded in hex.

TRACK INFORMATION
       Track  information  is  encoded  in a response line as pairs of fields.
       The first is a name, the second a value.  The names have the  following
       meanings:

       expected    The time the track is expected to be played at.

       id          A string uniquely identifying this queue entry.

       played      The time the track was played at.

       scratched   The user that scratched the track.

       origin      The origin of the track.  Valid origins are:

                   adopted     The  track  was  originally randomly picked but
                               has been adopted by a user.

                   picked      The track was picked by a user.

                   random      The track was randomly picked.

                   scheduled   The track was played from a scheduled action.

                   scratch     The track is a scratch sound.

       state       The current track state.  Valid states are:

                   failed      The player failed (exited with  nonzero  status
                               but wasn't scratched).

                   ok          The track was played without any problems.

                   scratched   The track was scratched.

                   started     The track is currently playing.

                   paused      Track is playing but paused.

                   unplayed    In the queue, hasn't been played yet.

                   quitting    The  track was terminated because the server is
                               shutting down.

       submitter   The user that submitted the track.

       track       The filename of the track.

       when        The time the track was added to the queue.

       wstat       The wait status of the player in decimal.

       Note that origin is new with DisOrder 4.3, and obsoletes some old state
       values.

EVENT LOG
       The  event  log consists of lines starting with a hexadecimal timestamp
       and a keyword followed by (optionally) parameters, which are structured
       into  fields  in the same way as command and response lines.  Currently
       the following keywords are used:

       adopted ID USERNAME
              USERNAME adopted track ID.

       completed TRACK
              Completed playing TRACK

       failed TRACK ERROR
              Completed playing TRACK with an error status

       global_pref PREF [VALUE]
              A global preference was set or unset.

       moved USERNAME
              User USERNAME  moved  some  track(s).   Further  details  aren't
              included any more.

       playing TRACK [USERNAME]
              Started playing TRACK.

       playlist_created PLAYLIST SHARING
              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).

       playlist_deleted PLAYLIST
              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).

       playlist_modified PLAYLIST SHARING
              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).

       queue QUEUE-ENTRY...
              Added TRACK to the queue.

       recent_added QUEUE-ENTRY...
              Added ID to the recently played list.

       recent_removed ID
              Removed ID from the recently played list.

       removed ID [USERNAME]
              Queue  entry  ID  was  removed.   This is used both for explicit
              removal (when USERNAME is present)  and  when  playing  a  track
              (when it is absent).

       rescanned
              A rescan completed.

       scratched TRACK USERNAME
              TRACK was scratched by USERNAME.

       state KEYWORD
              Some state change occurred.  The current set of keywords is:

              completed
                     The current track completed successfully.

              disable_play
                     Playing was disabled.

              disable_random
                     Random play was disabled.

              enable_play
                     Playing was enabled.

              enable_random
                     Random play was enabled.

              failed The current track failed.

              pause  The current track was paused.

              playing
                     A track started playing.

              resume The current track was resumed.

              rights_changed RIGHTS
                     User's rights were changed.

              scratched
                     The current track was scratched.

              To simplify client implementation, state commands reflecting the
              current state are sent at the start of the log.

       user_add USERNAME
              A user was created.

       user_delete USERNAME
              A user was deleted.

       user_edit USERNAME PROPERTY
              Some property of a user was edited.

       user_confirm USERNAME
              A user's login was confirmed (via the web interface).

       volume LEFT RIGHT
              The volume changed.

       QUEUE-ENTRY...  is as defined in TRACK INFORMATION above.

       The user-* messages are only sent to admin users, and are not sent over
       non-local connections unless remote_userman is enabled.

USER PROPERTIES
       The following user properties are defined:

       created
              The  timestamp when the user was created.  See TIMESTAMPS below.
              This user property cannot be modified.

       email  The user's email address.

       password
              The user's password.

       rights The rights the user has, separated by commas.

RIGHTS
       The full set of rights are:

       read   User can perform read-only operations

       play   User can add tracks to the queue

       move any
              User can move any track

       move mine
              User can move their own tracks

       move random
              User can move randomly chosen tracks

       remove any
              User can remove any track

       remove mine
              User can remove their own tracks

       remove random
              User can remove randomly chosen tracks

       scratch any
              User can scratch any track

       scratch mine
              User can scratch their own tracks

       scratch random
              User can scratch randomly chosen tracks

       volume User can change the volume

       admin  User can perform admin operations

       rescan User can initiate a rescan

       register
              User can register new users.  Normally only the guest user would
              have this right.

       userinfo
              User can edit their own userinfo

       prefs  User can modify track preferences

       global prefs
              User can modify global preferences

       pause  User can pause/resume

TIMESTAMPS
       A  timestamp  is  a decimal integer giving a number of seconds past the
       epoch, disregarding counting leap seconds.  The epoch is midnight, Jan-
       uary 1 1970, UTC.

NOTES
       For  file  listings, the regexp applies to the basename of the returned
       file, not the whole filename, and letter  case  is  ignored.   pcrepat-
       tern(3) describes the regexp syntax.

       Filenames  are in UTF-8 even if the collection they come from uses some
       other encoding - if you want to access the real file (in such cases  as
       the  filenames  actually correspond to a real file) you'll have to con-
       vert to whatever the right encoding is.

SEE ALSO
       disorder(1), time(2), disorder(3),  pcrepattern(3)  disorder_config(5),
       disorderd(8), utf8(7)