Rivendell Macro Language (or RML for short) is a set of commands implemented within Rivendell that can be used to program the system to take various actions. A wide variety of commands exist, ranging from control of outboard gear (such as switchers and GPIO devices) to control of various aspects of log playout in RDAirPlay, to Rivendell user management. The Normal form of a command takes the following syntax: cmd [arg] [...]! cmd A command mneumonic consisting of two alpha-numeric characters indicating the 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. 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 commands delivered to 5859 will be processed, but no reply made. If delivered to UDP port 5858, each command may receive a reply, formulated as follows: rpy +|- rpy The full command string (including arguments) originally received + ACK response, indicates success of the command. - NAK response, indicates failure of the command. In places where a color can be specified as a macro argument, the following predefined values are valid: white red green blue cyan magenta yellow gray lightGray black darkRed darkGreen darkBlue darkCyan darkMagenta darkYellow darkGray 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: %hexcode hexcode 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 Some commands (e.g. the Connect Jack Ports [JC] RML) require JACK port name arguments. Such port names have the following form: jack-client-name:jack-endpoint-name For example, to connect the first Rivendell audio output to the first available system playback ports, the following RML could be used: JC system:playback_1 rivendell_0:playout_0L! JC system:playback_2 rivendell_0:playout_0R! In this example, system and rivendell_0 are jack-client-names, while playback_1, playback_2, playout_0L and playout_0R are jack-endpoint-names. Note that two RML commands are required for this specific example. This is because JACK has no notion of stereo pairs, hence the "left" and "right" Rivendell playout ports have to be independently connected to the specific system playback ports. Some commands (e.g., MD, PL, and PS) require a log machine argument. See Log Machines in RDAirPlay for a detailed description of Log Machines. The log machine argument in the context of Rivendell macros must be an integer falling within one of the following values: 0 All non-virtual log machines --i.e. the Main Log, Aux 1 Log and Aux 2 Log log machines. 1 Main Log 2 Aux 1 Log 3 Aux 2 Log 101 through 120 Virtual Log 101 through Virtual Log 120 For example, the macro PL 1 0! starts playing at the first line (0) of the Main Log (log machine 1). Module ripcd8 Mnemonic AG Process an RML only if the On-Air flag is ON. AG rml! Execute RML rml only if the On-Air flag on the local machine is ON. Module rdairplay1, rdairplayd8 Mnemonic AL Append a log to a cuurently loaded log. AL mach logname! Append the log named logname to the log currently loaded in log machine mach. Module ripcd8 Mnemonic BO Output a string of binary codes. BO portnum hexcode ..! Output a string of binary codes represented by hexcode .. on serial port portnum. Module ripcd8 Mnemonic SC Clear a serial trap. SC portnum cart string! SC portnum cart! SC portnum! 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. Module ripcd8 Mnemonic CC Send RML to a remote host. CC dest[:udpport] rml! Execute the RML command rml on host dest, where dest may be either a Rivendell host name or an IP address. A UDP port value may be optionally specified as udpport (default value 5859). Module ripcd8 Mnemonic JC Connect a JACK input port to an output port. JC output input! Attempt to connect JACK input port input to output. See for an example. Module ripcd8 Mnemonic CL Set the label on a control surface. CL matrix surface chan label! On matrix matrix, set the input chan module label of control surface surface to label. Module rdcatchd8 Mnemonic CP Copy cut audio and metadata. CP srccart srccut dstcart dstcut! Copy the audio and metadata from cut number srccut in cart srccart to cut number dstcut in cart dstcart. The destination cart/cut must already exist. Module rdcatchd8 Mnemonic CE Place a cut event at the current location of an active RDCatch recording. CE decknum eventnum! Place a cut event with event number eventnum at the current position of the active recording in RDCatch Deck decknum. Module ripcd8 Mnemonic JD Disconnect a JACK input port from an output port. JD output input! Attempt to disconnect JACK input port input from output. Module ripcd8 Mnemonic JZ Disconnect all JACK audio port connections. JZ! Attempt to disconnect all JACK port connections. Module rdairplay1 Mnemonic PD Set the duck level of a SoundPanel button in RDAirPlay. PD panel col row level fade [mport]! Set the duck level of button at column, row of panel panel. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. If col and/or row is 0: duck all buttons in col or row. If playing, the audio fades to level (in db) in fade msecs. If specified, only stop carts playing on panel port mport. The duck level will be set to 0 after the playback is finished, or the button is stopped or reset. Module rdcartslots1 Mnemonic DX Execute a breakaway. DX slotlen! 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 to be aborted immediately and input audio restored. Module rdcatchd8 Mnemonic EX Execute a macro cart. EX cartnum! Execute macro cart cartnum on the local host. Module ripcd8 Mnemonic FS Execute a switcher salvo. FS matrix salvo! Fire salvo number salvo on matrix matrix. Module ripcd8 Mnemonic GE Enable/disable a GPI line. GE matrix type gpinum-spec state! Enable or disable the GPI line(s) of type type indicated by gpinum on matrix matrix. Possible types are: I Input O Output The gpinum-spec can be an integer value to indicate a single GPI line or a range specification to indicate multiple lines. A range specification has the following format: [first-value]:[last-value] All values in a range specification are inclusive. Some examples: 1:10 Lines 1 through 10, inclusive 5:10 Lines 5 through 10, inclusive 7:7 Line 7 :10 Lines 1 through 10, inclusive 1: Lines 1 onward, inclusive : All lines in the specified matrix Python programmers in the audience may be noticing similarities between range specifications and Python slices. The concepts are similar, but there are differences! Specifically: All values in range specifications are inclusive, whereas the stop parameter in a slice is last_value+1. There is no step parameter. All parameter values must be positive integers --i.e. zero- and negative-valued parameters are not supported. Module ripcd8 Mnemonic GE Enable/disable a GPI line. GE matrix gpinum-spec state! Enable or disable the GPI line(s) indicated by gpinum-spec on matrix matrix. The gpinum-spec can be an integer value to indicate a single GPI line or a range specification to indicate multiple lines. See above for examples of range specifications. Module ripcd8 Mnemonic GI Set action in response to a GPIO event. GI matrix type gpinum state cart! Execute the macro cart cart upon transition of the GPIO of type type and line gpinum on matrix matrix to state. Possible types are: I Input O Output Module ripcd8 Mnemonic GI Set action in response to a GPIO event. GI matrix gpinum state cart! Execute the macro cart cart upon transition of the GPIO of line gpinum on matrix matrix to state. Module ripcd8 Mnemonic GO Set the state of a GPIO line. GO matrix type gponum state length! Command GPIO line gponum 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 (valid only for Input type) Module ripcd8 Mnemonic GO Set the state of a GPIO line. GO matrix gponum state length! Command GPIO line gponum on matrix matrix> to state for length> mS. A length of 0 indicates to hold the state indefinitely. Module rdairplay1 Mnemonic PX Insert a cart in a log. PX mach cart [offset [PLAY|SEGUE|STOP]]! Insert cart cart after the currently playing or next event plus offset (default '0') lines on log machine mach. The transition may also be optionally specified. Module ripcd8 Mnemonic SI Insert a serial trap to detect a character sequence. SI portnum cart string! Insert a serial trap to execute the macro cart cart upon receipt of string on serial port port. Module rdairplay1 Mnemonic PC Set the label of a SoundPanel button in RDAirPlay. PC panel col row label color! Set the button at col, row of panel panel to have a text label of label and a background color of color. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. Module rdairplay1 Mnemonic LL Load a log into RDAirPlay. LL mach [logname] [startline]! Load the log logname in log machine mach. After loading, start the log at line startline if it is >=0. If startline is -2, the log will be started at the first event if that event does not have a 'stop' transition. Default startline=-1. If no log is specified, the machine's current log is unloaded. Module rdairplay1 Mnemonic LM Load a webpage into RDAirPlay's Message Area. LM url! Display the web page specified by url in the message widget. Module rdairplay1 Mnemonic PE Load a cart into a SoundPanel button in RDAirPlay. PE panel col row cart! Load cart cart into the button at col,row of panel panel. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. Module rdcartslots1 Mnemonic DL Load an RDCartSlots slot. 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 svcname! Set the slot slot to use service svcname. Omitting the svcname argument will cause the slot to be unloaded. This command will be ignored if the slot is currently executing a breakaway. Module ripcd8 Mnemonic LO Change the active Rivendell user context. 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. Module ripcd8 Mnemonic MT Timer for running macro carts. MT timernum timeout cart! Set the macro timer timernum to execute macro cart cart in timeout milliseconds. Setting timeout to 0 disables the timer. Sixteen macro timers (numbered 1-16) are available on each Rivendell host. Module rdairplay1 Mnemonic MN Load changes to a currently loaded log in RDAirPlay. RL mach line! Set the next event for log machine mach to line line. Module ripcd8 Mnemonic MB Display a popup message box on a host display. 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 When using the 'Message Box' ['MB'] RML, it may be necessary to configure the X server to allow local connections from other processes. One way to do this is to execute the following command as the local Rivendell user: xhost +local: For more information, see the xhost1 man page. Module none Mnemonic NN Do nothing. NN! This RML does precisely nothing. Module rdairplay1 Mnemonic PU Pause a SoundPanel button in RDAirPlay. PU panel col row [mport]! Pause the button at col, row of panel panel. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. If col and/or row is 0: pause all playing buttons in col or row. If specified, start the playout on panel port mport. In order for paused buttons to work, the Enable Button Pausing checkbox must be ticked on the Configure RDAirPlay dialog in rdadmin1. Module rdairplay1 Mnemonic PP Load a cart into a SoundPanel button in RDAirPlay. PP panel col row [mport] [0|1]! Play the button at col, row of panel panel. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. If col 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. Module rdcartslots1 Mnemonic DP Play an RDCartSlots slot. 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. Module rdairplay1 Mnemonic RL Load changes to a currently loaded log in RDAirPlay. RL mach! Refresh the log currently loaded in log machine mach. Module ripcd8 Mnemonic RN Run a shell command. RN cmd! Run the shell command cmd. The command is actually executed as: /bin/sh -c cmd using the user and group specified by the "RnRmlOwner=" and "RnRmlGroup=" directives in the "[Identity]" section of rd.conf5. Module rdairplay1 Mnemonic PW Select right-hand widget in RDAirPlay. PW mach! Select right-hand widget to log-machine mach or 0 for sound panel or 4 for voice tracker. Module ripcd8 Mnemonic SO Output a string on a serial port. SO portnum data! Output data on serial port portnum. data can consist of arbitrary binary data as well as textual characters (see above). Module ripcd8 Mnemonic SY Reload the configuration for a serial port. SY portnum! Reload the configuration for serial port portnum. Normally, this should only be issued by RDAdmin following a configuration change. Module rdairplay1 Mnemonic LC Display a color message in the label widget on RDAirPlay. LC color string! Display string in color color in the message widget. For the list of available colors, see . Module rdairplay1 Mnemonic SN Set the default Now & Next cart. SN now|next mach cart! Set the default Now & Next cart for log mach to cart. Module ripcd8 Mnemonic SD Set a console display. 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 Bits 6,5 Video attribute Bit 2,1,0 Message Text Color Display Mode: 0 Overwrite text 1 Insert text Video Attribute: 00 Normal 01 Flash 02 Reverse Text Color: 000 White 001 Red 010 Yellow 011 Green 100 Cyan 101 Magenta Module rdairplay1 Mnemonic MD Set duck level for an RDAirPlay log machine. MD mach level fade [mport]! Set the duck level of mach, or 0 for all log machines. If playing, the audio fades to level (in db) 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. Module rdairplay1 Mnemonic LB Display a message in the label widget on RDAirPlay. LB string! Display string in the message widget. Module rdairplay1 Mnemonic PM Set the mode of an RDAirPlay log machine. PM mode [mach]! Set log machine mach to mode mode. If mode is not given or the Mode Control Style is set to 'Unified', then all log machines are set to mode. Valid values for mode are: 1 LiveAssist 2 Auto 3 Manual See for the possible values of mach. Module ripcd8 Mnemonic SP Pause for specified time. SP msecs! Wait for msecs milliseconds. Module rdairplay1 Mnemonic PL Start a log at a specified line. PL mach line! Start log machine mach at line line if stopped, otherwise do nothing. Module rdairplay1 Mnemonic PB Push an RDAirPlay Start button (numbered starting from 1 at the top and counting downwards). PB button! Push button button. Module rdairplay1 Mnemonic PN Start the next event in a log. PN mach [mport] [skip]! Start log machine mach if stopped, or start next event if already running. If specified, start the playout on machine port mport. If skip 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. Module rdcatchd8 Mnemonic RS Start an RDCatch Recording RS decknum cartnum cutnum maxlen! Start recording to cut cutnum of cart cartnum, using RDCatch record deck decknum for a maximum time of maxlen 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. Module rdairplay1 Mnemonic PS Stop a log in RDAirPlay. 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. Module rdairplay1 Mnemonic PT Stop a SoundPanel button in RDAirPlay. PT panel col row [mport] [0|1] fade! Stop the button at col, row of panel panel. Panel: S1...S50 or U1...U50; C for panel means currently selected panel. If col and/or row is 0: stop all playing buttons in col or row. If specified, stop the playout on panel port mport, applying a fade of duration fade milliseconds. If the 5th argument is 1, the button will enter the paused state after the fade completes. In order for paused buttons to work, the Enable Button Pausing checkbox must be ticked on the Configure RDAirPlay dialog in rdadmin1. Module rdcatchd8 Mnemonic RR Stop an RDCatch Recording RR decknum! Stop any active recording on RDCatch deck decknum. Module rdcartslots1 Mnemonic DS Stop an RDCartSlots slot. 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 already playing. Module ripcd8 Mnemonic SA Add an input to an output. SA matrix input output! Command switch matrix number matrix to add input number input to output number output. Unlike SWITCH TAKE, this command leaves any other previously assigned inputs unchanged. Module ripcd8 Mnemonic SG Add an input to an output while specifyng the crosspoint gain. SG matrix input output gain! Command switch matrix number matrix to add input number input to output number output 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. Module ripcd8 Mnemonic SX Set crosspoint gain. SX matrix input output level! Command switch matrix number matrix to adjust the gain of the crosspoint connecting input input to output output to level dB. Module ripcd8 Mnemonic SL Set input gain. SL matrix input level! Command switch matrix number matrix to adjust the gain of input number input to level dB. Module ripcd8 Mnemonic SZ Reload the configuration for a switch matrix. SZ matrix! Reload the configuration for switch matrix matrix. Normally, this should only be issued by RDAdmin following a configuration change. Module ripcd8 Mnemonic SR Remove an input from an output. SR matrix input output! Command switch matrix number matrix to remove input number input from output number output. Unlike SWITCH TAKE, this command leaves any other previously assigned inputs unchanged. Module ripcd8 Mnemonic ST Exclusively route an input to an output. ST matrix input output! Command switch matrix number matrix to take input number input to output number output. "Take" in this context implies removing any previously assigned inputs from the referenced output. Module ripcd8 Mnemonic TA Set the state of the On Air flag. TA 0|1! Set the On-Air flag to ON [1] or OFF [0]. Module ripcd8 Mnemonic UO Send data to a UDP port. UO ipaddr udpport data! Send data in a UDP packet to port udpport at ipaddr. data can consist of arbitrary binary data as well as textual characters (see for details).