# Rivendell Core Audio Control Protocol

0.9.1
Fred
Gleason
fredg@paravelsystems.com

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

### `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!

## JACK Operations

### `Connect Ports`

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

`JC output-name input-name!`

output-name

  The name of the JACK output port, in format CLIENTNAME:PORTNAME.

input-name

  The name of the JACK input port, in format CLIENTNAME:PORTNAME.

### `Disconnect Ports`

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

`JD output-name input-name!`

output-name

  The name of the JACK output port, in format CLIENTNAME:PORTNAME.

input-name

  The name of the JACK input port, in format CLIENTNAME:PORTNAME.

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