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

### 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 whcih to send meter update messages.

`ME `udp-port`!`

`udp-port`

  UDP port number.

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