Rivendell Core Audio Control Protocol

Fred Gleason


Table of Contents

Overview
Connection Management
Password
Drop Connection
Playback Operations
Load Playback
Unload Playback
Play Position
Play
Stop Playback
Timescaling Support
Record Operations
Load Recording
Unload Recording
Record
Stop Recording
Record Start (Receive Only)
Mixer Operations
Set Input Volume
Set Output Volume
Fade Output Volume
Set Input Level
Set Output Level
Set Input Mode
Set Output Mode
Set Input Vox Level
Set Input Type
Get Input Status
Set Audio Passthrough Level
Set Clock Source
External Operations
Open RTP Capture Channel
Meter Commands
Meter Enable
Meter Status Updates
Port Meter Levels
Output Stream Meter Levels
Output Stream Position
Output Stream Status

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