Rivendell

Core Audio Control Protocol

v0.9.1

OVERVIEW

Formats used for audio storage are Microsoft's RIFF format, type WAVE. Sample representation is 16 bit little endian, stream interleaved where appropriate.

Commands to the Core Audio Engine are passed by means of a TCP SOCK_STREAM connection

to TCP port 5005 on the host server. Proper network byte order will be observed in all cases.

Commands have the following general syntax:

<cmd-code> [<arg>] [...]!

where:

<cmd-code>	A two letter command code, describing the generic action to be performed

<arg>	Zero or more arguments, delimited by spaces or, if the last argument, by !

(see below).

!	The ASCII character 33, indicating the end of the command sequence.

Unless otherwise specified, the engine will echo back the command with a + or - before the !, to indicate the success or failure of the command execution.

CONNECTION MANAGEMENT

PASSWORD

PW <password>!

Pass a password to the server for authentication.

where:

<password>	A password to be supplied before granting the client access.

Returns:	PW +! to indicate success

PW -! to indicate failure

DROP CONNECTION

DC!

Drop the TCP connection and end the session.

PLAYBACK OPERATIONS

LOAD PLAYBACK

LP <card-num> <name>!

Prepare an audio interface to play an audio file.

where:

<card-num>	The number of the audio adapter to use.

<name>	The base name of an existing file in the audio storage filesystem.

Returns: LP <card-num> <name> <stream-num> <conn-handle>!

Where:

<stream-num>	The stream number selected to be used, or a -1 in case of error. This is relative	to the audio adapter selected.

<conn-handle>	The connection handle. This will be used to refer to the playback event in all	subsequent calls to CAE.

UNLOAD PLAYBACK

UP <conn-handle>!

Free an audio playback interface.

where:

<conn-handle>	The connection handle of the playback event, from the LOAD PLAYBACK call.

PLAY POSITION

PP <conn-handle> <position>!

Position the playback pointer.

where:

<conn-handle>	The connection handle of the playback event, from the LOAD PLAYBACK call.

<position>	Position in file, in milliseconds.

PLAY

PY <conn-handle> <length> <speed> <pitch-flag>!

Play the loaded file from the current position.

where:

<conn-handle>	The connection handle of the playback event, from the LOAD PLAYBACK call.

<length>	Playback length in milliseconds, relative to the current start position.

0 = play until told to stop or end-of-file is reached.

<speed>	Playback speed in thousandths of a percent. 100000 = normal speed.

<pitch-flag>	Controls whether audio pitch changes with speed or not. 0 = no, 1 = yes.

Returns:	If playback reaches the end of the file, a Stop Playback (SP) confirmation will be echoed

back.

STOP PLAYBACK

SP <conn-handle>!

Stop playback of the specified playback interface.

where:

<conn-handle>	The connection handle of the playback event, from the LOAD PLAYBACK call.

TIMESCALING SUPPORT

TS <card-num>!

Interogate CAE if <card-num> supports timescaling.

Returns: TS <card-num> [+]|[-]

RECORD OPERATIONS

LOAD RECORDING

LR <card-num> <port-num> <coding> <channels> <samp-rate> <bit-rate> <name>!

Prepare an audio interface to capture an audio file.

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<coding>	0 = PCM16, 1 = MPEG Layer 1, 2 = MPEG Layer 2, 3 = MPEG Layer 3,

4 = PCM24

<channels>	1 = Mono, 2 = Stereo

<samp-rate>	Sample Rate in samples/sec. 32000, 44100 or 48000 supported.

<bit-rate>	MPEG Bit Rate. For PCM16, this should be zero.

<name>	The base name of a file in the audio storage filesystem. If the file already

exists, it will be overwritten, otherwise it will be created.

UNLOAD RECORDING

UR <card-num> <stream-num>!

Free an audio capture interface.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

Command will return:

UR <card-num> <stream-num> <len>!

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<len>	Length of recording, in mS.

RECORD

RD <card-num> <stream-num> <length> <threshold>!

Record the loaded file.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<length>	Length of time to record in milliseconds. If zero, record until told to

stop.

<threshold>	Threshold of audio detected at which to start recording, in 1/100 dBFs.

If '0', start immediately.

Returns:	When recording actually begins, a Record Start (RS) confirmation will be echoed back. If

record time expires a Stop Record (SR) confirmation will be echoed back.

RECORD START (Receive Only)

RS <card-num> <stream-num>!

Record start. Receive-only signal to indicate recording has actually started (as with a VOX event, where actual recording may begin some time after the interface is placed into record).

where:

<card-num>	The number of the audio adapter being used.

<stream-num>	The stream number being used. This is relative to the audio adapter selected.

STOP RECORD

SR <card-num> <stream-num>!

Stop the recording.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

MIXER OPERATIONS

SET INPUT VOLUME

IV <card-num> <stream-num> <level>!

Set the volume of an input stream.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

SET OUTPUT VOLUME

OV <card-num> <stream-num> <port-num> <level>!

Set the volume of an output stream.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

FADE OUTPUT VOLUME

FV <card-num> <stream-num> <port-num> <level> <length>!

Transition the volume of an output stream over time.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

<length>	The length of the transition, in milliseconds.

SET INPUT LEVEL

IL <card-num> <port-num> <level>!

Set the gain level of an input port.

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

SET OUTPUT LEVEL

OL <card-num> <port-num> <level>!

Set the gain level of an output port.

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

SET INPUT MODE

IM <card-num> <stream-num> <mode>!

Set the mode of an input stream.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<mode>	The mode, as follows:

0 = Normal

1 = Swap left and right channels

2 = Left audio on both channels

3 = Right audio on both channels

SET OUTPUT MODE

OM <card-num> <stream-num> <model>!

Set the mode of an output stream.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<mode>	The mode, as follows:

0 = Normal

1 = Swap left and right channels

2 = Left audio on both channels

3 = Right audio on both channels

SET INPUT VOX LEVEL

IX <card-num> <stream-num> <level>!

Set the VOX threshold level of an input stream.

where:

<card-num>	The number of the audio adapter to use.

<stream-num>	The stream number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

SET INPUT TYPE

IT <card-num> <port-num> <type>!

Set the signal type of an input port.

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<type>	The type, as follows:

0 = Analog

1 = AES3 Digital

INPUT STATUS

IS <card-num> <port-num>!

Request the status of an input port.

Response:

IS <card-num> <port-num> <status>!

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use. This is relative to the audio adapter selected.

<status>	The status, as follows:

0 = Ok

1 = No Sync

SET AUDIO PASSTHROUGH LEVEL

AL <card-num> <input-num> <output-num> <level>!

Set the gain of the audio passthrough from <card-num>:<input-num> to <card-num>:<output-num> to <level>.

where:

<card-num>	The number of the audio adapter to use.

<input-num>	The input number to use. This is relative to the audio adapter selected.

<output-num>	The output number to use. This is relative to the audio adapter selected.

<level>	The level, in hundreths of a dB.

EXTERNAL CLIENT OPERATIONS

OPEN RTP CAPTURE

CO <card-num> <port-num> <udp-port> <samp-rate> <chans>!

Open an RTP connection for audio capture.

where:

<card-num>	The number of the audio adapter to use.

<port-num>	The port number to use.

<udp-port>	The port number on the remote system to which to send RTP packets.

<samp-rate>	The requested sample rate.

<chans>	The requested number of channels.

The system will reply with:

CO <card-num> <port-num> <udp-port> <samp-rate> <chans> <pkt-size>!

where:

<card-num>	The number of the audio adapter being used.

<port-num>	The port number being used.

<udp-port>	The port number on the local system from which RTP packets will originate.

<samp-rate>	The actual sample rate.

<chans>	The actual number of channels.

The actual sample rate and number of channels may be different from those requested; clients must be prepared to detect and deal with this possibility!

JACK OPERATIONS

CONNECT PORTS

JC <output_name> | <input_name>!

Connect a JACK input port to an output port. If the connection was successfully added, returns:

JC <output_name> | <input_name>!

where:

<output_name>	The name of the output port, in format CLIENTNAME:PORTNAME.

<input_name>	The name of the input port, in format CLIENTNAME:PORTNAME.

DISCONNECT PORTS

JD <output_name> | <input_name>!

Disconnect a JACK input port to an output port. If the connection was successfully removed, returns:

JD <output_name> | <input_name>!

where:

<output_name>	The name of the output port, in format CLIENTNAME:PORTNAME.

<input_name>	The name of the input port, in format CLIENTNAME:PORTNAME.

Meter/Status Updates

METER ENABLE

ME <udp-port>!

where:

<udp-port>	UDP port number on client system to send meter update messages.

The following messages are sent by CAE to indicate current status and audio levels. They are sent to the UDP port requested by the Meter Enable ['ME'] command.

PORT METER LEVELS

ML <type> <card-num> <port-num> <left-lvl> <right-lvl>!

Where:

<type>	I = Input, O = Output

<card-num>	The number of the audio adapter.

<port-num>	The port number on the audio adapter.

<left-lvl>	Left channel level, in 100ths of dBFS.

<right-lvl>	Right channel level, in 100ths of dBFS.

OUTPUT STREAM METER LEVELS

MO <card-num> <stream-num> <left-lvl> <right-lvl>!

Where:

<card-num>	The number of the audio adapter.

<stream-num>	The stream number on the audio adapter.

<left-lvl>	Left channel level, in 100ths of dBFS.

<right-lvl>	Right channel level, in 100ths of dBFS.

OUTPUT STREAM POSITION

MP <card-num> <stream-num> <pos>!

Where:

<card-num>	The number of the audio adapter.

<stream-num>	The stream number on the audio adapter.

<pos>	The play position in mS.

OUTPUT STREAM STATUS

MS <card-num> <port-num> <stream-num> <status>!

Where:

<card-num>	The number of the audio adapter.

<port-num>	The port number on the audio adapter.

<stream-num>	The stream number on the audio adapter.

<status>	The status. 0 = Stopped, 1 = Playing.

Fred Gleason

2002-04-11T12:41:06

Fred Gleason