Rivendell Macro Language

v1.0.0

SCOPE

Rivendell Macro Language (RML) is a system of commands formulated to specify actions to be taken by and within the Rivendell Radio Automation system.

PROTOCOL

COMMAND SYNTAX

The Normal form of a command takes the following syntax:

<cmd> [<arg0>] [...] [<argn>]!

where:

<cmd>	A command mneumonic consisting of two alpha-numeric characters indicating	the action to be performed

<argn>	Zero or more arguments to the command.

In addition to the Normal form, and expanded form, consisting of plain English words in place of the two-letter command mneumonics is also supported.

COMMAND DELIVERY

To be executed by a Rivendell system, an appropriate command should be delivered to UDP ports 5858 or 5859 on said system, using the SOCK_DGRAM connectionless protocol. Commands delivered to port 5858 may receive a reply back to the originating IP address at UDP socket 5860 to indicated command success/failure, while commanders delivered to 5859 will be processed, but no reply made.

COMMAND REPLY

If delivered to UDP port 5858, each command may receive a reply, formulated as follows:

<cmdstr> +|-!

where:

<cmdstr>	The full command string (including arguments) originally received

+	ACK response, indicates success of the command.

-	NAK response, indicates failure of the command.

SPECIFYING COLOR

In places where a color can be specified as a macro argument, the following predefined values are valid:

white	black

red	darkRed

green	darkGreen

blue	darkBlue

cyan	darkCyan

magenta	darkMagenta

yellow	darkYellow

gray	darkGray

lightGray

BINARY DATA

Certain commands (e.g. SO and UO) have the ability to transmit arbitrary binary data in addition to textual characters. Such arbitrary binary data can be specified by means of escape codes as follows:

%<hex-code>

where:

<hex-code> Two digit numeric value of the byte to send in hexidecimal.

For example, the sequence 'TEST' followed by a carriage return/newline could be specified as:

TEST%0D%0A

RDCartSlots COMMANDS

The following set of commands are processed by RDCartSlots(1).

LOAD SLOT

Mnemonic: DL

This command has two syntaxes, depending upon the mode of the slot.

Cart Deck Mode Syntax:

DL <slot> <cart>!

Load the cart <cart> into the <slot> slot. Passing a '0' for <cart> will cause the slot to be unloaded. This command will be ignored if the slot is currently playing.

Breakaway Mode Syntax:

DL <slot> <svc-name>!

Load the service <svc-name> into the <slot> slot. Omitting the <svc-name> argument will cause the slot to be unloaded. This command will be ignored if the slot is currently executing a breakaway.

PLAY SLOT

Mnemonic: DP

Syntax:

DP <slot>!

Play the cart currently loaded in the <slot> slot. The slot must be in Cart Deck mode. This command will be ignored if the slot is unloaded or already playing.

STOP SLOT

Mnemonic: DS

Syntax:

DS <slot>!

Stop the cart currently loaded in the <slot> slot. The slot must be in Cart Deck mode. This command will be ignored if the slot is unloaded or not playing.

EXECUTE BREAKAWAY

Mnemonic: DX

Syntax:

DX <slot> <len>!

Execute a breakaway of length <len> (in mS) using the autofill carts configured for the service currently loaded in the <slot> slot. The slot must be in Breakaway mode. If a breakaway is currently executing, it will immediately be aborted and a new one started. Passing a '0' for <len> will cause any currently executing breakaway immediately to be aborted and input audio restored.

RDCATCHD COMMANDS

The following set of commands are processed by rdcatchd(8).

EXECUTE CART

Mnemonic: EX

Syntax:

EX <cart>!

Execute macro cart <cart> on the local station.

RIPCD COMMANDS

The following set of commands are processed by ripcd(8). Not all commands are supported by all types of underlying hardware. Unsupported commands should receive an NAK response.

BINARY SERIAL OUT

Mnemonic: BO

Syntax:

BO <port-num> <hex-code> <...>!

Output a string of binary codes represented by <hex-code> <...> on serial port <port-num>!

COMMAND SEND

Mnemonic: CC

Syntax:

CC <dest>[:<udp-port>] <rml>!

Send the RML command <rml> to <dest>. <dest> may be either a Rivendell host name or an IP address. A UDP port value may be optionally specified as <udp-port> (default value 5859).

CONSOLE LABEL

Mnemonic: CL

Syntax:

CL <matrix> <surface> <chan> <label>!

On matrix <matrix>, set the input <chan> module label of control surface <surface> to <label>.

CONNECT JACK PORTS

Mnemonic: JC

Syntax:

JC <output-port> <input-port>!

Attempt to connect JACK input port <input-port> to <output-port>.

DISCONNECT JACK PORTS

Mnemonic: JD

Syntax:

JD <output-port> <input-port>!

Attempt to disconnect JACK input port <input-port> to <output-port>.

MESSAGE BOX

Mnemonic: MB

Syntax:

MB <display> <severity> <msg>!

Display the text <msg> in a popup window on X display <display>, with an icon to indicate <severity>. Valid values of <severity> are:

1 – Information

2 – Warning

3 - Critical

SET DISPLAY

Mnemonic: SD

Syntax:

SD <matrix> <display> <line> <col> <attr> <label>!

On matrix <matrix>, set the console display <display> to <label>, starting at position <line>,<col> and using message attributes <attr>.

The message attributes value is constructed as follows:

Bit 7 – Display mode

Bit 6,5 – Video attribute

Bits 2,1,0 – Message Text Color

Display Mode:	0 – overwrite text

1 – insert text

Video Attribute:	00 – normally

01 – flash

02 – reverse

Text Color:	000 - White

001 - Red

010 - Yellow

011 - Green

100 - Cyan

101 – Magenta

DATABASE BACKUP

Mnemonic: DB

Syntax:

DB <path-name>!

Create a backup copy of the active Rivendell database in <pathname>.

FIRE SALVO

Mnemonic: FS

Syntax:

FS <matrix> <salvo-num>!

Fire salvo number <salvo-num> on matrix <matrix>.

GPI ENABLE

Mnemonic: GE

Syntax:

GE <matrix> <type> <gpi-num> <state>!

Enable or disable the GPI line of type <type> indicated by <gpi-num> on matrix <matrix>. Possible types are I=Input, O=Output.

GPI ENABLE (old format, deprecated)

Mnemonic: GE

Syntax:

GE <matrix> <gpi-num> <state>!

Enable or disable the GPI line indicated by <gpi-num> on matrix <matrix>.

GPI SET

Mnemonic: GI

Syntax:

GI <matrix> <type> <gpi-num> <state> <cart>!

Issue the macro cart <cart> upon transition of the GPIO of type <type> and line <gpi-num> on matrix <matrix> to <state>. Possible types are I=Input, O=Output.

GPI SET (old format, deprecated)

Mnemonic: GI

Syntax:

GI <matrix> <gpi-num> <state> <cart>!

Issue the macro cart <cart> upon transition of the GPI line <gpi-num> on matrix <matrix> to <state>.

GPO SET

Mnemonic: GO

Syntax:

GO <matrix> <type> <gpo-num> <state> <length>!

Command GPIO line <gpo-num> of type <type> on matrix <matrix> to <state> for <length> mS. A length of '0' indicates to hold the state indefinitely. Possible types are I=Input, O=Output. Possible states are 0=OFF, 1=ON, -1=passthrough hardware input. The 'passthrough' state is valid only for the Input type –i.e. <type>=I.

GPO SET (old format, deprecated)

Mnemonic: GO

Syntax:

GO <matrix> <gpo-num> <state> <length>!

Command GPO line <gpo-num> on matrix <matrix> to <state> for <length> mS. A length of '0' indicates to hold the state indefinitely.

LOGIN

Mneumonic: LO

Syntax:

LO!

LO <user> <password>!

Set the current Rivendell user to <user>. If no arguments are supplied, log out the station –i.e. Revert to the default user.

RUN SHELL COMMAND

Mneumonic: RN

Syntax:

RN <shell-cmd>!

Run the shell command <shell-cmd>.

SERIAL OUT

Mneumonic: SO

Syntax:

SO <port-num> <data>!

Output <string> on serial port <port-num>! <data> can consist of arbitrary binary data as well as textual characters (see Binary Data above).

INSERT SERIAL TRAP

Mneumonic: SI

Syntax:

SI <port> <cart> <string>!

Insert a serial trap to execute the macro cart <cart> upon receipt of <string> on serial port <port>.

CLEAR SERIAL TRAP

Mneumonic: SC

Syntax:

SC <port> <cart> <string>!

SC <port> <cart>!

SC <port>!

Clear a serial trap. The three argument form will clear all traps on <port> that reference <cart> and <string>. The two argument form will clear all traps on <port> that reference <cart>, while the one argument form will clear all traps on <port>.

SLEEP

Mnemonic: SP

Syntax:

SP <msecs>!

Wait for <msecs> milliseconds.

SWITCH ADD

Mnemonic: SA

Syntax:

SA <matrix> <source> <dest>!

Command switch matrix number <matrix> to add input number <source> to output number <dest>. Unlike SWITCH TAKE, this command leaves any other previously assigned inputs unchanged.

SWITCH ADD WITH GAIN

Mnemonic: SG

Syntax:

SG <matrix> <source> <dest> <gain>!

Command switch matrix number <matrix> to add input number <source> to output number <dest> at gain <gain>. The gain is specified in 1/10 of a dB, with 0 = unity gain. Unlike SWITCH TAKE, this command leaves any other previously assigned inputs unchanged.

SWITCH LEVEL

Mneumonic: SL

Syntax:

SL <matrix> <source> <level>!

Command switch matrix number <matrix> to adjust the gain of input number <source> to <level> dB.

SWITCH CROSSPOINT GAIN

Mnemonic: SX

Syntax:

SX <matrix> <source> <dest> <level>!

Command switch matrix number <matrix> to adjust the gain of the crosspoint connecting input <source> to output <dest> to <level> dB.

SERIAL RELOAD

Mneumonic: SY

Syntax:

SY <port-num>!

Reload the configuration for the indicated serial port. Normally, this should only be issued by RDAdmin following a configuration change.

SWITCH RELOAD

Mneumonic: SZ

Syntax:

SZ <matrix>!

Reload the configuration for the indicated matrix. Normally, this should only be issued by RDAdmin following a configuration change.

SWITCH REMOVE

Mneumonic: SR

Syntax:

SR <matrix> <source> <dest>!

Command switch matrix number <matrix> to remove input number <source> to output number <dest>. Unlike SWITCH TAKE, this command leaves any other previous assigned inputs unchanged.

SWITCH TAKE

Mneumonic: ST

Syntax:

ST <matrix> <source> <dest>!

Command switch matrix number <matrix> to take input number <source> to output number <dest>. “Take” in this context implies removing any previously assigned inputs from the referenced output.

TOGGLE ON AIR FLAG

Code: TA

Syntax:

TA 0|1!

Set the On-Air flag to ON [1] or OFF [0].

UDP OUT

Mneumonic: UO

Syntax:

UO <ip-addr> <udp-port> <data>!

Send <data> in a UDP packet to port <udp-port> at <ip-addr>. <data> can consist of arbitrary binary data as well as textual characters (see Binary Data above).

MACRO TIMER

Mneumonic: MT

Syntax:

MT <timer-no> <timeout> <cart-num>!

Set the macro timer <timer-no> to execute macro cart <cart-num> in <timeout> milliseconds. Setting <timeout> to '0' disables the timer. Sixteen macro timers (numbered 1 – 16) are available on each Rivendell host.

RDCATCHD COMMANDS

The following set of commands are processed by rdcatchd(8).

START RECORD DECK

Mneumonic: RS

Syntax:

RS <deck-num> <cart-num> <cut-num> <max_len>!

Start recording to cut <cut-num> of cart <cart-num>, using RDCatch record deck <deck-num> for a maximum time of <max-len> mS. The record parameters used (format, sample rate, channels, etc) will be those configured for the selected deck in RDAdmin->ManageHosts->RDCatch. The selected cart and cut must already exist. Any audio previously residing in the selected cart and cut will be overwritten.

STOP RECORD DECK

Mneumonic: RR

Syntax:

RR <deck-num>!

Stop any active recording on RDCatch deck <deck-num>.

RDAIRPLAY COMMANDS

The following set of commands are processed by rdairplay(1).

LOAD LOG

Mneumonic: LL

Syntax:

LL <mach> [<log>] [<start-line>]!

Load the log <log> in log machine <mach>. After loading, start the log at line <start-line> if it is >=0. If <start-line> is -2, the log will be started at the first event if that event does not have a 'stop' transition. Default <start-line>=-1. If no <log> is specified, the machine's current log is unloaded.

REFRESH LOG

Mneumonic: RL

Syntax:

RL <mach>!

Refresh the log currently loaded in log machine <mach>.

MAKE NEXT

Mneumonic: MN

Syntax:

MN <mach> <line>!

Set the next event for log machine <mach> to line <line>.

START

Mneumonic: PL

Syntax:

PL <mach> <line>!

Start log machine <mach> at line <line> if stopped, otherwise do nothing.

START BUTTON

Mneumonic: PB

Syntax:

PB <button>!

Push button <button>.

START NEXT

Mneumonic: PN

Syntax:

PN <mach> [<mport>] [<skip-meta>]!

Start log machine <mach> if stopped, or start next event if already running. If specified, start the playout on machine port <mport>. If <skip-meta> is supplied, equal to '1' and the log machine is in Manual or Live Assist mode, then any intervening meta-events in log between the current 'next' event and the next cart will be skipped over.

STOP

Mneumonic: PS

Syntax:

PS <mach>|0 [<fade>] [<mport>]!

Stop log machine <mach>, or '0' for all log machines. If specified, only stop carts playing on machine port <mport>. If specified: Fade out <fade> msecs.

SET DUCK LEVEL

Mneumonic: MD

Syntax:

MD <mach>|0 <level> <fade> [<mport>]!

Set the duck level of <mach>, or '0' for all log machines. If playing, the audio fades to <level> (in dbFS) in <fade> msecs. If specified, only affect carts playing on machine port <mport>.

Loading or clearing a log will set the duck level back to 0.

ADD NEXT

Mneumonic: PX

Syntax:

PX <mach> <cart>!

Insert cart <cart> in the next to play position on log machine <mach>.

SET MODE

Mneumonic: PM

Syntax:

PM <mode> [<mach>]!

Set log machine <mach> to mode <mode>. 1 = LiveAssist, 2 = Auto, 3 = Manual. If mode is not given or the Mode Control Style is set to 'Unified', then all log machines are set to <mode>.

SELECT WIDGET

Mneumonic: PW

Syntax:

PW <mach>|0!

Select right-hand widget to log-machine <mach> or '0' for sound panel.

LABEL PANEL

Mneumonic: PC

Syntax:

PC <panel> <column> <row> <label> <color>!

Set the button at <column>,<row> of panel <panel> to have a text label of <label> and a background color of <color>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

LOAD PANEL

Mneumonic: PE

Syntax:

PE <panel> <column> <row> <cart>!

Load cart <cart> into the button at <column>,<row> of panel <panel>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

PLAY PANEL

Mneumonic: PP

Syntax:

PP <panel> <column> <row> [<mport>] [<stay active: 0|1>]!

Play the button at <column>,<row> of panel <panel>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

If <column> and/or <row> is 0: Start the first loaded button that is not active.

If specified, start the playout on panel port <mport>.

The started panel will stay active when finished, if the 5th argument is 1.

PAUSE PANEL

Mneumonic: PU

Syntax:

PU <panel> <column> <row> [<mport>]!

Pause the button at <column>,<row> of panel <panel>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

If <column> and/or <row> is 0: Pause all playing buttons in column/row.

If specified, pause only if playing on panel port <mport>.

STOP PANEL

Mneumonic: PT

Syntax:

PT <panel> <column> <row> [<mport>] [<stay active: 0|1>] [<fade>]!

Stop the button at <column>,<row> of panel <panel>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

If <column> and/or <row> is 0: Stop all playing buttons in column/row.

If specified, stop only if playing on panel port <mport>.

The stopped panel will stay active, if the 5th argument is 1.

If specified: Fade out <fade> msecs.

DUCK PANEL BUTTON

Mneumonic: PD

Syntax:

PD <panel> <column> <row> <level> <fade> [<mport>]!

Set the duck level of button at <column>,<row> of panel <panel>.

Panel: S1...50 or U1...50; C for <panel> means currently selected panel.

If <column> and/or <row> is 0: Duck all buttons in column/row.

If playing, the audio fades to <level> (in dbFS) in <fade> msecs.

If specified, only stop carts playing on panel port <mport>.

The duck level will be set to 0 after the playback was finished, or the button was stopped or reseted.

SET LABEL

Mneumonic: LB

Syntax:

LB <string>!

Display <string> in the message widget.

SET COLOR LABEL

Mneumonic: LC

Syntax:

LC <color> <string>!

Display <string> in color <color> in the message widget.

SET DEFAULT NOW & NEXT CART

Mneumonic: SN

Syntax:

SN now|next <mach> <cart>!

Set the default Now or Next cart for log <mach> to <cart>.

Fred Gleason

2003-12-11T15:50:03