Tik-76.115 Individual Project: Guinea Pig
$Id: interface.html,v 2.9 1996/04/22 06:01:37 hynde Exp $

Sound Player - Interface Protocol

This document describes the text based communication protocol used by the Sound Player. See the Python interface for the Python end of the player.

1 · Message structure

A message is one line of text terminated by one newline character ('\n' in C style). When the message is processed the newline is removed from the message and the message is split into a C's argv-like array of fields. Fields are separated by one or more white space characters (excluding the newline). Fields containing spaces must be enclosed in double quotes.

The fields in the message line can contain different kinds of information. A list of possible types follows:

<string>
A string. If string contains spaces it must be enclosed in double quotes.
<int>
Integer number, positive or negative
<float>
Floating point number
<number> = <int>|<float>
Integer or floating point number.
<serial> = <int>|-
Serial number of the message. The logic uses serial numbers to match the reply to the corresponding message. Value is an integer number or - (minus) if no serial number is used.
<flags>
Protocol flags. If no flags are set, - (minus) is used. Otherwise it is a string of flags. Possible flags are:
<sid> = <int>
Sample ID number. Samples are referred to with these numbers.
<command> = <string>
The command is simply a string.
<error> = <int>|<string>
Error code is a error number or a corresponding string symbol.

1.1 · Command message

The structure of a command message is as follows: 
   <serial>  <flags>  <command>  ...
Serial is the serial number of the message, flags are the protocol flags and command is the command. After these the rest of the line may contain additional parameters for the command.

1.2 · Reply message

Reply messages are sent for command messages that requested them or when an error occurs. The structure is like this: 
   <serial>  <error>  ...
where serial is the serial number of the command message this message is a reply to. Error is the error code which is 0 or OK when the operation succeeded and an appropiate error code otherwise (the exact error codes will be specified in the documentation at a later stage). Rest of the line may contain additional parameters depending on the type of command we are replying to.

1.3 · Limitations of the protocol

No special limitations any more.

2 · Commands for loading and unloading samples

There are two types of samples that can be loaded: file samples and null samples. File samples are loaded from disk and are expected to be of supported formats. Null samples are samples that contain only silence of specified length.

2.1 · Loading

Commands for loading samples are: 
   <serial> <flags> LFIL <filename> [<opts>]*
   <serial> <flags> LNUL <length>

   #  <filename> = <string>
   #  <length>   = <int>
   #  <opts>     = CHANNELS=<int>|LITTLE_ENDIAN|BIG_ENDIAN
LFIL loads a file sample whose filename is filename. If optional options (opts) are given the file is assumed to be raw data. Then the CHANNELS option tells how many channels there are in the file and LITTLE_ENDIAN and BIG_ENDIAN tell which byteorder the sample uses. Without one of these the byteorder is assumed to be the same as the byteorder of the machine the player is running on.

LNUL loads a null sample of length sample frames.

Successfull loads reply with a message of type: 

   <serial> 0 <sid> <length> <channels> 

   #  <length>   = <int>
   #  <channels> = <int>
where sid is the sample ID of the new sample. Also the length of the sample in sample frames and the number of channels are returned. In case of an error the reply's error field contains an appropiate error code and the rest of the line may contain text describing the reason of the failure.

2.2 · Unloading

Samples are unloaded with the KILL command: 
   <serial> <flags> KILL <sid>
where sid is the sample ID of the sample to be unloaded.

2.3 · Limitations

Catenated samples are not implemented yet. Meanwhile they can be emulated in the logic module's player interface.

3 · Sample commands

There are commands for starting and stopping sample play, setting the volume levels and moving the sample pointer.

3.1 · Playing samples

   <serial> <flags> STRT <sid>+
   <serial> <flags> PLAY <sid>+
   <serial> <flags> STOP <sid>+
where sid is the sample ID.

The STRT command starts playing the sample(s) and returns immediately. Multiple sample IDs are allowed.

STOP stops the sample. If the sample was not playing it has no effect. Multiple sample IDs are allowed.

PLAY plays the sample(s) and returns after the sample has been played. Multiple sample IDs are allowed but the reply is sent when the first sample has been played. Also in the reply message the time when the sample ended is returned as the parameter.

3.2 · Volume control

The samples volume can be set individually for each channel in a sample. The command for setting the volume is: 
   <serial> <flags> SVOL <sid> <volume>+

   #  <volume>   = <chanmask>:<number>
   #  <chanmask> = [0-3]+|'*'
In the SVOL command the chanmask controls which channels are affected. The mask '03' would select channels 0 and 3. All channels can be selected by using '*' (asterisk) as the mask. Number is the multiplier that is used as the volume level (it is a scaling factor that is not in dB). Multiple volumes can appear, for example for setting a different volume level for each channel.

Examples: The command 
   <serial> <flags> SVOL 17 *:0.1
would set the volume of all channels of sample 17 to 0.1 (-20dB). The following command would set the volume of channels 0 and 2 to 0.1 and the volume of channel 1 to 0.2: 
   <serial> <flags> SVOL 17 02:0.1 1:0.2

3.3 · Output connections control

The output connections specify to which outputs the samples channels are connected to and with what weights. The command for setting the connections is: 
   <serial> <flags> SOUT <sid> <connection>+

   #  <connection> = <chanmask>:<outpmask>:<number>
   #  <chanmask>   = [0-3]+|'*'
   #  <outpmask>   = [0-3]+|'*'
The format of the connection is similar to the volume in the volume control except that there is also the outputs mask. It tells to which output channel to connect to.
Examples: The command 
   <serial> <flags> SOUT 17 *:0:0.5
would connect all channels of the sample to output channel 0 with weight 0.5 each. If the sample were a stereo sample and the output were one channel (mono) output then the output would be (L + R) / 2 (where L is the left channel of the sample and R the right).

To switch the left and right channels in the sample: 

   <serial> <flags> SVOL 17 *:*:0 0:1:1 1:0:1
The first connection disconnects the sample from all outputs. The second routes left channel's (channel 0) output to the right (channel 1) output channel. The third does similarly for right channel (channel 1) of sample.

3.4 · Pointer control

The sample pointer is the index of the next sample word played from the sound sample. Setting the pointer to 0 resets the sample to the start, etc. 
   <serial> <flags> SPTR <sid> <pointer>+
   <serial> <flags> MPTR <sid> <pointer>+
   <serial> <flags> SIPT <sid> <pointer>+

   #  <pointer>  = <chanmask>:<int>
   #  <chanmask> = [0-3]+|'*'
The format of the pointer is similar to the volume in the volume control except that the number is an integer number. The channel mask is the same as with the volume.

SPTR (set pointer) sets the pointer to a value. MPTR (move pointer) adds a value to the current sample pointer. Setting the sample pointer to a negative value is allowed in which case the sample outputs silence until the pointer reaches zero and then begins outputting the sample data.

The SIPT (set initial pointer) command is used to set the 'initial pointer' of a channel. When the sample is stopped or ends the sample pointer is reset from this value. It can be used to set a delay before the sample starts (using a negative value for this pointer) or to start it from some point in the sample. When the sample is set to loop, the sample pointer is reset to 0 when the end of sample is reached regardless of the value of the initial pointer.

3.5 · Looping samples

By default all samples are one-shot samples. A sample's looping status can be set with the LOOP command. It takes as parameters the sample id and a number: 
   <serial> <flags> LOOP <sid> <int>
The number is either 0 or 1 (0 for false, no loop or 1 for true, loop).
Example: 
   <serial> <flags> LOOP 10 1
Sets sample 10 to be a looping sample.

4 · Output control

The level of the outputs can be controlled without having to set the volume of all samples. 
   <serial> <flags> SOPV <volume>+

   #  <volume>   = <chanmask>:<number>
   #  <chanmask> = [0-3]+|'*'
The SOPV (set output volume) is very similar to the sample volume control, except that there is no sample involved and the channel mask selects output channels instead of sample's channels. This command would be used to set the output to the 'most comfortable listening level' at the beginning of the test.

5 · Terminating the server

The server is terminated with the QUIT command: 
   <serial> <flags> QUIT
After receiving a QUIT command the player doesn't accept any more commands and after it has sent all outbound messages, it closes the connection and terminated the player (unloads all samples, etc.).
· Sound Player Index · Document index · Guinea Pig ·