NetProtocol

NOTE: This in only a draft. Network protocol is still under development.

Introduction

Ovoplayer support remote control over a TCP/IP connection, with notifications of player events.

The communication is bidirectional

The network protocol is made of structured messages.

Message length

Each message is prefixed by its length, excluding the length field itself. The length could be expressed in bytes (default) or UTF8 chars as needed, for example, by Android.

Messages sent to server must always contain length expressed in bytes. Length of messages sent from server depends on value passed to CATEGORY_CONFIG:COMMAND_SIZEMODE command.

To avoid sending binary data, length is defined as a 24-bit unsigned integer. This 3-byte integer is then encoded in Base64, so it became a 4 byte ASCII string.

For example you have to send a message which length is 6867.
This number can be represented as 24-bit integer in network order. In hex this is represented as $00 $1A $D3.
This three bytes are then encoded using the Base64 MIME algorithm.
The output is a string containing the four ASCII characters "ABrT". So the message will be prefixed by this string.

When the peer receive the message, it will read the first four chars. The process is reversed, so the application knows how many chars it must read to get the full message.

The maximum message size is 16 Mb ( 2²⁴ bit = 16,777,216 bytes).

Message structure

Messages are text based and UTF-8 encoded.

<size><category>:<command>[=params]

where:

"size" - 4 byte ASCII string. It contains the length of the message, see "Message length" for definitions
"category" - a variable length string, delimited by a colon.
"command" - a variable length string. If command contain parameter, it is delimited by a equal sign.
"params" - a variable length string, representing a text o a number

Defined messages

CATEGORY_CONFIG = 'cfg'

This category contains commands to configure current connection.

Command value	Description	Parameter
COMMAND_SIZEMODE 'size'	Choose how to count message length	number: 0 = Message length is expressed in byte (default) 1 = Message length is expressed in UTF8 chars (Android mode)

CATEGORY_ACTION = 'act'

This category contains basic playback controls. This messages are sent from the client to the player

Command value	Description	Parameter
COMMAND_PLAY 'play'	Start playing current song or resume pause playback.	optional number: index of song to play in current playlist
COMMAND_STOP 'stop'	Stop playing	none
COMMAND_PAUSE 'pause'	Pause current song playback	none
COMMAND_PLAYPAUSE 'playpause'	Switch between playing and paused state	none
COMMAND_NEXT 'next'	Skip to next song in playlist	none
COMMAND_PREVIOUS 'previous'	Skip to previous song in playlist	none
COMMAND_SEEK_P 'seek+'	Skip 10 seconds forward in current song	none
COMMAND_SEEK_M 'seek-'	Skip 10 seconds backward in current song	none
COMMAND_SEEK 'seek'	Skip to a new position in current song.	number: New position in seconds
COMMAND_SETVOL 'vol'	Set current playback volume.	number: New volume in the range 1..256.
COMMAND_MUTE 'mute'	Mute player while continuing playback	none
COMMAND_UNMUTE 'unmute'	Unmute player	none
COMMAND_LOOP 'loop'	change repeat mode	number: 0 = None 1 = Repeat track 2 = Repeat album 3 = Repeat playList

CATEGORY_FILE = 'fil'

This category contains command for adding songs to current playlist. This messages are sent from the client to the player.

All commands in this category requires a filename in the parameter field.

Command value	Description	Parameter
COMMAND_ENQUEUE 'e'	Add the song at the end of current playlist.	String: File name
COMMAND_CLEAR_AND_PLAY p'	Clear current playlist, add the song and start playing.	String: File name
COMMAND_ENQUEUE_AND_PLAY 'x'	Add the song at the end of current playlist and begin playing it.	String: File name

CATEGORY_APP = 'app';

This category contains commands to control player. This messages are sent from the client to the player. Commands in this category do no have parameters.

Command value	Description	Parameter
COMMAND_ACTIVATE 'activate'	Bring player to front on desktop	none
COMMAND_QUIT 'quit'	Exit player	none
COMMAND_CLOSE 'close'	Close player window	none

CATEGORY_REQUEST = 'req'

This category contains commands to ask player for information about itself or songs. Usually the player will replay with the same command in the "info" category (see below).

Command value	Description	Parameter
INFO_ENGINE_STATE 'state'	Get player state	none
INFO_POSITION 'pos'	Get current song position	none
INFO_VOLUME 'vol'	Get current volume	none
INFO_METADATA 'meta'	Get metadata for a song	optional number: index of requested song in current playlist. If missing use current song
INFO_PLAYLISTCOUNT 'count'	Get number of songs in current playlist	none
INFO_COVERURL 'coverurl'	Get a file name for current song cover image	none
INFO_COVERIMG 'coverimg'	Get cover of current song	optional: Desired size of image in pixel, format <width>x<height>
INFO_FULLPLAYLIST 'playlist'	Get current playlist metadata	none
INFO_LOOP 'loop'	Get current repeat mode	number: 0 = None 1 = Repeat track 2 = Repeat album 3 = Repeat playList

CATEGORY_INFORMATION = 'inf'

Command value	Description	Parameter
INFO_ENGINE_STATE 'state'	Player state	number: 0 = Stopped / Idle 1 = Playing 2 = Paused
INFO_POSITION 'pos'	Song position	number: Song position in milliseconds
INFO_VOLUME 'vol'	Volume	number: volume in the range 1..256.
INFO_METADATA 'meta'	metadata for song	metadata
INFO_PLAYLISTCOUNT 'count'	Songs in current playlist	number: Count
INFO_COVERURL 'coverurl'	Image file name	String: Name of the file which contains cover for current image. If image is contained in song tags, a temporary file will be created.
INFO_COVERIMG 'coverimg'	Get cover of current song
INFO_FULLPLAYLIST 'playlist'	Current playlist	playlist
INFO_LOOP 'loop'	Current repeat mode	number: 0 = None 1 = Repeat track 2 = Repeat album 3 = Repeat playList

Metadata

Metadata structure contains the audio tags extracted from the track file.

Metadata are text based and UTF-8 encoded with this structure:

<totalsize><fieldsize>fieldvalue<fieldsize>fieldvalue<fieldsize>fieldvalue ...