Rivendell Core Audio Control Protocol

Fred Gleason

Overview

Formats used for audio storage are Broadcast Wave Format (BWF), as specified in EBU Tech Pub 3285 with annexes.

Commands to the Core Audio Engine are passed by means of a TCP SOCK_STREAM connection to TCP port 5005 on the host server.

Commands have the following general syntax:

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

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

Pass a password to the server for authentication.

PW password!

password: A password to be supplied before granting the client access.

Returns: PW +! to indicate success, PW -! to indicate failure

Drop Connection

Drop the TCP connection and end the session.

DC!

Playback Operations

Load Playback

Prepare an audio interface to play an audio file.

LP card-num name!

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!

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

Free an audio playback interface.

UP conn-handle!

conn-handle: The connection handle of the playback event, from the Load Playback call.

Play Position

Position the playback pointer.

PP conn-handle position!

conn-handle: The connection handle of the playback event, from the Load Playback call.
position: Position in file, in milliseconds.

Play

Play the loaded file from the current position.

PY conn-handle length speed pitch-flag!

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.
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.

Stop Playback

Stop playback of the specified playback interface.

SP conn-handle!

conn-handle: The connection handle of the playback event, from the Load Playback call.

Timescaling Support

Query CAE if card-num supports timescaling.

TS card-num!

card-num: The number of the audio adapter to query.

Returns: TS card-num +|-!

Record Operations

Load Recording

Prepare an audio interface to capture an audio file.

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

card-num: The number of the audio adapter to query.
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, 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 PCM, 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

Free an audio capture interface.

UR card-num stream-num!

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.

Returns: UR card-num stream-num len!

len: Length of recording, in mS.

Record

Record a loaded file.

RD card-num stream-num length threshold!

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.

Stop Recording

Stop recording of the specified record interface.

SR card-num stream-num!

card-num: The number of the audio adapter.
stream-num: The stream number.

Record Start (Receive Only)

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).

RS card-num stream-num!

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

Set the volume of an input stream.

IV card-num stream-num level!

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

Set the volume of an output stream.

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

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

Transition the volume of an output stream over time.

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

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

Set the gain level of an input port.

IL card-num port-num level!

card-num: The number of the audio adapter to use.
stream-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

Set the gain level of an output port.

OL card-num port-num level!

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

Set the mode of an input stream.

IM card-num stream-num mode!

card-num

The number of the audio adapter to use.

port-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

Set the mode of an output stream.

OM card-num stream-num mode!

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

Set the VOX threshold level of an input stream.

IX card-num stream-num level!

card-num: The number of the audio adapter to use.
port-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

Set the signal type of an input port.

IT card-num port-num type!

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 mode, as follows:

0: Analog
1: AES3 Digital

Get Input Status

Request the status of an input port.

IS card-num port-num!

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.

Returns: IS card-num port-num status!

status

The status, as follows:

0: OK
1: No Sync

Set Audio Passthrough Level

Set the gain of an audio passthrough path.

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

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.

Set Clock Source

Set source of an audio adapter's sample clock. Relevant only for cards that feature AES3 inputs.

CS card-num input-num!

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.

External Operations

Open RTP Capture Channel

Open an RTP channel for audio capture.

CO card-num port-num udp-port samp-rate channels!

card-num: The number of the audio adapter to use.
udp-port: The port number on the remote system to which to send RTP packets.
samp-rate: The requested sample rate.
channels: The requested number of channels.

Returns: CO card-num port-num udp-port samp-rate chans pkt-size!

pkt-size: The number of bytes to send per UDP packet.

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!

Meter Commands

Meter Enable

Set UDP port to which to send meter update messages for the specified card(s).

ME udp-port card0 ..!

udp-port: UDP port number.
card0: Audio card number for which to send updates.

Meter Status Updates

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

Send current meter level of output stream

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

type

Type of meter.

I: Input
O: Output

card-num

The number of the audio adapter to use.

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

Send current meter level of output stream

MO card-num port-num left-lvl right-lvl!

card-num: The number of the audio adapter to use.
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 Position

Output play position.

MP card-num stream-num pos!

card-num: The number of the audio adapter to use.
stream-num: The stream number on the audio adapter.
pos: The play position in mS.

Output Stream Status

The current output stream transport status.

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

card-num

The number of the audio adapter to use.

port-num

The port number on the audio adapter.

stream-num

The stream number on the audio adapter.

status

Current transport status.

0: Stopped
1: Playing