Agile Live Rendering Engine command documentation

This page describes all the commands available in the Agile Live Rendering Engine.

Command protocol

All commands to the Agile Live Rendering Engine is sent as human readable strings and are listed below. The Rendering Engine expect no line termination, meaning that you do not need to append any type of new line (\n) characters, or string termination (\0) characters.

Video commands

The data path graph of the video mixer in the Rendering Engine looks as follows:

There are four nodes that can be controlled using the protocol. The Transition node is used to pick which input slots to use for the program and preview output. The node also supports making transitions between the program and preview. The video mixer can overlay graphics on top of the background image using the two nodes Alpha combine and Alpha over. The Alpha combine node is used to pick two input slots (or the same input slot) to copy the color from one input and combine it with some information from the other input to form the alpha. The color will just be copied from the color input frame, but there are several modes that can be used to produce the alpha channel in the output frame in different ways. Then the Alpha over node is used to perform an “Alpha Over” operation, that is to put the overlay video stream on top of the background video stream, and let the background be seen through the overlay depending on the alpha of the overlay. The node also features fading the graphics in and out by multiplying the alpha channel by a constant factor.

The video mixer can be controlled with the following commands:

• cut <input_slot> - Cut (hot punch) the program output to the given input slot. This won’t affect the preview output.
• preview <input_slot> - Preview the given input slot. This won’t affect the program output.
• cut - Cut between the current program and preview outputs, effectively swapping their place.
• fade <duration_ms> - Perform an automatic fade from the current program output to the current preview output, lasting for <duration> milliseconds.

In addition to this the graphics pipeline can be controlled with these commands:

• alpha_combine color <input_slot> - Set which input slot to copy the color data from in the Alpha combine node
• alpha_combine alpha <input_slot> - Set which input slot to use to create the alpha channel of the output frame in the Alpha combine node
• alpha_combine mode <mode> - Set which way the alpha channel of the output frame will be produced. Valid modes are:
  • copy-r - Copy the R-channel of the input “alpha frame” and use it as alpha for the output.
  • copy-g - Copy the G-channel of the input “alpha frame” and use it as alpha for the output.
  • copy-b - Copy the B-channel of the input “alpha frame” and use it as alpha for the output.
  • copy-a - Copy the A-channel of the input “alpha frame” and use it as alpha for the output.
  • average-rgb - Take the average of the R, G and B channels of the input “alpha frame” and use it as alpha channel for the output.
• alpha_over factor <factor> - Manually set the transparency multiplier for the Alpha over node. The value <factor> should be a float between 0.0 and 1.0, where 0.0 means that the overlay is completely invisible and 1.0 means that the overlay is fully visible (where it should be visible according to the overlay image’s alpha channel). Default is 0.0.
• alpha_over fade to <duration_ms> - Start an automatic fade from the current factor to a fully visible overlay over the duration of <duration_ms> milliseconds.
• alpha_over fade from <duration_ms> - Start an automatic fade from the current factor to a fully invisible overlay over the duration of <duration_ms> milliseconds.

And before the final output, the video stream can be faded to/from black using these commands:

• fade_to_black factor <factor> - Manually set the blackness factor on a scale from 0.0 to 1.0, where 0.0 means not black and 1.0 means fully black output.
• fade_to_black fade to <duration_ms> - Start an automatic fade to a fully black output over the duration of <duration_ms> milliseconds.
• fade_to_black fade from <duration_ms> - Start an automatic fade to a fully visible (non-black) output over the duration of <duration_ms> milliseconds.

Audio commands

The audio mixer has the following data path:

In the example three sources are connected to input slots 3, 4 and 9. The audio mixer is completely separate from the video mixer, so switching image in the video mixer will not change the audio mixer in any way.

• volume <input_slot> <level> - Set the volume level of a specific input in proportion to its original strength. Parameter <level> should be a floating point number, where 0.0 means that the input slot is not mixed into the output and 1.0 means that the volume of the input slot is kept as is for the output. The signal can also be amplified by using values > 1.0. Default is 0.0.
• mastervolume <level> - Set the volume level of the master output, before the audio is clamped and converted from floating point samples to 16-bit integer samples. This can be used to avoid clipping of the audio when mixing multiple input sources. Parameter <level> is a floating point number where 0.0 means that all audio output is off, 1.0 means that the volume is not changed and any value above 1.0 means that the master volume is amplified.