Specification for the Jukebox protocol A v2.

Please note that extensions to this protocol are allowed, so be
prepared to recieve replies not specified in this file.

But the basic protocol format is fixed:

Each response from the server, or request sent to the server follows
the following format:

CMND arg[ arg ...]\n
!   ^    ^ hex 0x1              ^ (hex 0x0A)

The command/response is a four character token.

The arguments is a 
 (hex 0x1) separated list of integers or
floats (as a readable string), or strings, encoded as ISO-8859-1
characters, unless anything else is specified.

The "strings" can not contain the '
' character, but it is possible
to define other datatypes in the future that can contain them, if it
is deemed necessary.

The protocol is fully 8bit clean, all characters, incluing NULL
(hex 0x0) might be included.

All commands are always ended when a newline (hex 0x0A) is received.

Do not asume that the response to a question follows immediately after
a question, the protocol is asynchronous.

say Nja.. All commands that are marked with a '*' character are obsolete, and
should not be used by new clients.



Server to Client (replies and async messages)
*********************************************

AUTO <int>
!    mode
! 0 if not in autoplay-mode
! Asynchronous message, sent it the matching MODE is set to true. (default)

BALA <float> <string>
!     volume  user
! Someone changed the balance
! Asynchronous message, sent it the matching MODE is set to true.

CHAN <int> <string> <string> <int>
!   channel  desc.   encoding on/off
! 
! Response to the CHAN command.
! This will be sent aynchronously, if the channel mode for the
! specified chanel is on. It is set with the CHAN comand.
! Per default, all channels are set to OFF.

CHNG 
! someone changed the song play list
! Asynchronous message, sent it the matching MODE is set to true.

DUMP int string   int   int   int      int  int
!    song file volume  rate  channels type  datestamp
! file is the real filename
! volume is an integer number, default is 25
! rate is the number of samples per second
! channels is the number of channels, 2 for stereo and 1 for mono
! type is the file type, 3 is 16 bits linear PCM and 1 is 8 bit ISDN u-law
! datestamp is the last modified date for the file

EROR string
!    message
! bad command sent to the server. A message will be included with a
! somewhat userfriendly message.  

HELO <string>@<string> <int> <string>
!         username      num   server version
! gives the username and file descriptor for your session
! When this is sent, you are free to send commands to the server.
! You are connected to the server with num clients.

HTTP <int> <int> <string>
!    song  type    url
! type = bitwise or of: { INFO=1, PICT=2, } , 
!                       { SONG=256, ALBUM=512, ARTIST=1024 }
! More types might be specified in the future
!
! Asynchronous message, sent if the matching MODE is set to true.

MODE <string> <int>
!      name   value
! report a mode setting. Response from the MLST command.

NLST <int>
! number of songs in the list, first reply to the LIST command. 

*NPLI <int>
! number of songs in playlist, first reply to the PLST command.
! PLST has been replaced by ORDR

NREQ <int>
! number of requests owned by the user, first reply to the WHAT command.

NUSR <int>
! number of users, first reply to the WHO command

ORDR <int> [<int> ...]
! Report of song order. The arguments are song id-numbers.
! Reply to the ORDR command.

PLAY <int> <int> <int>
!     id    pri time_played
! a song is currently playing
! Asynchronous message, sent it the matching MODE is set to true, or
! if you issue the 'PLST' command.

PLFT <int>
! report number of priority points left.
! Asynchronous message, sent it the matching MODE is set to true. (default)

PTOT <int>
! report of total priority points
! Asynchronous message, sent it the matching MODE is set to true. (default)

PUSR <string> <int> <int> <int> <int> <int>
!       name    flags domain sess  ptot  plft
! user information
! Sent as a response to the LUSR command.

ROOT
! user is the administrator
! Send upon login, if this is an administrator session.

LYEV <int> <int> <int> <int> <int>
!    song channel when start end
! Start and end as for the SING command. This is a reply to the LYEV
! command.

LYRS <int> <int> <string>
!   song  channel  lyrics
! All lyrics for a channel in a song. nonbreakable space might be
! treated as a newline. This is in no way neccessary, if you choose to
! show only the current part of the lyrics, See the SING async. message
! Asynchronous message, sent it the matching MODE is set to true.

SING <int> <int> <int> <int>
!   song channel start  end
!                 character position, inclusive
!
! Some song lyrics/chords/notes/comments whatever
! The start and end characters are a subrange of the string
! sent by the LYRS command.
! Asynchronous message, sent it the matching MODE is set to true.

SONG <int> <string> <int> <int> <int> <int> <int>
!     id      name   pri  total times flags times
!			  time  played     failed
!
! Flags = bitwise or of: { MPEG=1, LYRICS=2, }
!
! Song information
! Asynchronous message, sent it the matching MODE is set to true.

SCRE <int> <int> <int> <int>
!     id    pri  times times
!               played failed
! priority point update
! Asynchronous message, sent it the matching MODE is set to true.

STAT <int> <int> <int> <int>      <int>
!     id   total times total      times
!          time  played time     failed
!          (sec)       played(sec)
! Statistics information. Reply to the STAT command.

STOP <int> <int> <int>
!     id    pri time_played
! a song stops playing
! Asynchronous message, sent it the matching MODE is set to true. (default)

SYNC
! the songlist is about to be reread.
! Asynchronous message, sent it the matching MODE is set to true.

TELL <string> <string>
!    who        what
! the user who told you the message what.
! Result of the 'TELL' command.

THIS <int> <int>
!     song  score
! The current user has bet score points on the song song.
! Sent asynchronously, and as a response to the WHAT command.

MESS <string>
! A public message, from someone.
! The user is _usually_ the first word in the message
! Result of the EMOT and MESS comands.

TOLD <int>
! number of users told
! Reply to the 'TELL' command.

UCNG
! the userlist has changed
! Asynchronous message, sent it the matching MODE is set to true.

UPDB
! notification that the song database has been updated.
! Asynchronous message, sent it the matching MODE is set to true.

USER <string>@<string> <string>
!      user     host     client
! a user connected to the jukebox with an optional client
! Sent as a response to the USER command.

VOLM <float> <string>
!     volume  user
! Someone changed the volume
! Asynchronous message, sent it the matching MODE is set to true.

VOLS <float> [<string>]
!     volume   user
! Someone changed the song volume. If there is no user, it was the
! jukebox server.
! Asynchronous message, sent it the matching MODE is set to true.

VOTE <int> <int> <string> <int>
!    song   pri     name   domain
! name@domain has voted pri on song
! Reply to the LREQ command.


Requests and commands: Client -> Server
***************************************

AUTO <int>
!    mode
! 0/1 to turn off/on autoplay-mode. This is a admin-only command.
! An auto async message will be sent to all clients when this is
! changed. It is also sent when anyone login.

BALA <float>
!     balance
! Set the balance. Normal is 0.0, max left is -1.0, max right is 1.0
! Please note that the speakers might be mounted in such a way that
! left for one person is not the same thing as left for another.
! The server does not know this. It is up to the client.
! An async message will be sent to all interrested clients if the
! balance is changed.

CLST
! List all available lyrics channels
! Will generate CHAN responses.

CHAN <int> <boolen>
!  channel  on/off
! toggle the mode of a lyrics channel.
! Will not generate any repsonse.

CLNT <string>
!     client-name
! Tell the server that you are using the client-name client.
! This is reported in the USER command replies.

DUMP <int>
!    song-no
! Dump all available information about song-no.
! generates a DUMP, a SONG and a STAT message, and one or more VOTE, HTTP
! LYEV and LYRS messages, depending on wheter or not that information
! is available for the song in question.

EMOT <string>
!     message
! Like mess, but only your name will be prepended to the message.

HELP
! list all available commands.
! Only comments are generated.
! This command is only intended to be used by clients for testing and
! debugging purposes. 

LEFT
! query priority points left for this user
! This will genrate a PTOT and a PLFT response.

LIST
! Request a list of all songs.
! This will generate a SONG response for each song in the database.

LREQ <int>
!    song
! list all request for a song.
! This will generate a VOTE responce for each vote on the specified
! song.

LUSR
! List the user database.
! This will generate a PUSR responce for each user in the database.

LYRS <int> 
!     song 
! Send the lyrics for the specified song. (see the LYRS response above)
! All channels available  will be sent.
!
! Also done asynchronously when a new song, with lyrics, starts, 
! but then only the ones toggled on with the CHAN command that are
! also available for that song.

MESS <string>
!    message
! Send a public message. Your name will be prepended to the message,
! followed by a ':', and the the actual message.
! The result is the MESS async message

MLST
! request a listing of all mode settings.
! This will generate quite a lot of MODE responces.

MODE <string> <int>
!     name    value
! request a certain mode setting
! valid mode names: PLAY STOP SONG UPDB AUTO CHNG UCNG THIS PLFT SCRE
!                   SING VOLS VOLM BALA
! valid mode values: 0 1

ORDR
! Request song order information (for songs with pri>0)
! This will generate a list of all songs currently in the play queue,
! using ORDR responses.

PLAY <int> <int>
!     id    pri
! Play the song <id> with <pri> points.

*PLST
! Request all songs in playlist (with pri>0)
! Will generate a NPLI and zero or more SONG commands, and zero or one
! PLAY command.
! Replaced with the ORDR command.

STAT
! Request song statistics database.
! zero or more STAT replies will be generated.

TELL <string> <string>
!      user    message
! Send a private message to user. 
! You will get a TOLD message, and the user(s) will get a TELL message

UPDB
! Reread song database from disk
! Some async messages will be sent to all clients when this is done.
! UPDB, zero or more SONG, and most other messages _could_ be
! generated by this call.

USER
! List all user connections. one or more USER replies will be sent to
! you.


VOLM <float>
!     volume
! Set the master volume. Normal is 1.0
! A VOLM async message will be sent to all who want it.

VOLS <float>
!     volume
! Set the song volume. Normal is 1.0
! A VOLS async message will be sent to all who want it.

WHAT
! list playrequests for this user
! A NREQ, a PTOT, a PLFT and one or more SONG replies will be the result.
! This should probably never be used by the client, if you have all
! async messages on instead.



EXAMPLES, tbd.