This file document both the MSGTYPE_PLAYER message queue and the
how a module writer should write a wrapper for a music player.

Note that most player modules should also do some type recognition.
see type_managment.txt to read about this.

OK, so how does it work ? from the mod_player point of view, all
players shall act as a state machine with for states: halt, stop,
playing, paused.


All players shall start in halt state.

players shall listen to the MSGTYPE_PLAYER messages for the following
messages: 
- play <player> <song>
- stop
- pause
- seek [+|-] offset

players shall only send the four following messages on the
MSGTYPE_PLAYER queues
- error
- endofsong
- time <pos> <remain>
- playing


HALT STATE
in this state, the audio device shall be available for other players
(usually, the underlying player is not started at all)
any message shall leave you in halt state, except a play message for
your specific player. neither error nor time nor endofsong nor playing shall 
be sent from this state.

STOP 
in this state, the player is ready to play but no song has been given
yet.
- a play message for your player should start playing that song and put
the player in play mode
- a play message to any other player shall put the player in halt mode.
- a pause, stop, or seek message should be ignored
- an error can be reported and will put the player in halt state
- endofsong shall not be reported
- time shall not be reported
- playing shall not be reported

PLAY
the music is playing.
- a play message to your player shall leave the player in play state,
but start playing the new song
- a play message to any other player shall put the player in halt mode.
- a pause order shall put the player in pause state
- a seek shall move to the given position/offset, but stay in the play
state
- a stop shall put the player in stop state
- error can be generated and shall put the player in halt state
- endofsong can be generated and shall put the player in stop mode
- time shall be generated when either the number of seconds spent or
  the number of second remaining has changed. If one of those values is
  unknown, it shall be replaced by -1
- playing shall be reported when playing has started. That is, when, as far as
  the player can tell, sound is coming out. This is usually just before the
  first "time" messsage. The player should send at least one time message,
  this is important if the time reported is -1 -1
  
PAUSE
the music is paused
- a play message to your player shall put the player in play state, and
start playing the new song
- a play message to any other player shall put the player in halt mode.
- a pause order shall put the player in play state
- a seek shall move to the given position/offset, and put the player in
  the play state
- a stop shall put the player in stop state.
- error can be generated and shall put the player in halt state
- endofsong can be generated and shall put the player in stop mode
- time shall not be generated
- playing shall not be generated


Note that there is an important difference between reporting an
endofsong and reporting an error: The caller might attempt to use
another player to play the same file on an error, while it will play
the next song on an endofsong. Please be carefull when choosing what
your module sends back.
