The following is a rendering of the OpenAPI for the Agile Live System Controller using Swagger. It does not have a backend server, so it cannot be run interactively.

This API is available from the server at the base URL /api/v3.

1.2 - Agile Live Rendering Engine configuration documentation

Reference for the Agile Live Rendering Engine configuration

This page describes how to configure the Rendering Engine. This topic is closely related to this page on the control command protocol for the video and audio mixers.

Rendering Engine components

The Rendering Engine is an application that uses the Production Pipeline library in the base platform for transport, and adds to that media file playback, HTML rendering, a full video mixer and an audio router and audio mixer. The figure below shows a schematic of the different components and an example of how streams may transition through it.

The rendering engine and its components

HTML Renderers

Multiple HTML renderers can be instantiated in runtime by control panels, and in each an HTML page can be opened. Each HTML renderer produces a video stream, but no audio.

Media Players

Multiple media players can be instantiated in runtime by control panels, and in each a media file can be opened. Each media player produces a stream containing a video stream and all audio streams from the file.

Video Mixer

The Video mixer receives all video inputs into the system, i.e. streams from ingests, from HTML renderers and from media players. It outputs one or more named video output streams. The internal structure of the video mixer is defined at startup (as decribed in detail below), and controlling the video mixer is done in runtime by control panels.

Audio Router

The audio router receives all audio streams into the system, i.e. streams from ingests and from media players. It outputs a set of streams that are either mono or a stereo pair, to the audio mixer. The mappings from input streams to output streams in the router is configured in runtime by control panels.

Audio Mixer

Note

The audio mixer can be either our internal audio mixer or an integration towards an external third party audio mixer. The rest of the documentation here is valid for the internal audio mixer.

The audio mixer takes a number of mono or stereo pair streams as inputs that we call input strips. It outputs a number of named output streams in stereo. The outputs of the audio mixer are defined at startup, and the audio mixer is controlled in runtime by control panels.

Combine outputs

The combination of video and audio outputs into full output streams from the rendering engine is configured at startup.

Configuring the Rendering Engine

Some aspects of the rendering engine can be configured statically at startup through the use of a configuration file in JSON format. Specifically, the video mixer node graph, the audio mixer outputs and the combination of video and audio outputs can be configured. As an example, here is such a JSON configuration file that we will refer to throughout this guide:

{
  "version": "1.0",
  "video": {
    "nodes": {
      "transition": {
        "type": "transition"
      },
      "chroma_key_select": {
        "type": "select"
      },
      "chroma_key": {
        "type": "chroma_key"
      },
      "chroma_key_alpha_over": {
        "type": "alpha_over"
      },
      "fade_to_black": {
        "type": "fade_to_black"
      },
      "program": {
        "type": "output"
      },
      "chroma_key_preview": {
        "type": "output"
      },
      "preview": {
        "type": "output"
      }
    },
    "links": [
      {
        "from_node": "transition",
        "from_socket": 0,
        "to_node": "chroma_key_alpha_over",
        "to_socket": 1
      },
      {
        "from_node": "transition",
        "from_socket": 1,
        "to_node": "preview",
        "to_socket": 0
      },
      {
        "from_node": "chroma_key_select",
        "from_socket": 0,
        "to_node": "chroma_key",
        "to_socket": 0
      },
      {
        "from_node": "chroma_key",
        "from_socket": 0,
        "to_node": "chroma_key_alpha_over",
        "to_socket": 0
      },
      {
        "from_node": "chroma_key_alpha_over",
        "from_socket": 0,
        "to_node": "fade_to_black",
        "to_socket": 0
      },
      {
        "from_node": "fade_to_black",
        "from_socket": 0,
        "to_node": "program",
        "to_socket": 0
      },
      {
        "from_node": "chroma_key",
        "from_socket": 0,
        "to_node": "chroma_key_preview",
        "to_socket": 0
      }
    ]
  },
  "audio": {
    "outputs": [
      {
        "name": "main",
        "channels": 2
      },
      {
        "name": "aux1",
        "channels": 2,
        "follows": "main"
      },
      {
        "name": "aux2",
        "channels": 2
      }
    ]
  },
  "output_mapping": [
    {
      "name": "program",
      "video_output": "program",
      "audio_output": "main",
      "feedback_input_slot": 1001,
      "stream": true
    },
    {
      "name": "preview",
      "video_output": "preview",
      "audio_output": "",
      "feedback_input_slot": 1002,
      "stream": false
    },
    {
      "name": "aux1",
      "video_output": "program",
      "audio_output": "aux1",
      "feedback_input_slot": 0,
      "stream": true
    },
    {
      "name": "chroma_key_preview",
      "video_output": "chroma_key_preview",
      "audio_output": "aux2",
      "feedback_input_slot": 100,
      "stream": true
    }
  ]
}

Video Mixer node graph

The video mixer is defined as a tree graph of nodes that work together in sequence to produce one or several video outputs. Each node performs a specific action, and has zero or more input sockets and zero or more output sockets. Links connect output sockets on one node to input sockets on other nodes. Each node is named and the name is used to control the node in runtime. The node tree configuration is specified in the video section of the JSON file, which contains two parts: the list of nodes and the list of links connecting the nodes.

The following is a graphical representation of the video mixer node graph configuration in the JSON example file above, with two input nodes, three processing nodes and three output nodes, and links in between:

Video mixer node graph example

Video nodes block

The nodes object of the video block is a JSON object where the names/keys in the object is the unique name of the node. The name is used to refer to the node when operating the mixer later on, so names that are easy to understand what they are supposed to be used for in the production is recommended. The name can only contain lower case letters, digits, _ and -. Space or other special characters are not allowed.

Each node is an JSON object with parameters defining the node properties. Here the parameter type defines which type of node it is. The supported types are listed below. They can be divided into three groups depending on if they provide input to the graph, output from the graph or is a processing node, placed in the middle of the graph.

Input nodes

The input nodes take their input from the input slots of the Rendering Engine, which contains the latest frame for all connected sources (this includes connected cameras, HTML graphics, media players etc.) The nodes in this group does not have any input sockets, as they take the input frames from the input slots of the Rendering Engine. Which slot to take the frames from is dynamically controlled during runtime.

Alpha combine node (alpha_combine)
Input sockets: 0 (Sources are taken from the input slots of the mixer)
Output sockets: 1
The alpha combine node takes two inputs and combines the color from one of them with the alpha from the other one. The node features multiple modes that can be set during runtime to either pick the alpha channel of the second video input, or to take any of the other R, G and B channels, or to average the RGB channels and use as alpha for the output. This node is useful in case videos with alpha is provided from SDI sources, where the alpha must be sent as a separate video feed and then combined with the fill/color source in the mixer.

Select node (select)
Input sockets: 0 (Source is taken from the input slots of the mixer)
Output sockets: 1
The select node simply selects an input slot from the Rendering Engine and forwards that video stream. Which input slot to forward is set during runtime. The node is a variant of the transition node, but does not support the transitions supported by the transition node.

Transition node (transition)
Input sockets: 0 (Sources are taken from the input slots of the mixer)
Output sockets: 2 (One with the program output and one with the preview output)
The transition node takes two video streams from the Rendering Engine’s input slots, one to use as the program and one as the preview output stream. These are output through the two output sockets. During runtime this node can be used to make transitions such as wipes and fades between the selected program and preview.

Output nodes

This group only contains a single node, used to mark a point where processed video can exit the graph and be used in output mappings.

Output node (output)
Input sockets: 1
Output sockets: 0 (Output is sent out of the video mixer)
The output node marks an output point in the video mixer’s graph, where the video stream can be used by the output mapping to be included in the Rendering Engine’s Output streams, or as streams to view in the multi-viewer. The node takes a single input and makes it possible to use that video feed outside the video mixer. Output nodes can be used both to output the program and preview feeds of a video mixer, but also to mark auxiliary outputs, as in the example above, where chroma_key_preview is output to be included in the graph to be able to view the result of the chroma keying, without the effect being keyed on to the program output.

Processing nodes

The processing nodes take their input from another node’s output and outputs a result that is sent to another node’s input. They are therefore placed in the middle of the graph, after nodes from the input group and before output nodes.

Alpha over node (alpha_over)
Input sockets: 2 (Index 0 for overlay video and index 1 for background video)
Output sockets: 1
The alpha over node composites the overlay video input on top of the background video input. The alpha of the overlay video input is taken into consideration. During runtime, this node can be controlled to show or not to show the overlay, and to fade the overlay in or out. This node is useful to composite things such as graphics or chroma keyed video onto a background video.

Chroma key node (chroma_key)
Input sockets: 1
Output sockets: 1
The chroma key node takes an input video stream and performs chroma keying on it based on parameters set during runtime. The video output will have the alpha channel (and in some cases also the color channels) altered. The result of this node can then be composited on top of a background using an Alpha over node.

Fade to black node (fade_to_black)
Input sockets: 1
Output sockets: 1
The fade to black node takes a single input video stream and can fade that video stream to and from black. This node is normally used as the last node before the main program output node, to be able to fade to and from black at the beginning and end of the broadcast.

Transform node (transform)
Input sockets: 1
Output sockets: 1
The transform node takes an input video stream and transform the result inside the visible canvas. This node can be configured during runtime to scale and move the input video. This node is useful for picture-in-picture effects, or to move a chroma key node output to the lower corner of the frame.

Video delay node (video_delay)
Input sockets: 1
Output sockets: 1
The video delay node is used to delay the video by a given number of frames. The number of frames to delay is controlled during runtime. This node is useful whenever the need for dynamically delay a video stream arises, for example in case an external audio mixer is used, which comes with a delay of some frames.

Video links block

The links array in the video block is a list of links between video nodes. The video frames are fed in one direction from node to node via these links. An input socket on a node can only have one connected link. The output sockets on a node can have multiple connected links.

Each block contains the following keys:

from_node - The name of the node in the nodes object, from which the link is receiving frames from
from_socket - The index of the output socket in the node from which this link originates
to_node - The name of the node in the nodes object, to which the link is sending frames to
to_socket - The index of the input socket in the node to which this link connects

Some examples

The simplest video mixer node graph imaginable would be a select node feeding an output node. This mixer would only be able to select one of the inputs and output it unaltered, like a video router would do:

Simplest possible video mixer node graph

The JSON file section for this is:

"video": {
  "nodes": {
    "input_select": {
      "type": "select"
    },
    "program": {
      "type": "output"
    }
  },
  "links": [
    {
      "from_node": "input_select",
      "from_socket": 0,
      "to_node": "program",
      "to_socket": 0
    }
  ]
}

A slightly more advanced node graph would be to use a transition node and two outputs, one for the program out and one for the preview:

Simple video mixer node graph

The JSON file section for this is:

"video": {
  "nodes": {
    "transition": {
      "type": "transition"
    },
    "program": {
      "type": "output"
    },
    "preview": {
      "type": "output"
    }
  },
  "links": [
      {
        "from_node": "transition",
        "from_socket": 0,
        "to_node": "program",
        "to_socket": 0
      },
      {
        "from_node": "transition",
        "from_socket": 1,
        "to_node": "preview",
        "to_socket": 0
      },
  ]
}

Audio outputs

The audio block of the configuration file defines the properties of the audio mixer. The JSON object contains a list called outputs which lists the outputs of the audio mixer and the configuration of each output. Each output has these parameters:

name - The unique name of this audio output, used to refer to if from the output_mapping block
channels - The number of audio channels of this output
follows - (Optional parameter) Used to identify the audio output this output is a post fader aux output for. If the output does not have this parameter set, it is considered a main output

The follows parameter is used to set the output in “post fader aux send” mode. This is used to create extra aux outputs from the audio mixer which are used for mix minus, i.e. where you want the program output, but with some specific audio source(s) removed. When follows is set, the volume of that output will follow the volume of the main bus and scale that volume. If the volume fader of the aux bus is up, it will send the same volume of audio of that strip as the main bus does. So when the main bus volume is turned down, the same thing will happen automatically in the aux bus. If an aux bus’ fader is down on the other hand, that strip will not contribute to the aux bus at all. The aux bus volume faders can therefore be used to remove audio (or scale the volume up or down), but cannot be used to add more audio strips compared to the main bus it is following.

The input routing and configuration of the strips is made via the control command API.

Combine outputs

The output_mapping block is used to define outputs of the entire Rendering Engine, by combining outputs from the video and audio mixers and configuring where those should be sent. The output mapping is an array of output mappings. Each mapping has the following parameters:

name - The unique name of the output mapping. This will be displayed in the REST API both for sources being streamed and sources with feedback streams that can be included in the multi-view
video_output - The name of the video mixer node of type output to get the video stream from. Leave empty, or omit the key to create an audio-only output
audio_output - The name of the audio output to get the audio stream from. Leave empty, or omit the key to create a video-only output
feedback_input_slot - The input slot to use to feed this output back to the multi-view. The REST API may then refer to this input slot to include this output in a multi-view view. Value must be >= 100 as input slots up to 99 are reserved for “regular” sources. Use 0 to disable feedback of this stream.
stream - Boolean value to tell if the output should be streamable and visible as an output in the REST API. If set to false the output will not turn up as an Pipeline Output in the REST API.

The following is a graphical visualisation of the output mappings in the JSON example configuration file above:

Rendering engine output mappings

1.3 - Agile Live Rendering Engine command documentation

Reference for the Agile Live Rendering Engine commands

This page describes the commands for controlling the video mixer, audio router, audio mixer, HTML renderers and media players in the Agile Live Rendering Engine. This topic is closely related to this page on how to configure the rendering engine at startup.

Command protocol

All commands to the Agile Live Rendering Engine are 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.

Each subsystem of the rendering engine has their own set of commands, prefixed by the subsystem name. As can be seen in the image below, the prefixes of the different subsystems are:

html for the html renderer instances
media for the media playback instances
video for the video mixer
audio map for the audio router
audio for the audio mixer (if using the built-in mixer)

The rendering engine and its components, with command prefixes displayed for each subsystem

Video mixer commands

Background

The video mixer is built as a tree graph of processing nodes, please see this page for further information on the video mixer node graph. The names of the nodes defined in the node graph are used as the first word in the control commands as the way to address the specific node. On this page we will specify the detailed protocol for each node type.

There are eight different node types.

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 Select node simply forwards one of the available sources to its output.
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. This is known as “key & fill” in broadcasting.
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 Transform node takes one input stream and transforms it (scaling and translating) to one output stream.
The Chroma Key node takes one input stream, and by setting appropriate parameters for the keying, it will remove areas with the key color from the incoming video stream both affecting the alpha and color channels
The Fade to black node takes one input stream, which it can fade to or from black gradually, and then outputs that stream.
The Output node has one input stream and will output that stream out from the video mixer, back to the Rendering Engine. It has no control commands

To reset the runtime configuration of all video nodes to their default state, the following command is used:

video reset - Reset the runtime configuration of all video mixer nodes

Transition

The transition type of node can be controlled with the following commands:

video <node_name> cut <input_slot> - Cut (hot punch) the program output to the given input slot. This won’t affect the preview output.
video <node_name> preview <input_slot> - Preview the given input slot. This won’t affect the program output.
video <node_name> cut - Cut between the current program and preview outputs, effectively swapping their place.
video <node_name> panic <input_slot> - Cut (hot punch) both the preview and program output to the given input slot instantly for all rendering engines that are receiving this command, disregarding any timing differences!

Some transition commands last over a duration of time, for example wipes. These can be performed either automatically or manually. The automatic mode works by the operator first selecting the type of transition, for instance a fade, setting the preview to the input slot to fade to and then trigger the transition at the right time with a set duration for the transition. In manual mode the exact “position” of the transition is set by the control panel. This is used for implementing T-bars, where the T-bar repeatedly sends the current position of the bar. In the manual mode, the transition type is set before the transition begins, just as in the automatic mode. Note that an automatic transition will be overridden in case the transition “position” is manually set, by interrupting the automatic transition and jumping to the manually set position.

video <node_name> type <type> - Set the transition type to use for transitions hereafter. Valid modes are:
- fade - Fade (mix) from one source to the next
- wipe_left - Wipe from one source to the next, wipe going from right side of the screen to the left
- wipe_right - Wipe from one source to the next, wipe going from left side of the screen to the right
video <node_name> auto <duration_ms> - Perform an automatic transition from the current program output to the current preview output, lasting for <duration_ms> milliseconds. The currently set transition type is used.
video <node_name> factor <factor> - Manually set the position/factor of the transition. <factor> should be between 0.0 and 1.0, where 0.0 is the value before the transition starts and 1.0 is the end of the transition. Note that setting this value to 1.0 will effectively swap place of program and preview output, resetting the transition factor to 0.0 internally. Control panels using this command must take this into consideration to not cause a sudden jump in the transition once the physical control is moved again. Sending this command will interrupt any ongoing automatic transition.

Select

The select type of node only has one control command:

video <node_name> cut <input_slot> - Choose which input slot to forward. Changing looks like a cut.

Alpha Combine

The alpha combine node type can be controlled with these commands:

video <node_name> color <input_slot> - Set which input slot to copy the color data from in the Alpha combine node
video <node_name> alpha <input_slot> - Set which input slot to use to create the alpha channel of the output frame in the Alpha combine node
video <node_name> 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

The alpha over node type can be controlled with these commands:

video <node_name> 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.
video <node_name> fade to <duration_ms> - Start an automatic fade from the current factor to a fully visible overlay over the duration of <duration_ms> milliseconds.
video <node_name> fade from <duration_ms> - Start an automatic fade from the current factor to a fully invisible overlay over the duration of <duration_ms> milliseconds.

Transform

The transform node type can be controlled with these commands:

video <node_name> scale <factor> - Set the scale of the output size, relative the original size. Parameter factor must be > 0. Default is 1.0.
video <node_name> x <position> - Set the X offset of the top left corner of the output, relative the top left corner of the frame. Position is measured in percent of frame width, where 0.0 is the left side of the frame and 1.0 is the right side of the frame. Values outside of the range 0, 1 are valid. Default is 0.0.
video <node_name> y <position> - Set the Y offset of the top left corner of the output, relative the top left corner of the frame. Position is measured in percent of frame height, where 0.0 is the top of the frame and 1.0 is the bottom of the frame. Values outside of the range 0, 1 are valid. Default is 0.0.

Chroma Key

The chroma key node type can be controlled with these commands:

video <node_name> r <value> - Set the red component of the chroma key color. Should be a float between 0.0 and 1.0.
video <node_name> g <value> - Set the green component of the chroma key color. Should be a float between 0.0 and 1.0.
video <node_name> b <value> - Set the blue component of the chroma key color. Should be a float between 0.0 and 1.0.
video <node_name> distance <value> - Set the distance parameter, ranging from 0.0 to 1.0, telling how far from the key color is also considered a part of the key. Larger values will result in more colors being included, 0.0 means only the exact key color is considered.
video <node_name> falloff <value> - Set the falloff parameter, ranging from 0.0 to 1.0, which makes edges smoother. A lower value means harder edges between the key color and the parts to keep, a higher value means a more smooth falloff between removed and kept parts.
video <node_name> spill <value> - Set the color spill reduction parameter, ranging from 0.0 to 1.0, which will desaturate the key color in the parts of the image that are left. Useful for hiding green rims around objects in from of a green screen etc. 0.0 means off and a higher value means more colors further away from the chroma key color will be desaturated.
video <node_name> color_picker <x_factor> <y_factor> <square_size> - Set the chroma key by sampling the pixels covered by the square area of size square_size x square_size. The position x,y is set by <x_factor> * width of video and <y_factor> * height of video. <x_factor> & <y_factor> should be a float between 0.0 and 1.0. The <square_size> should be an integer > 0.0.
video <node_name> alpha_as_video <value> - Instead of writing an alpha mask, set the alpha value as the RGB value, creating a grayscale image of the mask. Value should be true or false.
video <node_name> show_key_color <value> - Draw a 100x100 box in upper left corner with the current chroma key (RGB) value. Value should be true or false.
video <node_name> show_color_picker <value> - Draw a pink border around the area where the color picker will sample a new chroma key. Value should be true or false.

Note

For the true/false parameters above, also TRUE, True, t, T and 1 will be treated as true, any other values will be treated as false.

Fade to black

The fade to black node can be controlled via the following commands:

video <node_name> 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.
video <node_name> fade to <duration_ms> - Start an automatic fade to a fully black output over the duration of <duration_ms> milliseconds.
video <node_name> fade from <duration_ms> - Start an automatic fade to a fully visible (non-black) output over the duration of <duration_ms> milliseconds.

Audio Router commands

The audio router is used to route specific audio channels from an input slot of the Rendering Engine to an input channel strip on the audio mixer. By default, it has no audio routes set up. The router can be controlled with the following commands:

audio map <input_slot> <channel> mono <input_strip> - Map the <channel> from input slot <input_slot> as a mono channel into input strip <input_strip> of the audio mixer
audio map <input_slot> <left_channel> stereo <input_strip> - Map the <left_channel> and <left_channel> + 1 from input slot <input_slot> as a stereo pair into input strip <input_strip> of the audio mixer
audio map reset <input_strip> - Remove the current mapping from <input_strip> of the audio mixer.

To reset both the audio mixer and the audio router to their default state, including removal of all configured input strips, the following command can be used:

audio reset - Reset both the audio mixer and audio router

Audio mixer commands

The audio mixer and audio router have the following data path:

Audio mixer block diagram

In the example picture above, three sources are connected to the input slots and four mono or stereo audio streams are picked as input to the audio mixer. 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. The internal audio mixer can be controlled using the following commands:

Pre-gain

To control the pre-gain of each input strip use:

audio gain <input_strip> <level_dB> - Set the pre-gain level of a specific input in dB. Parameter <level> should be a floating point number. Default is 0.0.

Low-pass filter

To control the low-pass filter of each input strip use:

audio lpf <input_strip> freq <value> - Set the cutoff frequency for the low-pass filter in an input strip. <value> is the frequency in Hz as a floating point number. The frequency range is 20 Hz to 20 kHz. Setting a value of 20 kHz or higher will bypass the filter.
audio lpf <input_strip> q <value> - Set the q-value for the low-pass filter in an input strip. The q-value controls the steepness of cutoff curve with a higher value being a steeper slope. The value is a floating point number ranging from 0.4 to 6.0. The default value is 0.7.

High-pass filter

To control the high-pass filter of each input strip use:

audio hpf <input_strip> freq <value> - Set the cutoff frequency for the high-pass filter in an input strip. <value> is the frequency in Hz as a floating point number. The frequency range is 20 Hz to 20 kHz. Setting a value of 20 Hz or lower will bypass the filter.
audio hpf <input_strip> q <value> - Set the q-value for the high-pass filter in an input strip. The q-value controls the steepness of cutoff curve with a higher value being a steeper slope. The value is a floating point number ranging from 0.4 to 6.0. The default value is 0.7.

Parametric equalizer

The parametric equalizer has ten bands, indexed from 0 to 9. By default, all bands are disabled (type “none”) with a gain of 0 dB, a Q value of 0.707, and a frequency of 1 kHz. To control the parametric equalizer of each input strip use:

audio eq <input_strip> <band> freq <value> - Set the frequency of a specific band in the parametric equalizer. Here <band> is the zero-based index of the band. <value> is a floating point number with the frequency in Hz. For peak, notch, and band-pass filters this is the center frequency. For low-pass, high-pass, low-shelf, and high-shelf filters this is the corner frequency.
audio eq <input_strip> <band> gain <value> - Set the gain of a specific band in the parametric equalizer. Here <band> is the zero-based index of the band. <value> is a floating point number with the gain in dB. The gain parameter only has effect on peaking and shelving filters.
audio eq <input_strip> <band> q <value> - Set the q-value of a specific band in the parametric equalizer to shape the falloff of the band. Here <band> is the zero-based index of the band. <value> is a floating point number with the q-value where a higher value means a more pointy curve. The default value is 0.707.
audio eq <input_strip> <band> type <type> - Set the filter type to use for a specific band in the parametric equalizer. Here <band> is the zero-based index of the band. The available values for <type> are:
- none: Bypass audio without any changes
- lowpass: Low-pass filter at the current frequency. Gain has no effect.
- highpass: High-pass filter at the current frequency. Gain has no effect.
- bandpass: Band-pass filter at the current frequency. Gain has no effect.
- lowshelf: Low-shelf filter. Audio frequencies below the currently set value are modified by the current gain value.
- highshelf: High-shelf filter. Audio frequencies above the currently set value are modified by the current gain value.
- peak: Peak filter. Frequencies around the currently set value are modified by the current gain value.
- notch: Notch filter. Frequencies around the currently set value are reduced greatly. Gain has no effect.

Panning

To control the panning of each input strip use:

audio pan <input_strip> <factor> - Pan the mono or stereo input of an input strip to the left or right. The range of <factor> is between -1.0 and +1.0, where 0.0 means center (no panning), negative values means more to the left and positive value more to the right. Values outside this range will be clamped. A value of +/- 1.0 means that there will only be audio in the left/right channel.

Dynamic range compressor

To control the dynamic range compressor of each input strip use:

audio comp <input_strip> threshold <value> - Set the threshold for activation of the compressor. The threshold is a negative dB value ranging from -30 dB to 0 dB. The volume of audio which is above the threshold value will be reduced (compressed). The default value is 0 dB, i.e. only compression if the audio signal is overloaded.
audio comp <input_strip> ratio <value> - Set the compression ratio for audio exceeding the loudness threshold. The value is the numerator in the compression ratio <value>:1. For instance, if the value is set to 4, the compression ratio is 4:1 and volume overshoot above the threshold will be scaled down to 25 %. The ratio numerator is a floating point number in the range from 1.0 to 24.0, with 4.0 as the default value.
audio comp <input_strip> knee <value> - Set the width of the soft knee in decibels. Instead of simply turning the compression completely on or off at the threshold, the knee defines a volume range in which the compression ratio follows a curve, the “knee”. The knee is a floating point number between 0 dB and 30 dB, with a default value of 2.5 dB.
audio comp <input_strip> attack <value> - Set the attack time of the compressor in milliseconds. The attack time determines how long it takes to reach the full compression after the threshold has been exceeded. The value is a floating point number in the range from 0.1 ms to 120 ms. The default value is 50 ms.
audio comp <input_strip> release <value> - Set the release time of the compressor in milliseconds. The release time determines how long it takes to return to zero compression when the volume is below the compression threshold. The value is a floating point number in the range from 10 ms to 1000 ms. The default value is 200 ms.
audio comp <input_strip> gain <value> - Set the make-up gain i decibels. Since the compression filter lowers the volume of louder audio sections it can be desirable to increase the gain after the filtering. The gain value increases the audio volume with the specified number of decibels. The value is a floating point number in the range from 0 dB to 24 dB. The default value is 0 dB.

Volume and master volume

To control the volume faders and master volume faders use:

audio volume <input_strip> <output> <level> - Set the volume level of a specific input in proportion to its original strength for a given output. Parameter <level> should be a floating point number, where 0.0 means that the input slot is not mixed into the output at all 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.
audio mastervolume <output> <level> - Set the master volume level of an 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. Default is 1.0.
audio volume <input_strip> <output> auto <level> <time_ms> - Do automatic transition of volume from the current volume to the requested level over time_ms milliseconds. The volume will be linearly faded over time in the dB scale.
audio mastervolume <output> auto <level> <time_ms> - Do automatic transition of the master volume from the current volume to the requested level over time_ms milliseconds. The volume will be linearly faded over time in the dB scale.
audio volume <input_strip> <output> mute <value> - Mute or unmute a specific input strip for a specific output bus. This operation will not change any gain or volume fader of the strip. I.e. unmuting will restore the same audio level as before mute was sent. Value should be a boolean, true or false. Use true to mute and false to unmute.
audio mastervolume <output> mute <value> - Mute or unmute all audio in a specific output bus. This operation will not change any gain or volume fader of any strip. I.e. unmuting will restore the same audio levels as before mute was sent. Value should be a boolean, true or false. Use true to mute and false to unmute.

Reset all audio filters

To reset both the audio mixer and the audio router to their default state, including removal of all configured input strips, the following command can be used:

audio reset - Reset both the audio mixer and audio router

HTML rendering

The Rendering Engine also features a built-in HTML renderer which uses the Chromium web browser engine to render HTML pages. The following commands can be used to create and control the HTML browser instances:

html create <input_slot> <width> <height> - Create a new HTML browser instance with the canvas size of width x height pixels and output the rendered frames to the given input slot
html close <input_slot> - Close the HTML browser instance on the given input slot
html load <input_slot> <url> - Load a new URL in the HTML browser on the given input slot
html execute <input_slot> <java script> - Execute JavaScript in the HTML browser on the given input slot. The JavaScript snippet might span over multiple lines and may contain spaces.
html reset - Close all open HTML browsers

Media player

The Rendering Engine can create media player instances to play video and audio files from the hard drive of the machine running the Rendering Engine. It is up to the user of the API to ensure the files are uploaded to the machines running the Rendering Engine(s) before trying to run them. The media players use the FFmpeg library to demux and decode the media files, so most files supported by FFmpeg should work. The media players each have three state parameters: start, duration and looping, to mark a section of the video to loop, or a last frame to stop at in case looping is set to false. The following commands can be used to create and control the media player instances:

media create <input_slot> <filename> - Create a new media player instance with the given media file and output the rendered frames to the given input slot.
media load <input_slot> <filename> - Load another file into an existing media player on the given input slot. This will reset the start, duration and looping parameters of that media player.
media close <input_slot> - Close the media player instance on the given input slot
media play <input_slot> - Start/resume playing the currently loaded media file in the media player on the given input slot
media pause <input_slot> - Pause the media player on the given input slot
media seek <input_slot> <time_ms> - Seek the media player on the given input slot to a time point time_ms milliseconds from the start of the media file and pause the playback at the first frame. Use media play <input_slot> to resume the playback
media set_start <input_slot> <start_time_ms> - Set the start time of the looping section of the media player on the given input slot to a time point start_time_ms milliseconds from the start of the media file. It will still be possible to seek before this time point and play the video from there.
media set_duration <input_slot> <duration_ms> - Set the duration of the playing/looping section of the media player on the given input slot to duration_ms milliseconds from the start_time_ms of the media file. The duration will be clamped in case it spans past the end of the media file. A running media player will either stop at this point, or loop the video depending on the state of the looping parameter
media set_looping <input_slot> <true/false> - Set if the media should loop from the start time when the media player on the given input slot hits either the end of the looping section defined by the start time and duration, or the end of the media file. If set to false, the media player will stop at the end of the section or at the end of the file instead of looping it from the start point.
media reset - Close all open media players

1.4 - C++ SDK

Agile Content Live C++ SDK reference

Agile Content Live C++ SDK reference.

1.4.1 - Classes

Classes

namespace ACL
namespace AclLog
A namespace for logging utilities.
- class CommandLogFormatter
  This class is used to format log entries for Rendering Engine commands.
- class FileLocationFormatterFlag
  A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.
- class ThreadNameFormatterFlag
struct AlignedAudioFrame
AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.
struct AlignedFrame
A frame of aligned data that is passed to the rendering engine from the MediaReceiver. A DataFrame contains a time stamped frame of media, which might be video, audio and auxiliary data such as subtitles. A single DataFrame can contain one or multiple types of media. Which media types are included can be probed by nullptr-checking/size checking the data members. The struct has ownership of all data pointers included. The struct includes all logic for freeing the resources held by this struct and the user should therefore just make sure the struct itself is deallocated to ensure all resources are freed.
namespace ControlDataCommon
- struct ConnectionStatus
  Connection status struct containing information about a connection event.
- struct Response
  A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
- struct StatusMessage
  A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.
class ControlDataSender
A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.
- struct Settings
  Settings for a ControlDataSender.
class DeviceMemory
RAII class for a CUDA memory buffer.
class IControlDataReceiver
IControlDataReceiver is the interface class for the control data receiver. An IControlDataReceiver can receive messages from a sender or other IControlDataReceivers using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a receiving or listening side, as well as a sending side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests.
- struct IncomingRequest
  An incoming request to this ControlDataReceiver.
- struct ReceiverResponse
  A response message to a request.
- struct Settings
  Settings for a ControlDataReceiver.
class IMediaStreamer
IMediaStreamer is an interface class for MediaStreamers, that can take a single stream of uncompressed video and/or audio frames and encode and output it in some way. This output can either be a stream to a network or writing down the data to a file on the hard drive. This class is configured from two interfaces. The input configuration (input video resolution, frame rate, pixel format, number of audio channels…) is made through this C++ API. The output stream is then started from the System Controller. Any of these configurations can be made first. The actual stream to output will start once the first call to.
- struct Configuration
  The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.
- struct Settings
  Settings used when creating a new MediaStreamer.
class ISystemControllerInterface
An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server.
- struct Callbacks
  A struct containing the callbacks that needs to be registered by the component using this interface.
- struct Response
  A response to a request, consists of a status code and an (optional) parameters JSON object.
class IngestApplication
- struct Settings
namespace IngestUtils
class MediaReceiver
A MediaReceiver contains the logic for receiving, decoding and aligning incoming media sources from the Ingests. The aligned data is then delivered to the Rendering Engine which is also responsible for setting up the MediaReceiver. The MediaReceiver has a builtin multi view generator, which can create output streams containing composited subsets of the incoming video sources. This class is controlled using an ISystemControllerInterface provided when starting it.
- struct NewStreamParameters
  A struct containing information on the format of an incoming stream.
- struct Settings
  Settings for a MediaReceiver.
class SystemControllerConnection
An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.
- struct Settings
  Settings for a SystemControllerConnection.
namespace TimeCommon
- struct TAIStatus
- struct TimeStructure
namespace UUIDUtils
A namespace for UUID utility functions.
namespace spdlog

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.1 - AclLog::CommandLogFormatter

AclLog::CommandLogFormatter

This class is used to format log entries for Rendering Engine commands.

#include <AclLog.h>

Inherits from spdlog::formatter

Public Functions

	Name
	CommandLogFormatter()
void	format(const spdlog::details::log_msg & msg, spdlog::memory_buf_t & dest) override
std::unique_ptr< spdlog::formatter >	clone() const override

Public Functions Documentation

function CommandLogFormatter

CommandLogFormatter()

function format

void format(
    const spdlog::details::log_msg & msg,
    spdlog::memory_buf_t & dest
) override

function clone

std::unique_ptr< spdlog::formatter > clone() const override

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.2 - AclLog::FileLocationFormatterFlag

AclLog::FileLocationFormatterFlag

A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

#include <AclLog.h>

Inherits from spdlog::custom_flag_formatter

Public Functions

	Name
void	format(const spdlog::details::log_msg & msg, const std::tm & , spdlog::memory_buf_t & dest) override
std::unique_ptr< custom_flag_formatter >	clone() const override

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & msg,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.3 - AclLog::ThreadNameFormatterFlag

AclLog::ThreadNameFormatterFlag

Inherits from spdlog::custom_flag_formatter

Public Functions

	Name
void	format(const spdlog::details::log_msg & , const std::tm & , spdlog::memory_buf_t & dest) override
std::unique_ptr< custom_flag_formatter >	clone() const override

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & ,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.4 - AlignedAudioFrame

AlignedAudioFrame

AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.

#include <AlignedFrame.h>

Public Attributes

	Name
std::vector< float >	mSamples
uint8_t	mNumberOfChannels
uint32_t	mNumberOfSamplesPerChannel

Public Attributes Documentation

variable mSamples

std::vector< float > mSamples;

variable mNumberOfChannels

uint8_t mNumberOfChannels = 0;

variable mNumberOfSamplesPerChannel

uint32_t mNumberOfSamplesPerChannel = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.5 - AlignedFrame

AlignedFrame

A frame of aligned data that is passed to the rendering engine from the MediaReceiver. A DataFrame contains a time stamped frame of media, which might be video, audio and auxiliary data such as subtitles. A single DataFrame can contain one or multiple types of media. Which media types are included can be probed by nullptr-checking/size checking the data members. The struct has ownership of all data pointers included. The struct includes all logic for freeing the resources held by this struct and the user should therefore just make sure the struct itself is deallocated to ensure all resources are freed.

#include <AlignedFrame.h>

Public Functions

	Name
	AlignedFrame() =default
	~AlignedFrame() =default
	AlignedFrame(AlignedFrame const & ) =delete
AlignedFrame &	operator=(AlignedFrame const & ) =delete
std::shared_ptr< AlignedFrame >	makeShallowCopy() const Make a shallow copy of this AlignedFrame (video and audio pointers will point to the same video and audio memory buffers as in the frame copied from)

Public Attributes

	Name
int64_t	mCaptureTimestamp
int64_t	mRenderingTimestamp
std::shared_ptr< DeviceMemory >	mVideoFrame
PixelFormat	mPixelFormat
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mWidth
uint32_t	mHeight
AlignedAudioFramePtr	mAudioFrame
uint32_t	mAudioSamplingFrequency

Public Functions Documentation

function AlignedFrame

AlignedFrame() =default

function ~AlignedFrame

~AlignedFrame() =default

function AlignedFrame

AlignedFrame(
    AlignedFrame const & 
) =delete

function operator=

AlignedFrame & operator=(
    AlignedFrame const & 
) =delete

function makeShallowCopy

std::shared_ptr< AlignedFrame > makeShallowCopy() const

Make a shallow copy of this AlignedFrame (video and audio pointers will point to the same video and audio memory buffers as in the frame copied from)

Return: A pointer to a new frame, which is a shallow copy of the old one, pointing to the same video and audio memory buffers

Public Attributes Documentation

variable mCaptureTimestamp

int64_t mCaptureTimestamp = 0;

The TAI timestamp in microseconds since the TAI epoch when this frame was captured by the ingest

variable mRenderingTimestamp

int64_t mRenderingTimestamp = 0;

The TAI timestamp in microseconds since the TAI epoch when this frame should be delivered to the rendering engine

variable mVideoFrame

std::shared_ptr< DeviceMemory > mVideoFrame = nullptr;

variable mPixelFormat

PixelFormat mPixelFormat = PixelFormat::kUnknown;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 0;

variable mWidth

uint32_t mWidth = 0;

variable mHeight

uint32_t mHeight = 0;

variable mAudioFrame

AlignedAudioFramePtr mAudioFrame = nullptr;

variable mAudioSamplingFrequency

uint32_t mAudioSamplingFrequency = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.6 - ControlDataCommon::ConnectionStatus

ControlDataCommon::ConnectionStatus

Connection status struct containing information about a connection event.

#include <ControlDataCommon.h>

Public Functions

	Name
	ConnectionStatus() =default
	ConnectionStatus(ConnectionType mConnectionType, const std::string & mIp, uint16_t mPort)

Public Attributes

	Name
ConnectionType	mConnectionType
std::string	mIP
uint16_t	mPort

Public Functions Documentation

function ConnectionStatus

ConnectionStatus() =default

function ConnectionStatus

inline ConnectionStatus(
    ConnectionType mConnectionType,
    const std::string & mIp,
    uint16_t mPort
)

Public Attributes Documentation

variable mConnectionType

ConnectionType mConnectionType = ConnectionType::DISCONNECTED;

variable mIP

std::string mIP;

variable mPort

uint16_t mPort = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.7 - ControlDataCommon::Response

ControlDataCommon::Response

A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.

#include <ControlDataCommon.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage
uint64_t	mRequestId The actual message.
std::string	mFromUUID The ID of the request this is a response to.

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

variable mRequestId

uint64_t mRequestId = 0;

The actual message.

variable mFromUUID

std::string mFromUUID;

The ID of the request this is a response to.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.8 - ControlDataCommon::StatusMessage

ControlDataCommon::StatusMessage

A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

#include <ControlDataCommon.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage
std::string	mFromUUID The actual message.

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

variable mFromUUID

std::string mFromUUID;

The actual message.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.9 - ControlDataSender

ControlDataSender

A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.

#include <ControlDataSender.h>

Public Classes

	Name
struct	Settings Settings for a ControlDataSender.

Public Functions

	Name
	ControlDataSender() Default constructor, creates an empty object.
	~ControlDataSender() Destructor. Will disconnect from the connected receivers and close the System controller connection.
bool	configure(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, const Settings & settings) Configure this ControlDataSender and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.
bool	sendRequestToReceivers(const std::vector< uint8_t > & request, uint64_t & requestId) Send a request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.
bool	sendMultiRequestToReceivers(const std::vector< std::vector< uint8_t » & request, uint64_t & requestId) Send a multi-message request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.
	ControlDataSender(ControlDataSender const & ) =delete
ControlDataSender &	operator=(ControlDataSender const & ) =delete
std::string	getVersion() Get application version.

Public Functions Documentation

function ControlDataSender

ControlDataSender()

Default constructor, creates an empty object.

function ~ControlDataSender

~ControlDataSender()

Destructor. Will disconnect from the connected receivers and close the System controller connection.

function configure

bool configure(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
)

Configure this ControlDataSender and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.

Parameters:

controllerInterface The interface to the System controller, used for communicating with this ControlDataSender
settings The Settings to use for this ControlDataSender

Return: True on success, false otherwise

function sendRequestToReceivers

bool sendRequestToReceivers(
    const std::vector< uint8_t > & request,
    uint64_t & requestId
)

Send a request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async responses.

Return: True if the request was successfully sent, false otherwise

function sendMultiRequestToReceivers

bool sendMultiRequestToReceivers(
    const std::vector< std::vector< uint8_t >> & request,
    uint64_t & requestId
)

Send a multi-message request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async responses.

Return: True if the request was successfully sent, false otherwise

function ControlDataSender

ControlDataSender(
    ControlDataSender const & 
) =delete

function operator=

ControlDataSender & operator=(
    ControlDataSender const & 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “6.0.0-39-g60a35937”

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.10 - ControlDataSender::Settings

ControlDataSender::Settings

Settings for a ControlDataSender.

#include <ControlDataSender.h>

Public Attributes

	Name
std::function< void(const ControlDataCommon::ConnectionStatus &)>	mConnectionStatusCallback
std::function< void(const ControlDataCommon::Response &)>	mResponseCallback
std::function< void(const ControlDataCommon::StatusMessage &)>	mStatusMessageCallback

Public Attributes Documentation

variable mConnectionStatusCallback

std::function< void(const ControlDataCommon::ConnectionStatus &)> mConnectionStatusCallback;

variable mResponseCallback

std::function< void(const ControlDataCommon::Response &)> mResponseCallback;

variable mStatusMessageCallback

std::function< void(const ControlDataCommon::StatusMessage &)> mStatusMessageCallback;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.11 - DeviceMemory

DeviceMemory

RAII class for a CUDA memory buffer.

#include <DeviceMemory.h>

Public Functions

	Name
	DeviceMemory() =default Default constructor, creates an empty object, without allocating any memory on the device.
	DeviceMemory(size_t numberOfBytes) Constructor allocating the required number of bytes.
	DeviceMemory(size_t numberOfBytes, cudaStream_t cudaStream) Constructor allocating the required number of bytes by making an async allocation. The allocation will be put in the given CUDA stream.
	DeviceMemory(void * deviceMemory) Constructor taking ownership of an already allocated CUDA memory pointer. This class will free the pointer once it goes out of scope.
bool	allocateMemory(size_t numberOfBytes) Allocates device memory. The memory allocated will automatically be freed by the destructor.
bool	allocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Allocates device memory. The memory allocated will automatically be freed by the destructor.
bool	reallocateMemory(size_t numberOfBytes) Reallocates device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.
bool	reallocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Asynchronously reallocate device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.
bool	allocateAndResetMemory(size_t numberOfBytes) Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.
bool	allocateAndResetMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.
bool	freeMemory() Free the device memory held by this class. Calling this when no memory is allocated is a no-op.
bool	freeMemoryAsync(cudaStream_t cudaStream) Deallocate memory asynchronously, in a given CUDA stream. Calling this when no memory is allocated is a no-op.
void	setFreeingCudaStream(cudaStream_t cudaStream) Set which CUDA stream to use for freeing this DeviceMemory. In case the DeviceMemory already holds a CUDA stream to use for freeing the memory, this will be overwritten.
	~DeviceMemory() Destructor, frees the internal CUDA memory.
template T *	getDevicePointer() const
size_t	getSize() const
	DeviceMemory(DeviceMemory && other)
DeviceMemory &	operator=(DeviceMemory && other)
void	swap(DeviceMemory & other)
	DeviceMemory(DeviceMemory const & ) =delete DeviceMemory is not copyable.
DeviceMemory	operator=(DeviceMemory const & ) =delete

Public Functions Documentation

function DeviceMemory

DeviceMemory() =default

Default constructor, creates an empty object, without allocating any memory on the device.

function DeviceMemory

explicit DeviceMemory(
    size_t numberOfBytes
)

Constructor allocating the required number of bytes.

Parameters:

numberOfBytes Number of bytes to allocate

Exceptions:

std::runtime_error In case the allocation failed

function DeviceMemory

explicit DeviceMemory(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Constructor allocating the required number of bytes by making an async allocation. The allocation will be put in the given CUDA stream.

Parameters:

size Number of bytes to allocate
cudaStream The CUDA stream to put the async allocation in. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Exceptions:

std::runtime_error In case the async allocation failed to be put in queue.

See: freeMemoryAsync method is not explicitly called, the memory will be freed synchronously when this DeviceMemory instance goes out of scope, meaning that the entire GPU is synchronized, which will impact performance negatively.

Note:

The method will return as soon as the allocation is put in queue in the CUDA stream, i.e. before the actual allocation is made. Using this DeviceMemory is only valid as long as it is used in the same CUDA stream, or in case another stream is used, only if that stream is synchronized first with respect to cudaStream.
In case the

function DeviceMemory

explicit DeviceMemory(
    void * deviceMemory
)

Constructor taking ownership of an already allocated CUDA memory pointer. This class will free the pointer once it goes out of scope.

Parameters:

deviceMemory CUDA memory pointer to take ownership over.

function allocateMemory

bool allocateMemory(
    size_t numberOfBytes
)

Allocates device memory. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate

Return: True on success, false if there is already memory allocated by this instance, or if the CUDA malloc failed.

function allocateMemoryAsync

bool allocateMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Allocates device memory. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate
cudaStream The CUDA stream to use for the allocation. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Return: True on success, false if there is already memory allocated by this instance, or if the CUDA malloc failed.

function reallocateMemory

bool reallocateMemory(
    size_t numberOfBytes
)

Reallocates device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.

Parameters:

numberOfBytes Number of bytes to allocate in the new allocation

Return: True on success, false if CUDA free or CUDA malloc failed.

function reallocateMemoryAsync

bool reallocateMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Asynchronously reallocate device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.

Parameters:

numberOfBytes Number of bytes to allocate in the new allocation
cudaStream The CUDA stream to use for the allocation and freeing of memory. A reference to this stream will also be saved internally to be used to asynchronously free them memory when this instance goes out of scope.

Return: True on success, false if CUDA free or CUDA malloc failed.

function allocateAndResetMemory

bool allocateAndResetMemory(
    size_t numberOfBytes
)

Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate

Return: True on success, false if there is already memory allocated by this instance, or if any of the CUDA operations failed.

function allocateAndResetMemoryAsync

bool allocateAndResetMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate
cudaStream The CUDA stream to use for the allocation and resetting. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Return: True on success, false if there is already memory allocated by this instance, or if any of the CUDA operations failed.

function freeMemory

bool freeMemory()

Free the device memory held by this class. Calling this when no memory is allocated is a no-op.

See: freeMemoryAsync instead.

Return: True in case the memory was successfully freed (or not allocated to begin with), false otherwise.

Note: This method will free the memory in an synchronous fashion, synchronizing the entire CUDA context and ignoring the internally saved CUDA stream reference in case one exist. For async freeing of the memory, use

function freeMemoryAsync

bool freeMemoryAsync(
    cudaStream_t cudaStream
)

Deallocate memory asynchronously, in a given CUDA stream. Calling this when no memory is allocated is a no-op.

Parameters:

cudaStream The CUDA stream to free the memory asynchronously in

Return: True in case the memory deallocation request was successfully put in queue in the CUDA stream.

Note:

The method will return as soon as the deallocation is put in queue in the CUDA stream, i.e. before the actual deallocation is made.
It is the programmer’s responsibility to ensure this DeviceMemory is not used in another CUDA stream before this method is called. In case it is used in another CUDA stream, sufficient synchronization must be made before calling this method (and a very good reason given for not freeing the memory in that CUDA stream instead)

function setFreeingCudaStream

void setFreeingCudaStream(
    cudaStream_t cudaStream
)

Set which CUDA stream to use for freeing this DeviceMemory. In case the DeviceMemory already holds a CUDA stream to use for freeing the memory, this will be overwritten.

Parameters:

cudaStream The new CUDA stream to use for freeing the memory when the destructor is called.

Note: It is the programmer’s responsibility to ensure this DeviceMemory is not used in another CUDA stream before this instance is destructed. In case it is used in another CUDA stream, sufficient synchronization must be made before setting this as the new CUDA stream to use when freeing the memory.

function ~DeviceMemory

~DeviceMemory()

Destructor, frees the internal CUDA memory.

function getDevicePointer

template <typename T  =uint8_t>
inline T * getDevicePointer() const

Template Parameters:

T The pointer type to return

Return: the CUDA memory pointer handled by this class. Nullptr in case no memory is allocated.

function getSize

size_t getSize() const

Return: The size of the CUDA memory allocation held by this class.

function DeviceMemory

DeviceMemory(
    DeviceMemory && other
)

function operator=

DeviceMemory & operator=(
    DeviceMemory && other
)

function swap

void swap(
    DeviceMemory & other
)

function DeviceMemory

DeviceMemory(
    DeviceMemory const & 
) =delete

DeviceMemory is not copyable.

function operator=

DeviceMemory operator=(
    DeviceMemory const & 
) =delete

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.12 - IControlDataReceiver

IControlDataReceiver

IControlDataReceiver is the interface class for the control data receiver. An IControlDataReceiver can receive messages from a sender or other IControlDataReceivers using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a receiving or listening side, as well as a sending side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests. More…

#include <IControlDataReceiver.h>

Public Classes

	Name
struct	IncomingRequest An incoming request to this ControlDataReceiver.
struct	ReceiverResponse A response message to a request.
struct	Settings Settings for a ControlDataReceiver.

Public Functions

	Name
virtual	~IControlDataReceiver() =default Destructor.
virtual bool	configure(const Settings & settings) =0 Configure this instance.
virtual bool	sendStatusMessageToSender(const std::vector< uint8_t > & message) =0 Send a status message to the (directly or indirectly) connected ControlDataSender. In case this ControlDataReceiver has another ControlDataReceiver as sender, that receiver will forward the status message to the sender.
virtual bool	sendRequestToReceivers(const std::vector< uint8_t > & request, uint64_t & requestId) =0 Send a request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.
virtual bool	sendMultiRequestToReceivers(const std::vector< std::vector< uint8_t » & request, uint64_t & requestId) =0 Send a multi-message request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.

Detailed Description

class IControlDataReceiver;

Each ControlDataReceiver can be configured to have a certain message delay. This delay parameter is set when the System controller instructs the ControlDataReceiver to start listening for incoming connections from senders (or sending ControlDataReceiver). Each incoming request will then be delayed and delivered according to the parameter, compared to the send timestamp in the message. In case multiple receivers are chained, like sender->receiver1->receiver2, receiver1 will delay the incoming messages from the sender based on when they were sent from the sender. Furthermore, receiver2 will delay them compared to when they were sent from receiver1.

An IControlDataReceiver can send status messages back to the sender. In case of chained receivers, the message will be forwarded back to the sender. A user of the ControlDataReceiver can register callbacks to receive requests and status messages. There is also an optional “preview” callback that is useful in case the incoming messages are delayed (have a delay > 0). This callback will then be called as soon as the request message arrives, to allow the user to prepare for when the actual delayed request callback is called.

Public Functions Documentation

function ~IControlDataReceiver

virtual ~IControlDataReceiver() =default

Destructor.

function configure

virtual bool configure(
    const Settings & settings
) =0

Configure this instance.

Parameters:

settings The settings to use for this receiver

Return: True on success, false otherwise

function sendStatusMessageToSender

virtual bool sendStatusMessageToSender(
    const std::vector< uint8_t > & message
) =0

Send a status message to the (directly or indirectly) connected ControlDataSender. In case this ControlDataReceiver has another ControlDataReceiver as sender, that receiver will forward the status message to the sender.

Parameters:

message The status message

Return: True in case the message was sent successfully, false otherwise.

function sendRequestToReceivers

virtual bool sendRequestToReceivers(
    const std::vector< uint8_t > & request,
    uint64_t & requestId
) =0

Send a request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async response.

Return: True if the request was successfully sent, false otherwise

function sendMultiRequestToReceivers

virtual bool sendMultiRequestToReceivers(
    const std::vector< std::vector< uint8_t >> & request,
    uint64_t & requestId
) =0

Send a multi-message request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async response.

Return: True if the request was successfully sent, false otherwise

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.13 - IControlDataReceiver::IncomingRequest

IControlDataReceiver::IncomingRequest

An incoming request to this ControlDataReceiver.

#include <IControlDataReceiver.h>

Public Attributes

	Name
std::vector< std::vector< uint8_t > >	mMessages
std::string	mSenderUUID The actual messages.
std::string	mRequesterUUID UUID of the sender/forwarder that sent the request to this ControlDataReceiver.
uint64_t	mRequestID UUID of the requester (the original sender, creating the request)
int64_t	mSenderTimestampUs The requester’s unique id of this request.
int64_t	mDeliveryTimestampUs The TAI timestamp when this message was sent from the sender/forwarder in micro sec since TAI epoch.

Public Attributes Documentation

variable mMessages

std::vector< std::vector< uint8_t > > mMessages;

variable mSenderUUID

std::string mSenderUUID;

The actual messages.

variable mRequesterUUID

std::string mRequesterUUID;

UUID of the sender/forwarder that sent the request to this ControlDataReceiver.

variable mRequestID

uint64_t mRequestID = 0;

UUID of the requester (the original sender, creating the request)

variable mSenderTimestampUs

int64_t mSenderTimestampUs =
            0;

The requester’s unique id of this request.

variable mDeliveryTimestampUs

int64_t mDeliveryTimestampUs =
            0;

The TAI timestamp when this message was sent from the sender/forwarder in micro sec since TAI epoch.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.14 - IControlDataReceiver::ReceiverResponse

IControlDataReceiver::ReceiverResponse

A response message to a request.

#include <IControlDataReceiver.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.15 - IControlDataReceiver::Settings

IControlDataReceiver::Settings

Settings for a ControlDataReceiver.

#include <IControlDataReceiver.h>

Public Attributes

	Name
std::string	mProductionPipelineUUID
std::function< void(const IncomingRequest &)>	mPreviewIncomingRequestCallback
std::function< ReceiverResponse(const IncomingRequest &)>	mIncomingRequestCallback
std::function< void(const ControlDataCommon::ConnectionStatus &)>	mConnectionStatusCallback
std::function< void(const ControlDataCommon::Response &)>	mResponseCallback Callback for connection events.

Public Attributes Documentation

variable mProductionPipelineUUID

std::string mProductionPipelineUUID;

variable mPreviewIncomingRequestCallback

std::function< void(const IncomingRequest &)> mPreviewIncomingRequestCallback;

UUID of the Production Pipeline component this Receiver is a part of Callback called as soon as this ControlDataReceiver gets the request, as a “preview” of what requests will be delivered.

variable mIncomingRequestCallback

std::function< ReceiverResponse(const IncomingRequest &)> mIncomingRequestCallback;

The actual callback used when this ControlDataReceiver gets a request and wants a response back. This callback will delay and deliver the request according to this receiver’s configured delay.

variable mConnectionStatusCallback

std::function< void(const ControlDataCommon::ConnectionStatus &)> mConnectionStatusCallback;

variable mResponseCallback

std::function< void(const ControlDataCommon::Response &)> mResponseCallback;

Callback for connection events.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.16 - IMediaStreamer

IMediaStreamer

IMediaStreamer is an interface class for MediaStreamers, that can take a single stream of uncompressed video and/or audio frames and encode and output it in some way. This output can either be a stream to a network or writing down the data to a file on the hard drive. This class is configured from two interfaces. The input configuration (input video resolution, frame rate, pixel format, number of audio channels…) is made through this C++ API. The output stream is then started from the System Controller. Any of these configurations can be made first. The actual stream to output will start once the first call to. More…

#include <IMediaStreamer.h>

Public Classes

	Name
struct	Configuration The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.
struct	Settings Settings used when creating a new MediaStreamer.

Public Functions

	Name
virtual	~IMediaStreamer() =default Destructor.
virtual bool	configure(const std::string & uuid, const Settings & settings, CUcontext cudaContext) =0 Configure this MediaStreamer. This must be called before any call to the.
virtual bool	setInputFormatAndStart(const Configuration & configuration) =0 Set the input format of this MediaStreamer and start the streamer. The.
virtual bool	stopAndResetFormat() =0 Stop streaming and reset the format. A call to this method will stop any output streams set up by the ISystemControllerInterface and reset the input format set by the.
virtual bool	hasFormatAndIsRunning() const =0
virtual bool	hasOpenOutputStream() const =0
virtual bool	outputData(const AlignedFramePtr & frame) =0 Output data through this streamer. The AlignedFrame::mRenderingTimestamp of the frame will be used as PTS when encoding the uncompressed frame.

Detailed Description

class IMediaStreamer;

See: outputData is made.

Public Functions Documentation

function ~IMediaStreamer

virtual ~IMediaStreamer() =default

Destructor.

function configure

virtual bool configure(
    const std::string & uuid,
    const Settings & settings,
    CUcontext cudaContext
) =0

Configure this MediaStreamer. This must be called before any call to the.

Parameters:

uuid UUID of this MediaStreamer
settings Settings for this MediaStreamer
cudaContext The CUDA context to use for this MediaStreamer. The frames passed to this instance should be valid in this CUDA context. The streamer will use this context for preprocessing and encoding.

See:

Return: True if the streamer was successfully configured

function setInputFormatAndStart

virtual bool setInputFormatAndStart(
    const Configuration & configuration
) =0

Set the input format of this MediaStreamer and start the streamer. The.

Parameters:

configuration The configuration with the format of the frames that will be sent to this MediaReceiver

See:

configure method must be called before this method is called. This method must be called before any call to
outputData. If the format should be reset, the
stopAndResetFormat method should be called first and then this method can be called again to reset the format.

Return: True if the streamer was successfully started, false otherwise

function stopAndResetFormat

virtual bool stopAndResetFormat() =0

Stop streaming and reset the format. A call to this method will stop any output streams set up by the ISystemControllerInterface and reset the input format set by the.

See: setInputFormatAndStart method. The connection to the ISystemControllerInterface will be kept.

Return: True if the stream was successfully stopped and the format reset, or if the format was not set before this method was called, false on error.

function hasFormatAndIsRunning

virtual bool hasFormatAndIsRunning() const =0

Return: True if the input format is set and the OutputStreamer is running, false otherwise

function hasOpenOutputStream

virtual bool hasOpenOutputStream() const =0

See:

outputData will be discarded without being encoded, as there is no stream to output them to. This method can be used to check if the frame even needs to be produced by the rendering engine. Note however, that the
outputData method will still log the frames sent to it as received, even if they are not encoded when the output stream is closed.

Return: True if the output stream of the MediaStreamer is currently open and outputting the data, false otherwise. In case this returns false all frames passed to

function outputData

virtual bool outputData(
    const AlignedFramePtr & frame
) =0

Output data through this streamer. The AlignedFrame::mRenderingTimestamp of the frame will be used as PTS when encoding the uncompressed frame.

Parameters:

frame The data frame to output, with video data in CUDA memory

See: setInputFormatAndStart method, or if the format has not been set by a call to that method.

Return: True if the frame was accepted (but not necessarily streamed, in case the output stream has not been set up by the ISystemControllerInterface), false in case the frame did not match the configuration made in the

Note: The DeviceMemory in the AlignedFrame passed to this method must not be in use by any CUDA stream. In case the memory has been used in kernels in another CUDA stream, make sure to first synchronize with the stream, before passing it over to the MediaStreamer.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.17 - IMediaStreamer::Configuration

IMediaStreamer::Configuration

The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.

#include <IMediaStreamer.h>

Public Attributes

	Name
PixelFormat	mIncomingPixelFormat
uint32_t	mWidth
uint32_t	mHeight
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mAudioSampleRate
uint32_t	mNumAudioChannels

Public Attributes Documentation

variable mIncomingPixelFormat

PixelFormat mIncomingPixelFormat = PixelFormat::kUnknown;

variable mWidth

uint32_t mWidth = 0;

variable mHeight

uint32_t mHeight = 0;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 0;

variable mAudioSampleRate

uint32_t mAudioSampleRate = 0;

variable mNumAudioChannels

uint32_t mNumAudioChannels = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.18 - IMediaStreamer::Settings

IMediaStreamer::Settings

Settings used when creating a new MediaStreamer.

#include <IMediaStreamer.h>

Public Attributes

	Name
std::string	mName

Public Attributes Documentation

variable mName

std::string mName;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.19 - IngestApplication

IngestApplication

Public Classes

	Name
struct	Settings

Public Functions

	Name
	IngestApplication() Constructor, creates an empty IngestApplication without starting it.
	~IngestApplication() Destructor.
bool	start(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, const Settings & settings) Start this IngestApplication given an interface to the System Controller and an UUID.
bool	stop() Stop this IngestApplication.
std::string	getVersion() Get application version.
std::string	getLibraryVersions() Get the versions of the libraries available at runtime, among others, CUDA version, BMD and NDI versions.

Public Functions Documentation

function IngestApplication

IngestApplication()

Constructor, creates an empty IngestApplication without starting it.

function ~IngestApplication

~IngestApplication()

Destructor.

function start

bool start(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
)

Start this IngestApplication given an interface to the System Controller and an UUID.

Parameters:

controllerInterface The interface for communication with the System Controller
settings The settings for the IngestApplication

Return: True if the IngestApplication was successfully started, false otherwise

function stop

bool stop()

Stop this IngestApplication.

Return: True if the IngestApplication was successfully stopped, false otherwise

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “6.0.0-39-g60a35937”

function getLibraryVersions

static std::string getLibraryVersions()

Get the versions of the libraries available at runtime, among others, CUDA version, BMD and NDI versions.

Return: a string with the currently found versions of the libraries used by this application

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.20 - IngestApplication::Settings

IngestApplication::Settings

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.21 - ISystemControllerInterface

ISystemControllerInterface

#include <ISystemControllerInterface.h>

Inherited by SystemControllerConnection

Public Classes

	Name
struct	Callbacks A struct containing the callbacks that needs to be registered by the component using this interface.
struct	Response A response to a request, consists of a status code and an (optional) parameters JSON object.

Public Types

	Name
enum class uint32_t	StatusCode { SUCCESS = 3001, TOO_MANY_REQUESTS = 3101, UUID_ALREADY_REGISTERED = 3201, FORMAT_ERROR = 3202, ALREADY_CONFIGURED = 3203, OUT_OF_RESOURCES = 3204, NOT_FOUND = 3205, INTERNAL_ERROR = 3206, CONNECTION_FAILED = 3207, TIMEOUT_EXCEEDED = 3208, KEY_MISMATCH = 3209, UNKNOWN_REQUEST = 3210, MALFORMED_REQUEST = 3211, ALREADY_IN_USE = 3212, VERSION_MISMATCH = 3213} Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Name

enum class uint32_t

StatusCode { SUCCESS = 3001, TOO_MANY_REQUESTS = 3101, UUID_ALREADY_REGISTERED = 3201, FORMAT_ERROR = 3202, ALREADY_CONFIGURED = 3203, OUT_OF_RESOURCES = 3204, NOT_FOUND = 3205, INTERNAL_ERROR = 3206, CONNECTION_FAILED = 3207, TIMEOUT_EXCEEDED = 3208, KEY_MISMATCH = 3209, UNKNOWN_REQUEST = 3210, MALFORMED_REQUEST = 3211, ALREADY_IN_USE = 3212, VERSION_MISMATCH = 3213}
Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions

	Name
virtual	~ISystemControllerInterface() =default Virtual destructor.
virtual std::optional< std::string >	sendMessage(const std::string & messageTitle, const nlohmann::json & parameters) =0 Send a message containing a JSON object to the controller.
virtual bool	registerRequestCallback(const Callbacks & callbacks) =0 Register the callbacks to call for events in this class.
virtual bool	connect() =0 Connect to the System controller.
virtual bool	disconnect() =0 Disconnect from the System controller.
virtual bool	isConnected() const =0
virtual std::string	getUUID() const =0

Public Types Documentation

enum StatusCode

Enumerator	Value	Description
SUCCESS	3001	3000-3099 Info/Notifications
TOO_MANY_REQUESTS	3101	3100-3199 Warnings
UUID_ALREADY_REGISTERED	3201	3200-3299 Error
FORMAT_ERROR	3202
ALREADY_CONFIGURED	3203
OUT_OF_RESOURCES	3204
NOT_FOUND	3205
INTERNAL_ERROR	3206
CONNECTION_FAILED	3207
TIMEOUT_EXCEEDED	3208
KEY_MISMATCH	3209
UNKNOWN_REQUEST	3210
MALFORMED_REQUEST	3211
ALREADY_IN_USE	3212
VERSION_MISMATCH	3213

Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions Documentation

function ~ISystemControllerInterface

virtual ~ISystemControllerInterface() =default

Virtual destructor.

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) =0

Send a message containing a JSON object to the controller.

Parameters:

messageTitle The title of the status type or request
parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplemented by: SystemControllerConnection::sendMessage

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) =0

Parameters:

callbacks The callbacks to use when events in this class happen

Return: True on successful registration, false if some callback is not set or if already connected

Reimplemented by: SystemControllerConnection::registerRequestCallback

function connect

virtual bool connect() =0

Connect to the System controller.

Return: True on successful connection, false on error or if already connected

Reimplemented by: SystemControllerConnection::connect

function disconnect

virtual bool disconnect() =0

Disconnect from the System controller.

Return: True on successful disconnection, false on error or if not connected

Reimplemented by: SystemControllerConnection::disconnect

function isConnected

virtual bool isConnected() const =0

Return: True if connected to the System controller, false otherwise

Reimplemented by: SystemControllerConnection::isConnected

function getUUID

virtual std::string getUUID() const =0

Return: The UUID of this interface to the System controller

Reimplemented by: SystemControllerConnection::getUUID

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.22 - ISystemControllerInterface::Callbacks

ISystemControllerInterface::Callbacks

A struct containing the callbacks that needs to be registered by the component using this interface.

#include <ISystemControllerInterface.h>

Public Attributes

	Name
std::function< Response(const std::string &, const nlohmann::json &)>	mRequestCallback
std::function< void(uint32_t, const std::string &, const std::error_code &)>	mConnectionClosedCallback

Public Attributes Documentation

variable mRequestCallback

std::function< Response(const std::string &, const nlohmann::json &)> mRequestCallback;

variable mConnectionClosedCallback

std::function< void(uint32_t, const std::string &, const std::error_code &)> mConnectionClosedCallback;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.23 - ISystemControllerInterface::Response

ISystemControllerInterface::Response

A response to a request, consists of a status code and an (optional) parameters JSON object.

#include <ISystemControllerInterface.h>

Public Attributes

	Name
StatusCode	mCode
nlohmann::json	mParameters

Public Attributes Documentation

variable mCode

StatusCode mCode;

variable mParameters

nlohmann::json mParameters;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.24 - MediaReceiver

MediaReceiver

A MediaReceiver contains the logic for receiving, decoding and aligning incoming media sources from the Ingests. The aligned data is then delivered to the Rendering Engine which is also responsible for setting up the MediaReceiver. The MediaReceiver has a builtin multi view generator, which can create output streams containing composited subsets of the incoming video sources. This class is controlled using an ISystemControllerInterface provided when starting it.

#include <MediaReceiver.h>

Public Classes

	Name
struct	NewStreamParameters A struct containing information on the format of an incoming stream.
struct	Settings Settings for a MediaReceiver.

Public Types

	Name
enum class uint32_t	TallyBorderColor { kNone, kRed, kGreen, kYellow} Available colors for tally border in multi view.

Public Functions

	Name
	MediaReceiver() Default constructor.
	~MediaReceiver() Default destructor.
bool	start(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, CUcontext cudaContext, const Settings & settings, const ControlDataReceiver::Settings & receiverSettings) Start the MediaReceiver. This method will call connect on the System controller interface and set up the callbacks from the interface to call internal methods.
void	stop() Stop the MediaReceiver.
std::function< void(const AlignedFramePtr &)>	getCustomMultiViewSourceInput(uint32_t inputSlot, const std::string & name ="") This method allows the Rendering Engine to provide custom input sources to the Multi-view generator to send video streams that can be added to the multi-views. This could for instance be used for adding a “preview” of the video stream the rendering engine is about to cut to.
bool	removeCustomMultiViewSourceInput(uint32_t inputSlot) Remove a custom multi-view generator source input earlier registered using the `getCustomMultiViewSourceInput` method.
std::shared_ptr< IMediaStreamer >	createMediaStreamerOutput(const MediaStreamer::Settings & settings) Create a new MediaStreamer instance to output data from this MediaReceiver.
bool	removeMediaStreamerOutput(const std::string & uuid) Remove an MediaStreamer created via the.
std::shared_ptr< IControlDataReceiver >	getControlDataReceiver() Get a pointer to the ControlDataReceiver instance of this MediaReceiver. A call to this method will always return the same instance.
void	setTallyBorder(uint32_t inputSlot, TallyBorderColor color) Set tally border color in the multi-views for a specific input slot.
void	clearTallyBorder(uint32_t inputSlot) Remove tally border in the multi-views for a specific input slot.
void	clearAllTallyBorders() Remove all tally borders.
MediaReceiver::TallyBorderColor	getTallyBorder(uint32_t inputSlot) const get tally border color for an input slot
	MediaReceiver(MediaReceiver const & ) =delete MediaReceiver is neither copyable nor movable.
	MediaReceiver(MediaReceiver && ) =delete
MediaReceiver &	operator=(MediaReceiver const & ) =delete
MediaReceiver &	operator=(MediaReceiver && ) =delete
std::string	getVersion() Get application version.
std::string	getLibraryVersions() Get versions of the libraries available at runtime, among others, CUDA runtime and driver versions.

Public Types Documentation

enum TallyBorderColor

Enumerator	Value	Description
kNone
kRed
kGreen
kYellow

Available colors for tally border in multi view.

Public Functions Documentation

function MediaReceiver

MediaReceiver()

Default constructor.

function ~MediaReceiver

~MediaReceiver()

Default destructor.

function start

bool start(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    CUcontext cudaContext,
    const Settings & settings,
    const ControlDataReceiver::Settings & receiverSettings
)

Start the MediaReceiver. This method will call connect on the System controller interface and set up the callbacks from the interface to call internal methods.

Parameters:

controllerInterface The ISystemControllerInterface to use for this MediaReceiver. The interface should be configured (Such as setting the IP address and port of the System Controller if a server based System Controller is used) but not connected before passed to this method. This method will internally set the callbacks before connecting to the controller. If the controller is already connected or if the controller is not configured, this method will return false. This class will take ownership of the smart pointer.
cudaContext The CUDA context to use for this MediaReceiver. The frames will delivered as CUDA pointers, valid in this context, and the multi-view generator will use this context for rendering and encoding.
settings The settings to use for the MediaReceiver.
receiverSettings The settings to use for the ControlDataReceiver.

Return: True if the MediaReceiver was started successfully, false otherwise.

function stop

void stop()

Stop the MediaReceiver.

function getCustomMultiViewSourceInput

std::function< void(const AlignedFramePtr &)> getCustomMultiViewSourceInput(
    uint32_t inputSlot,
    const std::string & name =""
)

This method allows the Rendering Engine to provide custom input sources to the Multi-view generator to send video streams that can be added to the multi-views. This could for instance be used for adding a “preview” of the video stream the rendering engine is about to cut to.

Parameters:

inputSlot The input slot this source will be “plugged in” to. The custom input sources share the input slots with the streams connected from Ingests. This means that it is probably a good idea to use higher numbered slots for these custom inputs, such as numbers from 1000, so that the lower numbers, 1 and up, can be used by the connected video cameras, as the input slot number will also be used when cutting.
name Optional human readable name of this stream, to be presented to the System Controller.

See: MediaReceiver::Settings::mDecodedFormat.

Return: A function to where the Rendering Engine should send the frames. In case the requested inputSlot is already used by another custom input source, or a stream from an ingest, the returned function will be nullptr.

Note: Make sure no CUDA stream will write to the DeviceMemory in the AlignedFrame passed to the function. Failing to do so will lead to undefined behavior. In case another CUDA stream has written to the DeviceMemory, make sure to synchronize with the stream before passing the AlignedFrame.

Precondition: The AlignedFrame sent to this function must have the same pixel format as this MediaReceiver is configured to deliver to the Rendering Engine,

function removeCustomMultiViewSourceInput

bool removeCustomMultiViewSourceInput(
    uint32_t inputSlot
)

Remove a custom multi-view generator source input earlier registered using the getCustomMultiViewSourceInput method.

Parameters:

inputSlot The input slot the custom multi-view source input is connected to, that should be removed

Return: True if the custom multi-view source input was successfully removed, false in case there was no custom input registered for the given input slot, or in case of an internal error.

function createMediaStreamerOutput

std::shared_ptr< IMediaStreamer > createMediaStreamerOutput(
    const MediaStreamer::Settings & settings
)

Create a new MediaStreamer instance to output data from this MediaReceiver.

Parameters:

settings The settings for the new MediaStreamer

Return: A shared pointer to the MediaStreamer instance in case of a successful creation, otherwise nullptr

function removeMediaStreamerOutput

bool removeMediaStreamerOutput(
    const std::string & uuid
)

Remove an MediaStreamer created via the.

Parameters:

uuid The UUID of the MediaStreamer to remove

See: createMediaStreamerOutput method by its UUID.

Return: True if the MediaStreamer was successfully removed, false in case no MediaStreamer with the given UUID was found.

function getControlDataReceiver

std::shared_ptr< IControlDataReceiver > getControlDataReceiver()

Get a pointer to the ControlDataReceiver instance of this MediaReceiver. A call to this method will always return the same instance.

See: start.

Return: Pointer to the ControlDataReceiver instance. Nullptr if called before a successful call to

function setTallyBorder

void setTallyBorder(
    uint32_t inputSlot,
    TallyBorderColor color
)

Set tally border color in the multi-views for a specific input slot.

Parameters:

inputSlot the input slot for a source
color the color to set

function clearTallyBorder

void clearTallyBorder(
    uint32_t inputSlot
)

Remove tally border in the multi-views for a specific input slot.

Parameters:

inputSlot the input slot for a source

function clearAllTallyBorders

void clearAllTallyBorders()

Remove all tally borders.

function getTallyBorder

MediaReceiver::TallyBorderColor getTallyBorder(
    uint32_t inputSlot
) const

get tally border color for an input slot

Parameters:

inputSlot the input slot to get color for

Return: the tally border color for the given input slot

function MediaReceiver

MediaReceiver(
    MediaReceiver const & 
) =delete

MediaReceiver is neither copyable nor movable.

function MediaReceiver

MediaReceiver(
    MediaReceiver && 
) =delete

function operator=

MediaReceiver & operator=(
    MediaReceiver const & 
) =delete

function operator=

MediaReceiver & operator=(
    MediaReceiver && 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “6.0.0-39-g60a35937”

function getLibraryVersions

static std::string getLibraryVersions()

Get versions of the libraries available at runtime, among others, CUDA runtime and driver versions.

Return: a string with the currently found versions of the libraries used by this application

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.25 - MediaReceiver::NewStreamParameters

MediaReceiver::NewStreamParameters

A struct containing information on the format of an incoming stream.

#include <MediaReceiver.h>

Public Attributes

	Name
uint32_t	mVideoHeight
uint32_t	mVideoWidth
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mAudioSampleRate

Public Attributes Documentation

variable mVideoHeight

uint32_t mVideoHeight = 0;

variable mVideoWidth

uint32_t mVideoWidth = 0;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 1;

variable mAudioSampleRate

uint32_t mAudioSampleRate = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.26 - MediaReceiver::Settings

MediaReceiver::Settings

Settings for a MediaReceiver.

#include <MediaReceiver.h>

Public Attributes

	Name
PixelFormat	mDecodedFormat The pixel format delivered to the rendering engine.
std::function< std::function< void(const AlignedFramePtr &)>uint32_t inputSlot, const std::string &streamID, const NewStreamParameters &newStreamParameters)>	mNewConnectionCallback
std::function< void(uint32_t inputSlot)>	mClosedConnectionCallback
std::function< std::optional< std::string >)>	mResetCallback
bool	mUseMultiViewer
bool	mDeliverOld Set to true if this MediaReceiver should have a multi-view generator.
CUstream	mAlignedFrameFreeStream

Public Attributes Documentation

variable mDecodedFormat

PixelFormat mDecodedFormat = PixelFormat::kRgba64Le;

The pixel format delivered to the rendering engine.

variable mNewConnectionCallback

std::function< std::function< void(const AlignedFramePtr &)>uint32_t inputSlot, const std::string &streamID, const NewStreamParameters &newStreamParameters)> mNewConnectionCallback;

Parameters:

inputSlot can be seen as a virtual SDI input on a hardware mixer and should be used by the Rendering engine to identify sources. For example, if a source is connected to input slot 5, the button “Cut to camera 5” on the control panel ought to cut to this stream. The MediaReceiver is responsible for making sure only one stream can be connected to an input slot at a time. This callback might be called multiple times with the same input slot, however, in case the stream has been disconnected and the mClosedConnectionCallback has been called for that input slot earlier.
streamID is the identification string of the video/audio source on the Ingest. A Rendering engine might have the same StreamID connected multiple times (for instance if two different alignments are used for the same source) so this should not be used as an unique identifier for the stream.
newStreamParameters contains information on the pending incoming stream to allow the Rendering engine to decide if it can receive it or not.

Note: The internal CUDA stream is synchronized before delivering the AlignedFrames, meaning the DeviceMemory in the AlignedFrame will always contain the written data; no further synchronization is needed before the rendering engine can read the data.

A callback called by the MediaReceiver whenever a new connection from an Ingest is set up. The callback should return a function to which the data will be delivered. In case the Rendering engine does not want to accept the pending incoming stream (due to a format not supported, etc) the Rendering engine can return nullptr.

variable mClosedConnectionCallback

std::function< void(uint32_t inputSlot)> mClosedConnectionCallback;

Parameters:

inputSlot The input slot that was disconnected

A callback called whenever a connection from an Ingest has been stopped. When receiving this callback, the callback function returned by the mNewConnectionCallback will not be called anymore and can be discarded if required by the application. After this function has been called, the input slot might be reused by another incoming stream after a call to the mNewConnectionCallback.

variable mResetCallback

std::function< std::optional< std::string >)> mResetCallback;

See: mNewConnectionCallback should be kept, however).

Return: True on successful reset, false in case something unexpected happened

A callback called whenever the System Controller has requested that the Rendering Engine should be reset to its initial state (connections made via the

variable mUseMultiViewer

bool mUseMultiViewer = false;

variable mDeliverOld

bool mDeliverOld = false;

Set to true if this MediaReceiver should have a multi-view generator.

variable mAlignedFrameFreeStream

CUstream mAlignedFrameFreeStream = nullptr;

Set to true if the media frames should be delivered, even if the delivery time has already passed, otherwise they are discarded The CUDA stream to use for asynchronously freeing the AlignedFrames’ DeviceMemory. Set this to the rendering engine’s CUDA stream, to ensure memory is not freed before the rendering engine is done using it asynchronously in its CUDA stream. Note that the MediaReceiver instance and all AlignedFrames delivered from it must be destroyed before the CUDA stream can be destroyed.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.27 - SystemControllerConnection

SystemControllerConnection

An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.

#include <SystemControllerConnection.h>

Inherits from ISystemControllerInterface

Public Classes

	Name
struct	Settings Settings for a SystemControllerConnection.

Public Types

	Name
enum class uint32_t	ComponentType { kIngest, kPipeline, kControlPanel} Enumeration of component types the component using this SystemControllerConnection can tell the System Controller to be seen as.

Public Functions

	Name
	SystemControllerConnection()
	~SystemControllerConnection() override
bool	configure(const Settings & settings) Configure this connection. This method should be called before calling.
virtual bool	connect() override Connect to the server using the settings set with the.
virtual bool	isConnected() const override
virtual std::string	getUUID() const override
virtual std::optional< std::string >	sendMessage(const std::string & messageTitle, const nlohmann::json & parameters) override Send a message containing a JSON object to the system controller server.
virtual bool	disconnect() override Disconnect from the server.
virtual bool	registerRequestCallback(const Callbacks & callbacks) override Register callbacks to call when getting requests from the server or the server connection is lost.
	SystemControllerConnection(SystemControllerConnection const & ) =delete
	SystemControllerConnection(SystemControllerConnection && ) =delete
SystemControllerConnection &	operator=(SystemControllerConnection const & ) =delete
SystemControllerConnection &	operator=(SystemControllerConnection && ) =delete

Additional inherited members

Public Classes inherited from ISystemControllerInterface

	Name
struct	Callbacks A struct containing the callbacks that needs to be registered by the component using this interface.
struct	Response A response to a request, consists of a status code and an (optional) parameters JSON object.

Public Types inherited from ISystemControllerInterface

	Name
enum class uint32_t	StatusCode { SUCCESS, TOO_MANY_REQUESTS, UUID_ALREADY_REGISTERED, FORMAT_ERROR, ALREADY_CONFIGURED, OUT_OF_RESOURCES, NOT_FOUND, INTERNAL_ERROR, CONNECTION_FAILED, TIMEOUT_EXCEEDED, KEY_MISMATCH, UNKNOWN_REQUEST, MALFORMED_REQUEST, ALREADY_IN_USE, VERSION_MISMATCH} Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Name

enum class uint32_t

StatusCode { SUCCESS, TOO_MANY_REQUESTS, UUID_ALREADY_REGISTERED, FORMAT_ERROR, ALREADY_CONFIGURED, OUT_OF_RESOURCES, NOT_FOUND, INTERNAL_ERROR, CONNECTION_FAILED, TIMEOUT_EXCEEDED, KEY_MISMATCH, UNKNOWN_REQUEST, MALFORMED_REQUEST, ALREADY_IN_USE, VERSION_MISMATCH}
Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions inherited from ISystemControllerInterface

	Name
virtual	~ISystemControllerInterface() =default Virtual destructor.

Public Types Documentation

enum ComponentType

Enumerator	Value	Description
kIngest
kPipeline
kControlPanel

Enumeration of component types the component using this SystemControllerConnection can tell the System Controller to be seen as.

Public Functions Documentation

function SystemControllerConnection

SystemControllerConnection()

function ~SystemControllerConnection

~SystemControllerConnection() override

function configure

bool configure(
    const Settings & settings
)

Configure this connection. This method should be called before calling.

Parameters:

settings The settings to use when connecting to the server

See: connect.

Return: True if successfully configured, false otherwise

function connect

virtual bool connect() override

Connect to the server using the settings set with the.

See: configure method.

Return: True if connection was successful, false otherwise

Reimplements: ISystemControllerInterface::connect

function isConnected

virtual bool isConnected() const override

Return: True if this class is connected to the server, false otherwise

Reimplements: ISystemControllerInterface::isConnected

function getUUID

virtual std::string getUUID() const override

Return: The UUID of this interface to the System controller

Reimplements: ISystemControllerInterface::getUUID

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) override

Send a message containing a JSON object to the system controller server.

Parameters:

messageTitle The title of the status type or request
parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplements: ISystemControllerInterface::sendMessage

function disconnect

virtual bool disconnect() override

Disconnect from the server.

Return: True if successfully disconnected, false on internal error

Reimplements: ISystemControllerInterface::disconnect

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) override

Parameters:

callbacks The callbacks to set

Return: True if successfully registered, false if a callback is not set, or if already connected to the server

Reimplements: ISystemControllerInterface::registerRequestCallback

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection const & 
) =delete

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection && 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection const & 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection && 
) =delete

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.28 - SystemControllerConnection::Settings

SystemControllerConnection::Settings

Settings for a SystemControllerConnection.

#include <SystemControllerConnection.h>

Public Attributes

	Name
std::string	mSystemControllerIP
uint16_t	mSystemControllerPort
std::string	mSystemControllerPostfix
std::string	mPSK
std::string	mUUID
ComponentType	mType
std::string	mName
std::string	mMyIP
std::chrono::milliseconds	mConnectTimeout
bool	mEnableHTTPS
bool	mInsecureHTTPS
std::string	mCustomCaCertFile

Public Attributes Documentation

variable mSystemControllerIP

std::string mSystemControllerIP;

variable mSystemControllerPort

uint16_t mSystemControllerPort;

variable mSystemControllerPostfix

std::string mSystemControllerPostfix;

variable mPSK

std::string mPSK;

variable mUUID

std::string mUUID;

variable mType

ComponentType mType;

variable mName

std::string mName;

variable mMyIP

std::string mMyIP;

variable mConnectTimeout

std::chrono::milliseconds mConnectTimeout {
            3000};

variable mEnableHTTPS

bool mEnableHTTPS;

variable mInsecureHTTPS

bool mInsecureHTTPS;

variable mCustomCaCertFile

std::string mCustomCaCertFile;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.29 - TimeCommon::TAIStatus

TimeCommon::TAIStatus

Public Attributes

	Name
StratumLevel	mStratum
bool	mHasLock
double	mTimeDiffS

Public Attributes Documentation

variable mStratum

StratumLevel mStratum = StratumLevel::UnknownStratum;

variable mHasLock

bool mHasLock = false;

variable mTimeDiffS

double mTimeDiffS = 0.0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.1.30 - TimeCommon::TimeStructure

TimeCommon::TimeStructure

Public Attributes

	Name
uint64_t	t1
uint64_t	t2
uint64_t	t3
uint64_t	t4
uint64_t	token
uint64_t	dummy1
uint64_t	dummy2
uint64_t	dummy3

Public Attributes Documentation

variable t1

uint64_t t1 = 0;

variable t2

uint64_t t2 = 0;

variable t3

uint64_t t3 = 0;

variable t4

uint64_t t4 = 0;

variable token

uint64_t token = 0;

variable dummy1

uint64_t dummy1 = 0;

variable dummy2

uint64_t dummy2 = 0;

variable dummy3

uint64_t dummy3 = 0;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2 - Files

Files

dir build
- dir install
  - dir include
    - file include/AclLog.h
    - file include/AlignedFrame.h
    - file include/Base64.h
    - file include/ControlDataCommon.h
    - file include/ControlDataSender.h
    - file include/DeviceMemory.h
    - file include/IControlDataReceiver.h
    - file include/IMediaStreamer.h
    - file include/ISystemControllerInterface.h
    - file include/IngestApplication.h
    - file include/IngestUtils.h
    - file include/MediaReceiver.h
    - file include/PixelFormat.h
    - file include/SystemControllerConnection.h
    - file include/TimeCommon.h
    - file include/UUIDUtils.h

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.1 - include/AclLog.h

include/AclLog.h

Namespaces

Name
AclLog A namespace for logging utilities.

Classes

	Name
class	AclLog::CommandLogFormatter This class is used to format log entries for Rendering Engine commands.
class	AclLog::ThreadNameFormatterFlag
class	AclLog::FileLocationFormatterFlag A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <filesystem>
#include <string>

#include <spdlog/details/log_msg.h>
#include <spdlog/fmt/fmt.h>
#include <spdlog/formatter.h>
#include <spdlog/pattern_formatter.h>
#include <sys/prctl.h>

namespace AclLog {

enum class Level {
    kTrace,    // Detailed diagnostics (for development only)
    kDebug,    // Messages intended for debugging only
    kInfo,     // Messages about normal behavior (default log level)
    kWarning,  // Warnings (functionality intact)
    kError,    // Recoverable errors (functionality impaired)
    kCritical, // Unrecoverable errors (application must stop)
    kOff       // Turns off all logging
};

void init(const std::string& name);

void initCommandLog(const std::string& name);

void setLevel(Level level);

void logCommand(const std::string& origin, const std::string& command);

AclLog::Level getLogLevel();

size_t getMaxFileSize();

size_t getMaxLogRotations();

std::filesystem::path getLogFileFullPath(const std::string& name);

class CommandLogFormatter : public spdlog::formatter {
public:
    CommandLogFormatter();
    void format(const spdlog::details::log_msg& msg, spdlog::memory_buf_t& dest) override;
    [[nodiscard]] std::unique_ptr<spdlog::formatter> clone() const override;

private:
    std::unique_ptr<spdlog::pattern_formatter> mCommandLogPattern;
};

inline std::string getThreadName() {
    static const size_t RECOMMENDED_BUFFER_SIZE = 20;
    static thread_local std::string name;

    if (name.empty()) {
        char buffer[RECOMMENDED_BUFFER_SIZE];
        int retval = prctl(PR_GET_NAME, buffer);
        if (retval == -1) {
            throw spdlog::spdlog_ex("Failed to get thread name: ", errno);
        }
        name = std::string(buffer);
    }
    return name;
}

class ThreadNameFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg&, const std::tm&, spdlog::memory_buf_t& dest) override {
        std::string threadName = getThreadName();
        dest.append(threadName.data(), threadName.data() + threadName.size());
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<ThreadNameFormatterFlag>();
    }
};

class FileLocationFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg& msg, const std::tm&, spdlog::memory_buf_t& dest) override {
        if (!msg.source.empty()) {
            using namespace spdlog::details;

            dest.push_back('[');
            const char* filename = short_filename_formatter<null_scoped_padder>::basename(msg.source.filename);
            fmt_helper::append_string_view(filename, dest);
            dest.push_back(':');
            fmt_helper::append_int(msg.source.line, dest);
            dest.push_back(']');
        }
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<FileLocationFormatterFlag>();
    }
};

} // namespace AclLog

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.2 - include/AlignedFrame.h

include/AlignedFrame.h

Classes

	Name
struct	AlignedAudioFrame AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.
struct	AlignedFrame A frame of aligned data that is passed to the rendering engine from the MediaReceiver. A DataFrame contains a time stamped frame of media, which might be video, audio and auxiliary data such as subtitles. A single DataFrame can contain one or multiple types of media. Which media types are included can be probed by nullptr-checking/size checking the data members. The struct has ownership of all data pointers included. The struct includes all logic for freeing the resources held by this struct and the user should therefore just make sure the struct itself is deallocated to ensure all resources are freed.

Name

struct

AlignedAudioFrame
AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.

struct

AlignedFrame
A frame of aligned data that is passed to the rendering engine from the MediaReceiver. A DataFrame contains a time stamped frame of media, which might be video, audio and auxiliary data such as subtitles. A single DataFrame can contain one or multiple types of media. Which media types are included can be probed by nullptr-checking/size checking the data members. The struct has ownership of all data pointers included. The struct includes all logic for freeing the resources held by this struct and the user should therefore just make sure the struct itself is deallocated to ensure all resources are freed.

Types

	Name
using std::shared_ptr< AlignedAudioFrame >	AlignedAudioFramePtr
using std::shared_ptr< const AlignedAudioFrame >	AlignedAudioFrameConstPtr
using std::shared_ptr< AlignedFrame >	AlignedFramePtr

Functions

	Name
AlignedAudioFramePtr	createAlignedAudioFrame(uint8_t numberOfChannels, uint32_t numberOfSamplesPerChannel) Create a new AudioFrame with a given amount of samples allocated and all samples initialized to 0.0f.
AlignedAudioFramePtr	extractChannel(AlignedAudioFrameConstPtr sourceFrame, uint8_t channelIndex) Extract one channel from an AlignedAudioFrame as a new AlignedAudioFrame. The new AlignedAudioFrame will share no data with the original frame, meaning the new frame can be edited without corrupting the old one.

Types Documentation

using AlignedAudioFramePtr

using AlignedAudioFramePtr =  std::shared_ptr<AlignedAudioFrame>;

using AlignedAudioFrameConstPtr

using AlignedAudioFrameConstPtr =  std::shared_ptr<const AlignedAudioFrame>;

using AlignedFramePtr

using AlignedFramePtr =  std::shared_ptr<AlignedFrame>;

Functions Documentation

function createAlignedAudioFrame

AlignedAudioFramePtr createAlignedAudioFrame(
    uint8_t numberOfChannels,
    uint32_t numberOfSamplesPerChannel
)

Create a new AudioFrame with a given amount of samples allocated and all samples initialized to 0.0f.

Parameters:

numberOfChannels Number of channels to allocate space for
numberOfSamplesPerChannel Number of samples per channel to allocate space for

Return: Shared pointer to the new AudioFrame

function extractChannel

AlignedAudioFramePtr extractChannel(
    AlignedAudioFrameConstPtr sourceFrame,
    uint8_t channelIndex
)

Extract one channel from an AlignedAudioFrame as a new AlignedAudioFrame. The new AlignedAudioFrame will share no data with the original frame, meaning the new frame can be edited without corrupting the old one.

Parameters:

sourceFrame The frame to extract a channel from
channelIndex The zero-based channel index to extract

Return: Shared pointer to a new mono AlignedAudioFrame, or nullptr if channel is out of bounds

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <array>
#include <iostream>
#include <memory>
#include <vector>

#include <cuda_runtime_api.h>

#include "DeviceMemory.h"
#include "PixelFormat.h"

struct AlignedAudioFrame {
    // The samples interleaved
    std::vector<float> mSamples;
    uint8_t mNumberOfChannels = 0;
    uint32_t mNumberOfSamplesPerChannel = 0;
};

using AlignedAudioFramePtr = std::shared_ptr<AlignedAudioFrame>;
using AlignedAudioFrameConstPtr = std::shared_ptr<const AlignedAudioFrame>;

AlignedAudioFramePtr createAlignedAudioFrame(uint8_t numberOfChannels, uint32_t numberOfSamplesPerChannel);

AlignedAudioFramePtr extractChannel(AlignedAudioFrameConstPtr sourceFrame, uint8_t channelIndex);

struct AlignedFrame {

    AlignedFrame() = default;

    ~AlignedFrame() = default;

    AlignedFrame(AlignedFrame const&) = delete;            // Copy construct
    AlignedFrame& operator=(AlignedFrame const&) = delete; // Copy assign

    [[nodiscard]] std::shared_ptr<AlignedFrame> makeShallowCopy() const;

    int64_t mCaptureTimestamp = 0;

    int64_t mRenderingTimestamp = 0;

    // Video
    std::shared_ptr<DeviceMemory> mVideoFrame = nullptr;
    PixelFormat mPixelFormat = PixelFormat::kUnknown;
    uint32_t mFrameRateN = 0;
    uint32_t mFrameRateD = 0;
    uint32_t mWidth = 0;
    uint32_t mHeight = 0;

    // Audio
    AlignedAudioFramePtr mAudioFrame = nullptr;
    uint32_t mAudioSamplingFrequency = 0;
};

using AlignedFramePtr = std::shared_ptr<AlignedFrame>;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.3 - include/Base64.h

include/Base64.h

Functions

	Name
std::string	encodeBase64(const uint8_t * data, size_t size) Base64 encode some data.
std::string	encodeBase64(const std::vector< uint8_t > & data) Base64 encode some data.
std::vector< uint8_t >	decodeBase64(const std::string & data) Decode some Base64 encoded data.

Functions Documentation

function encodeBase64

std::string encodeBase64(
    const uint8_t * data,
    size_t size
)

Base64 encode some data.

Parameters:

data Pointer to the data to encode with Base64
size The length of the data to encode with Base64

Return: The resulting Base64 encoded string

function encodeBase64

std::string encodeBase64(
    const std::vector< uint8_t > & data
)

Base64 encode some data.

Parameters:

data The data to encode with Base64

Return: The resulting Base64 encoded string

function decodeBase64

std::vector< uint8_t > decodeBase64(
    const std::string & data
)

Decode some Base64 encoded data.

Parameters:

data The Base64 encoded string to decode

Return: The resulting decoded data

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <string>
#include <vector>

std::string encodeBase64(const uint8_t* data, size_t size);

std::string encodeBase64(const std::vector<uint8_t>& data);

std::vector<uint8_t> decodeBase64(const std::string& data);

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.4 - include/ControlDataCommon.h

include/ControlDataCommon.h

Namespaces

Name
ControlDataCommon

Classes

	Name
struct	ControlDataCommon::ConnectionStatus Connection status struct containing information about a connection event.
struct	ControlDataCommon::Response A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
struct	ControlDataCommon::StatusMessage A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <cstdint>
#include <string>
#include <vector>

namespace ControlDataCommon {

enum class ConnectionType { CONNECTED, DISCONNECTED };

struct ConnectionStatus {

    ConnectionStatus() = default;

    ConnectionStatus(ConnectionType mConnectionType, const std::string& mIp, uint16_t mPort)
        : mConnectionType(mConnectionType)
        , mIP(mIp)
        , mPort(mPort) {
    }

    ConnectionType mConnectionType = ConnectionType::DISCONNECTED;
    std::string mIP;
    uint16_t mPort = 0;
};

struct Response {
    std::vector<uint8_t> mMessage; 
    uint64_t mRequestId = 0;       
    std::string mFromUUID;         
};

struct StatusMessage {
    std::vector<uint8_t> mMessage; 
    std::string mFromUUID;         
};

} // namespace ControlDataCommon

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.5 - include/ControlDataSender.h

include/ControlDataSender.h

Classes

Name

class

ControlDataSender
A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.

struct

ControlDataSender::Settings
Settings for a ControlDataSender.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <functional>
#include <memory>
#include <vector>

#include <ISystemControllerInterface.h>

#include "ControlDataCommon.h"

class ControlDataSender final {
public:
    struct Settings {
        std::function<void(const ControlDataCommon::ConnectionStatus&)>
            mConnectionStatusCallback; // Callback for receiver connection/disconnection events
        std::function<void(const ControlDataCommon::Response&)>
            mResponseCallback; // Callback for response messages from receivers
        std::function<void(const ControlDataCommon::StatusMessage&)>
            mStatusMessageCallback; // Callback for status messages from receivers
    };

    ControlDataSender();

    ~ControlDataSender();

    bool configure(const std::shared_ptr<ISystemControllerInterface>& controllerInterface, const Settings& settings);

    bool sendRequestToReceivers(const std::vector<uint8_t>& request, uint64_t& requestId);

    bool sendMultiRequestToReceivers(const std::vector<std::vector<uint8_t>>& request, uint64_t& requestId);

    static std::string getVersion();

    // ControlDataSender is not copyable
    ControlDataSender(ControlDataSender const&) = delete;            // Copy construct
    ControlDataSender& operator=(ControlDataSender const&) = delete; // Copy assign

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.6 - include/DeviceMemory.h

include/DeviceMemory.h

Classes

	Name
class	DeviceMemory RAII class for a CUDA memory buffer.

Types

	Name
using std::shared_ptr< DeviceMemory >	DeviceMemoryPtr

Types Documentation

using DeviceMemoryPtr

using DeviceMemoryPtr =  std::shared_ptr<DeviceMemory>;

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <cstddef>
#include <cstdint>
#include <memory>

#include <cuda_runtime.h>

class DeviceMemory {
public:
    DeviceMemory() = default;

    explicit DeviceMemory(size_t numberOfBytes);

    explicit DeviceMemory(size_t numberOfBytes, cudaStream_t cudaStream);

    explicit DeviceMemory(void* deviceMemory) noexcept;

    bool allocateMemory(size_t numberOfBytes);

    bool allocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream);

    bool reallocateMemory(size_t numberOfBytes);

    bool reallocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream);

    bool allocateAndResetMemory(size_t numberOfBytes);

    bool allocateAndResetMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream);

    bool freeMemory();

    bool freeMemoryAsync(cudaStream_t cudaStream);

    void setFreeingCudaStream(cudaStream_t cudaStream);

    ~DeviceMemory();

    template <typename T = uint8_t> [[nodiscard]] T* getDevicePointer() const {
        return reinterpret_cast<T*>(dMemory);
    }

    [[nodiscard]] size_t getSize() const;

    DeviceMemory(DeviceMemory&& other) noexcept;
    DeviceMemory& operator=(DeviceMemory&& other) noexcept;

    void swap(DeviceMemory& other) noexcept;

    DeviceMemory(DeviceMemory const&) = delete;
    DeviceMemory operator=(DeviceMemory const&) = delete;

private:
    uint8_t* dMemory = nullptr;
    size_t mAllocatedBytes = 0;
    cudaStream_t mCudaStream = nullptr; // Stream to use for Async free
};

using DeviceMemoryPtr = std::shared_ptr<DeviceMemory>;

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.7 - include/IControlDataReceiver.h

include/IControlDataReceiver.h

Classes

	Name
class	IControlDataReceiver IControlDataReceiver is the interface class for the control data receiver. An IControlDataReceiver can receive messages from a sender or other IControlDataReceivers using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a `receiving` or `listening` side, as well as a `sending` side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests.
struct	IControlDataReceiver::IncomingRequest An incoming request to this ControlDataReceiver.
struct	IControlDataReceiver::ReceiverResponse A response message to a request.
struct	IControlDataReceiver::Settings Settings for a ControlDataReceiver.

Source code

// Copyright (c) 2024, Edgeware AB. All rights reserved.

#pragma once

#include <memory>

#include <ISystemControllerInterface.h>

#include "ControlDataCommon.h"

class IControlDataReceiver {
public:
    struct IncomingRequest {
        std::vector<std::vector<uint8_t>> mMessages; 
        std::string mSenderUUID;    
        std::string mRequesterUUID; 
        uint64_t mRequestID = 0;    
        int64_t mSenderTimestampUs =
            0; 
        int64_t mDeliveryTimestampUs =
            0; 
    };

    struct ReceiverResponse {
        std::vector<uint8_t> mMessage; 
    };

    struct Settings {
        std::string mProductionPipelineUUID; 
        std::function<void(const IncomingRequest&)> mPreviewIncomingRequestCallback;
        std::function<ReceiverResponse(const IncomingRequest&)> mIncomingRequestCallback;

        std::function<void(const ControlDataCommon::ConnectionStatus&)>
            mConnectionStatusCallback; 
        std::function<void(const ControlDataCommon::Response&)>
            mResponseCallback; 
    };

    virtual ~IControlDataReceiver() = default;

    virtual bool configure(const Settings& settings) = 0;

    virtual bool sendStatusMessageToSender(const std::vector<uint8_t>& message) = 0;

    virtual bool sendRequestToReceivers(const std::vector<uint8_t>& request, uint64_t& requestId) = 0;

    virtual bool sendMultiRequestToReceivers(const std::vector<std::vector<uint8_t>>& request, uint64_t& requestId) = 0;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.8 - include/IMediaStreamer.h

include/IMediaStreamer.h

Classes

	Name
class	IMediaStreamer IMediaStreamer is an interface class for MediaStreamers, that can take a single stream of uncompressed video and/or audio frames and encode and output it in some way. This output can either be a stream to a network or writing down the data to a file on the hard drive. This class is configured from two interfaces. The input configuration (input video resolution, frame rate, pixel format, number of audio channels…) is made through this C++ API. The output stream is then started from the System Controller. Any of these configurations can be made first. The actual stream to output will start once the first call to.
struct	IMediaStreamer::Settings Settings used when creating a new MediaStreamer.
struct	IMediaStreamer::Configuration The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.

Source code

// Copyright (c) 2024, Edgeware AB. All rights reserved.

#pragma once

#include <memory>

#include <ISystemControllerInterface.h>
#include <cuda.h>

#include "AlignedFrame.h"

class IMediaStreamer {
public:
    struct Settings {
        std::string mName; // Human-readable name, presented in the REST API
    };

    struct Configuration {
        // Video
        PixelFormat mIncomingPixelFormat = PixelFormat::kUnknown;
        uint32_t mWidth = 0;      // Width of the incoming video frames in pixels
        uint32_t mHeight = 0;     // Height of the incoming video frames in pixels
        uint32_t mFrameRateN = 0; // Frame rate numerator of the incoming video frames
        uint32_t mFrameRateD = 0; // Frame rate denominator of the incoming video frames

        // Audio
        uint32_t mAudioSampleRate = 0;  // Audio sample rate of the incoming frames in Hz
        uint32_t mNumAudioChannels = 0; // Number of audio channels in the incoming frames
    };

    virtual ~IMediaStreamer() = default;

    virtual bool configure(const std::string& uuid, const Settings& settings, CUcontext cudaContext) = 0;

    virtual bool setInputFormatAndStart(const Configuration& configuration) = 0;

    virtual bool stopAndResetFormat() = 0;

    [[nodiscard]] virtual bool hasFormatAndIsRunning() const = 0;

    [[nodiscard]] virtual bool hasOpenOutputStream() const = 0;

    virtual bool outputData(const AlignedFramePtr& frame) = 0;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.9 - include/IngestApplication.h

include/IngestApplication.h

Classes

	Name
class	IngestApplication
struct	IngestApplication::Settings

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <memory>

#include "ISystemControllerInterface.h"

class IngestApplication {
public:
    struct Settings {};

    IngestApplication();

    ~IngestApplication();

    bool start(const std::shared_ptr<ISystemControllerInterface>& controllerInterface, const Settings& settings);

    bool stop();

    static std::string getVersion();

    static std::string getLibraryVersions();

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.10 - include/IngestUtils.h

include/IngestUtils.h

Namespaces

Name
IngestUtils

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

namespace IngestUtils {

bool isRunningWithRootPrivileges();

} // namespace IngestUtils

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.11 - include/ISystemControllerInterface.h

include/ISystemControllerInterface.h

Classes

	Name
class	ISystemControllerInterface An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server.
struct	ISystemControllerInterface::Response A response to a request, consists of a status code and an (optional) parameters JSON object.
struct	ISystemControllerInterface::Callbacks A struct containing the callbacks that needs to be registered by the component using this interface.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <functional>
#include <json.hpp>
#include <optional>
#include <string>

class ISystemControllerInterface {
public:
    enum class StatusCode : uint32_t {
        SUCCESS = 3001, // Accept / Success

        TOO_MANY_REQUESTS = 3101, // Too many requests, try again later

        UUID_ALREADY_REGISTERED = 3201, // UUID is already registered
        FORMAT_ERROR = 3202,            // Message formatting error
        ALREADY_CONFIGURED = 3203,      // The requested thing to configure is already configured
        OUT_OF_RESOURCES = 3204,  // Out of resources (CPU/GPU close to max utilization, all available slots used, etc.)
        NOT_FOUND = 3205,         // The requested thing was not found
        INTERNAL_ERROR = 3206,    // Internal error when trying to serve the request
        CONNECTION_FAILED = 3207, // Connection failure
        TIMEOUT_EXCEEDED = 3208,  // Timeout exceeded
        KEY_MISMATCH = 3209,      // Key mismatch (might be a timeout, 3007 in the future)
        UNKNOWN_REQUEST = 3210,   // The name of the request was not known
        MALFORMED_REQUEST = 3211, // The request is not correctly formatted
        ALREADY_IN_USE = 3212,    // The requested resource is already in use
        VERSION_MISMATCH = 3213,  // The version of the request is not supported

        // None, yet
    };

    struct Response {
        StatusCode mCode;
        nlohmann::json mParameters; // Can be empty
    };

    struct Callbacks {
        std::function<Response(const std::string&, const nlohmann::json&)>
            mRequestCallback; // Callback called when then controller has sent a request
        std::function<void(uint32_t, const std::string&, const std::error_code&)>
            mConnectionClosedCallback; // Callback called when the connection to the controller is closed
    };

    virtual ~ISystemControllerInterface() = default;

    virtual std::optional<std::string> sendMessage(const std::string& messageTitle,
                                                   const nlohmann::json& parameters) = 0;

    virtual bool registerRequestCallback(const Callbacks& callbacks) = 0;

    virtual bool connect() = 0;

    virtual bool disconnect() = 0;

    [[nodiscard]] virtual bool isConnected() const = 0;

    [[nodiscard]] virtual std::string getUUID() const = 0;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.12 - include/MediaReceiver.h

include/MediaReceiver.h

Classes

	Name
class	MediaReceiver A MediaReceiver contains the logic for receiving, decoding and aligning incoming media sources from the Ingests. The aligned data is then delivered to the Rendering Engine which is also responsible for setting up the MediaReceiver. The MediaReceiver has a builtin multi view generator, which can create output streams containing composited subsets of the incoming video sources. This class is controlled using an ISystemControllerInterface provided when starting it.
struct	MediaReceiver::NewStreamParameters A struct containing information on the format of an incoming stream.
struct	MediaReceiver::Settings Settings for a MediaReceiver.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <memory>
#include <utility>

#include <cuda.h>

#include "AlignedFrame.h"
#include "ControlDataReceiver.h"
#include "ISystemControllerInterface.h"
#include "MediaStreamer.h"

class MediaReceiver {
public:
    struct NewStreamParameters {
        uint32_t mVideoHeight = 0;     // Height of the video in pixels. 0 if the stream does not contain any video
        uint32_t mVideoWidth = 0;      // Width of the video in pixels. 0 if the stream does not contain any video
        uint32_t mFrameRateN = 0;      // Frame rate numerator
        uint32_t mFrameRateD = 1;      // Frame rate denominator
        uint32_t mAudioSampleRate = 0; // Sample rate of the audio in Hz. 0 if the stream does not contain any audio
    };

    struct Settings {
        PixelFormat mDecodedFormat = PixelFormat::kRgba64Le;

        std::function<std::function<void(const AlignedFramePtr&)>(uint32_t inputSlot,
                                                                  const std::string& streamID,
                                                                  const NewStreamParameters& newStreamParameters)>
            mNewConnectionCallback;

        std::function<void(uint32_t inputSlot)> mClosedConnectionCallback;

        std::function<std::optional<std::string>()> mResetCallback;

        bool mUseMultiViewer = false; 
        bool mDeliverOld = false;     

        CUstream mAlignedFrameFreeStream = nullptr;
    };

    enum class TallyBorderColor : uint32_t { kNone, kRed, kGreen, kYellow };

    MediaReceiver();

    ~MediaReceiver();

    bool start(const std::shared_ptr<ISystemControllerInterface>& controllerInterface,
               CUcontext cudaContext,
               const Settings& settings,
               const ControlDataReceiver::Settings& receiverSettings);

    void stop();

    std::function<void(const AlignedFramePtr&)> getCustomMultiViewSourceInput(uint32_t inputSlot,
                                                                              const std::string& name = "");

    bool removeCustomMultiViewSourceInput(uint32_t inputSlot);

    std::shared_ptr<IMediaStreamer> createMediaStreamerOutput(const MediaStreamer::Settings& settings);

    bool removeMediaStreamerOutput(const std::string& uuid);

    std::shared_ptr<IControlDataReceiver> getControlDataReceiver();

    void setTallyBorder(uint32_t inputSlot, TallyBorderColor color);

    void clearTallyBorder(uint32_t inputSlot);

    void clearAllTallyBorders();

    [[nodiscard]] MediaReceiver::TallyBorderColor getTallyBorder(uint32_t inputSlot) const;

    MediaReceiver(MediaReceiver const&) = delete;            // Copy construct
    MediaReceiver(MediaReceiver&&) = delete;                 // Move construct
    MediaReceiver& operator=(MediaReceiver const&) = delete; // Copy assign
    MediaReceiver& operator=(MediaReceiver&&) = delete;      // Move assign

    static std::string getVersion();

    static std::string getLibraryVersions();

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.13 - include/PixelFormat.h

include/PixelFormat.h

Namespaces

Name
ACL

Types

	Name
enum uint32_t	PixelFormat { kUnknown = 0, kNv12 = ACL::makeFourCC(‘N’, ‘V’, ‘1’, ‘2’), kUyvy = ACL::makeFourCC(‘U’, ‘Y’, ‘V’, ‘Y’), kP010 = ACL::makeFourCC(‘P’, ‘0’, ‘1’, ‘0’), kP016 = ACL::makeFourCC(‘P’, ‘0’, ‘1’, ‘6’), kP210 = ACL::makeFourCC(‘P’, ‘2’, ‘1’, ‘0’), kP216 = ACL::makeFourCC(‘P’, ‘2’, ‘1’, ‘6’), kRgba =
ACL::makeFourCC(‘R’, ‘G’, ‘B’, ‘A’), kV210 = ACL::makeFourCC(‘V’, ‘2’, ‘1’, ‘0’), kRgba64Le =
ACL::makeFourCC(‘R’, ‘G’, ‘B’, 64)} Enumeration of FourCC formats.

Functions

	Name
std::ostream &	operator«(std::ostream & stream, PixelFormat pixelFormat) Add the string representation of a PixelFormat to the output stream.

Types Documentation

enum PixelFormat

Enumerator	Value	Description
kUnknown	0
kNv12	ACL::makeFourCC(‘N’, ‘V’, ‘1’, ‘2’)
kUyvy	ACL::makeFourCC(‘U’, ‘Y’, ‘V’, ‘Y’)
kP010	ACL::makeFourCC(‘P’, ‘0’, ‘1’, ‘0’)
kP016	ACL::makeFourCC(‘P’, ‘0’, ‘1’, ‘6’)
kP210	ACL::makeFourCC(‘P’, ‘2’, ‘1’, ‘0’)
kP216	ACL::makeFourCC(‘P’, ‘2’, ‘1’, ‘6’)
kRgba	=
ACL::makeFourCC(‘R’, ‘G’, ‘B’, ‘A’)
kV210	ACL::makeFourCC(‘V’, ‘2’, ‘1’, ‘0’)
kRgba64Le	=
ACL::makeFourCC(‘R’, ‘G’, ‘B’, 64)

Enumeration of FourCC formats.

Functions Documentation

function operator«

std::ostream & operator<<(
    std::ostream & stream,
    PixelFormat pixelFormat
)

Add the string representation of a PixelFormat to the output stream.

Parameters:

pixelFormat The PixelFormat to get as a string

Return: The ostream with the string representation of the PixelFormat appended

Source code

// Copyright (c) 2023, Edgeware AB. All rights reserved.

#pragma once

#include <cstdint>
#include <ostream>

namespace ACL {

constexpr uint32_t makeFourCC(char a, char b, char c, char d) {
    return static_cast<uint32_t>(a) + (static_cast<uint32_t>(b) << 8) + (static_cast<uint32_t>(c) << 16) +
           (static_cast<uint32_t>(d) << 24);
}

} // namespace ACL

enum PixelFormat : uint32_t {
    kUnknown = 0,                                // Unknown format
    kNv12 = ACL::makeFourCC('N', 'V', '1', '2'), // 4:2:0 format with Y plane followed by UVUVUV.. plane
    kUyvy = ACL::makeFourCC('U', 'Y', 'V', 'Y'), // 4:2:2 format with packed UYVY macropixels
    kP010 = ACL::makeFourCC('P', '0', '1', '0'), // 4:2:0 P016 with data in the 10 MSB
    kP016 = ACL::makeFourCC('P', '0', '1', '6'), // 4:2:0 format with 16 bit words, Y plane followed by UVUVUV.. plane
    kP210 = ACL::makeFourCC('P', '2', '1', '0'), // 4:2:2 P216 with data in the 10 MSB
    kP216 = ACL::makeFourCC('P', '2', '1', '6'), // 4:2:2 format with 16 bit words, Y plane followed by UVUVUV.. plane
    kRgba =
        ACL::makeFourCC('R', 'G', 'B', 'A'), // 4:4:4:4 RGB format, 8 bit per channel, ordered RGBARGBARG.. in memory
    kV210 = ACL::makeFourCC('V', '2', '1', '0'), // 4:2:2 packed format with 10 bit per component
    kRgba64Le =
        ACL::makeFourCC('R', 'G', 'B', 64) // 16 bit per component, ordered as RGBA in memory with little endian words.
};

std::ostream& operator<<(std::ostream& stream, PixelFormat pixelFormat);

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.14 - include/SystemControllerConnection.h

include/SystemControllerConnection.h

Classes

	Name
class	SystemControllerConnection An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.
struct	SystemControllerConnection::Settings Settings for a SystemControllerConnection.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <chrono>

#include "ISystemControllerInterface.h"
#include "json.hpp"

class SystemControllerConnection final : public ISystemControllerInterface {
public:
    enum class ComponentType : uint32_t {
        kIngest,
        kPipeline,
        kControlPanel,
    };

    struct Settings {
        std::string mSystemControllerIP;      // IP of the server
        uint16_t mSystemControllerPort;       // Port of the server
        std::string mSystemControllerPostfix; // Postfix of the address that the backend uses if any
        std::string mPSK;    // The pre shared key used for authorization with the system controller server
        std::string mUUID;   // The UUID of the device using this library
        ComponentType mType; // The component type of the component using this SystemControllerConnection
        std::string mName;   // The component name (optional)
        std::string mMyIP;   // The external IP of the system the component is running on. Will be sent to the system
                             // controller server in the announce message (optional)
        std::chrono::milliseconds mConnectTimeout{
            3000};           // Max time to wait on an announcement response from the server during connection
        bool mEnableHTTPS;   // Enable the communication between the system controller and a component encrypted
        bool mInsecureHTTPS; // Disable the verification of the TLS certificate if requested.
        std::string mCustomCaCertFile; // Custom CA certificate
    };

    SystemControllerConnection();
    ~SystemControllerConnection() override;

    bool configure(const Settings& settings);

    bool connect() override;

    [[nodiscard]] bool isConnected() const override;

    [[nodiscard]] std::string getUUID() const override;

    std::optional<std::string> sendMessage(const std::string& messageTitle, const nlohmann::json& parameters) override;

    bool disconnect() override;

    bool registerRequestCallback(const Callbacks& callbacks) override;

    SystemControllerConnection(SystemControllerConnection const&) = delete;            // Copy construct
    SystemControllerConnection(SystemControllerConnection&&) = delete;                 // Move construct
    SystemControllerConnection& operator=(SystemControllerConnection const&) = delete; // Copy assign
    SystemControllerConnection& operator=(SystemControllerConnection&&) = delete;      // Move assign

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.15 - include/TimeCommon.h

include/TimeCommon.h

Namespaces

Name
TimeCommon

Classes

	Name
struct	TimeCommon::TAIStatus
struct	TimeCommon::TimeStructure

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <chrono>
#include <cstdint>
#include <fstream>
#include <sstream>

#include "expected.hpp"

namespace TimeCommon {

enum class StratumLevel {
    UnknownStratum,
    stratum0,
    stratum1,
    stratum2,
    stratum3,
    stratum4,
};

struct TAIStatus {
    StratumLevel mStratum = StratumLevel::UnknownStratum;
    bool mHasLock = false;
    double mTimeDiffS = 0.0; // Time diff vs NTP in seconds, +/- value means slow/faster than NTP time
};

// Little endian
// Minimum size packet is 64 - bytes
struct TimeStructure {
    uint64_t t1 = 0;     // 8-bytes / Total 8-bytes  == Client time T1
    uint64_t t2 = 0;     // 8-bytes / Total 16-bytes == Server
    uint64_t t3 = 0;     // 8-bytes / Total 24-bytes
    uint64_t t4 = 0;     // 8-bytes / Total 32-bytes
    uint64_t token = 0;  // 8-bytes / Total 40-bytes == t1 ^ key
    uint64_t dummy1 = 0; // 8-bytes / Total 48-bytes == for future use
    uint64_t dummy2 = 0; // 8-bytes / Total 56-bytes == for future use
    uint64_t dummy3 = 0; // 8-bytes / Total 64-bytes == for future use
};

uint64_t getMonotonicClockMicro();

tl::expected<TimeCommon::TAIStatus, std::string> getStatus();

int64_t getTAIMicro();

std::string taiMicroToString(int64_t taiTimestamp);
} // namespace TimeCommon

Updated on 2024-04-08 at 15:15:27 +0200

1.4.2.16 - include/UUIDUtils.h

include/UUIDUtils.h

Namespaces

Name
UUIDUtils A namespace for UUID utility functions.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <string>

namespace UUIDUtils {

std::string generateRandomUUID();

bool isValidUUIDString(const std::string& uuid);

} // namespace UUIDUtils

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3 - Namespaces

Namespaces

namespace ACL
namespace AclLog
A namespace for logging utilities.
namespace ControlDataCommon
namespace IngestUtils
namespace TimeCommon
namespace UUIDUtils
A namespace for UUID utility functions.
namespace spdlog

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.1 - ACL

ACL

Functions

	Name
constexpr uint32_t	makeFourCC(char a, char b, char c, char d) Helper function to create a FourCC code out of four characters.

Functions Documentation

function makeFourCC

constexpr uint32_t makeFourCC(
    char a,
    char b,
    char c,
    char d
)

Helper function to create a FourCC code out of four characters.

Return: The characters a-d encoded as a 32 bit FourCC code.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.2 - AclLog

AclLog

A namespace for logging utilities.

Classes

	Name
class	AclLog::CommandLogFormatter This class is used to format log entries for Rendering Engine commands.
class	AclLog::ThreadNameFormatterFlag
class	AclLog::FileLocationFormatterFlag A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

Types

	Name
enum class	Level { kTrace, kDebug, kInfo, kWarning, kError, kCritical, kOff} Log levels.

Functions

	Name
void	init(const std::string & name) Initialize logging.
void	initCommandLog(const std::string & name) Init the Rendering Engine command log.
void	setLevel(Level level) Set global logging level.
void	logCommand(const std::string & origin, const std::string & command) Log a command to the command log.
AclLog::Level	getLogLevel() Internal helper function for getting the setting for the log level.
size_t	getMaxFileSize() Internal helper function for getting the setting for the maximum size for a log file.
size_t	getMaxLogRotations() Internal helper function for getting the setting for the maximum number of rotated log files.
std::filesystem::path	getLogFileFullPath(const std::string & name) Internal helper function for constructing the full path name for the log file.
std::string	getThreadName()

Types Documentation

enum Level

Enumerator	Value	Description
kTrace
kDebug
kInfo
kWarning
kError
kCritical
kOff

Log levels.

Functions Documentation

function init

void init(
    const std::string & name
)

Initialize logging.

Parameters:

name The name of the component (used for log prefix and filename)

By default two sinks are created. The first sink writes messages to the console. The second sink attempts to create a log file in the path set by the environment variable ACL_LOG_PATH (’/tmp’ if unset). The name of the log file is ’name-.log’. The default logging level is ‘info’ (‘debug’ for debug builds) and can be changed by setting the ACL_LOG_LEVEL environment variable.

function initCommandLog

void initCommandLog(
    const std::string & name
)

Init the Rendering Engine command log.

Parameters:

name The name of the Rendering Engine (used for filename)

function setLevel

void setLevel(
    Level level
)

Set global logging level.

Parameters:

level Logging level to set

function logCommand

void logCommand(
    const std::string & origin,
    const std::string & command
)

Log a command to the command log.

Parameters:

origin The origin of the command to log, usually the UUID of the control panel sending the command
command The command to log

function getLogLevel

AclLog::Level getLogLevel()

Internal helper function for getting the setting for the log level.

Return: The wanted log level fetched from an environment variable if set, or else a default value

function getMaxFileSize

size_t getMaxFileSize()

Internal helper function for getting the setting for the maximum size for a log file.

Return: The wanted maximum size of the log file fetched from an environment variable if set, or else a default value

function getMaxLogRotations

size_t getMaxLogRotations()

Internal helper function for getting the setting for the maximum number of rotated log files.

Return: The wanted number of log files to rotate fetched from an environment variable if set, or else a default value

function getLogFileFullPath

std::filesystem::path getLogFileFullPath(
    const std::string & name
)

Internal helper function for constructing the full path name for the log file.

Parameters:

name The name of the component

Return: The full path to the log file

function getThreadName

inline std::string getThreadName()

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.3 - ControlDataCommon

ControlDataCommon

Classes

	Name
struct	ControlDataCommon::ConnectionStatus Connection status struct containing information about a connection event.
struct	ControlDataCommon::Response A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
struct	ControlDataCommon::StatusMessage A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

Types

	Name
enum class	ConnectionType { CONNECTED, DISCONNECTED} The connection types.

Types Documentation

enum ConnectionType

Enumerator	Value	Description
CONNECTED
DISCONNECTED

The connection types.

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.4 - IngestUtils

IngestUtils

Functions

	Name
bool	isRunningWithRootPrivileges()

Functions Documentation

function isRunningWithRootPrivileges

bool isRunningWithRootPrivileges()

Return: true if this application is executing with root privileges, false otherwise

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.5 - spdlog

spdlog

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.6 - TimeCommon

TimeCommon

Classes

	Name
struct	TimeCommon::TAIStatus
struct	TimeCommon::TimeStructure

Types

	Name
enum class	StratumLevel { UnknownStratum, stratum0, stratum1, stratum2, stratum3, stratum4}

Functions

	Name
uint64_t	getMonotonicClockMicro() Get current time since epoch.
tl::expected< TimeCommon::TAIStatus, std::string >	getStatus() Get TAI status.
int64_t	getTAIMicro() Get current TAI time.
std::string	taiMicroToString(int64_t taiTimestamp) Converts the input TAI timestamp to a human readable string. Timestamp is converted to local time including leap seconds.

Types Documentation

enum StratumLevel

Enumerator	Value	Description
UnknownStratum
stratum0
stratum1
stratum2
stratum3
stratum4

Functions Documentation

function getMonotonicClockMicro

uint64_t getMonotonicClockMicro()

Get current time since epoch.

Return: Return current time since epoch in microseconds

function getStatus

tl::expected< TimeCommon::TAIStatus, std::string > getStatus()

Get TAI status.

Return: Expected with the TAI status if successful or an error string in case something went wrong

function getTAIMicro

int64_t getTAIMicro()

Get current TAI time.

Return: Return current TAI time in microseconds

function taiMicroToString

std::string taiMicroToString(
    int64_t taiTimestamp
)

Converts the input TAI timestamp to a human readable string. Timestamp is converted to local time including leap seconds.

Parameters:

taiTimestamp A TAI timestamp with microseconds resolution

Return: Return a human readable timestamp

Updated on 2024-04-08 at 15:15:27 +0200

1.4.3.7 - UUIDUtils

UUIDUtils

A namespace for UUID utility functions.

Functions

	Name
std::string	generateRandomUUID() Generates a completely randomized UUID string.
bool	isValidUUIDString(const std::string & uuid) Checks if a string is a valid UUID string.

Functions Documentation

function generateRandomUUID

std::string generateRandomUUID()

Generates a completely randomized UUID string.

Return: A random generated UUID string

function isValidUUIDString

bool isValidUUIDString(
    const std::string & uuid
)

Checks if a string is a valid UUID string.

Parameters:

uuid The string to check

Return: True if uuid is a valid UUID string, otherwise false

Updated on 2024-04-08 at 15:15:27 +0200

1.5 - System controller config

Reference for the Agile Live System Controller configuration file

This page describes the configuration settings possible to set via the acl_sc_settings.json file.

Expanded Config name	Config name	Description	Default value
psk	psk	The Pre-shared key used to authorize components to connect to the System Controller. Must be 32 characters long	""
security.salt	salt	Salt string for the generation of tokens and encryption keys	“Some random string”
security.n	n	Parameter for token and encryption generation. N is CPU/memory cost parameter, must be a power of 2, greater than 1. ¹	65536
security.r	r	Parameter for token and encryption generation. R is block size factor. R constrain must satisfy R*P < 2^30. ¹	8
security.p	p	Parameter for token and encryption generation. P is the parallelization parameter. P constrain must satisfy R*P < 2^30, if this is exceeded, an error will be returned ¹	1
security.keylen	keylen	The length of the generated tokens	32
client_auth.enabled	enabled	Switch to enable basic authentication for clients in the REST API	true
client_auth.username	username	The username that will grant access to the REST API	“admin”
client_auth.password	password	Password that will grant access to the REST API	“changeme”
https.enabled	enabled	Switch to enable encryption of the REST API as well as the connections between the System Controller and the connected components	true
https.certificate_file	certificate_file	Path to the certificate file. In `pem` format	""
https.private_key_file	private_key_file	Path to the private key file. In `pem` format	""
logger.level	level	The level that the logging will produce output, available in ascending order: `debug`, `info`, `warn`, `error`	info
logger.file_name_prefix	file_name_prefix	The prefix of the log filename. A unique timecode and “.log” will automatically be appended to this prefix. The prefix can contain both the path and the prefix of the log file.	""
site.port	port	Port on which the service is accessible	8080
site.host	host	Hostname on which the service is accessible	localhost
rate_limit.requests_per_sec	RateLimit.RequestsPerSec	The average number of requests that are handled per second, before requests are queued up. (Number of tokens added to the token bucket per second ²)	300
rate_limit.burst_limit	RateLimit.BurstLimit	The number of requests that can be handled in a short burst before rate limiting kicks in (Maximum number of tokens in the token bucket ²).	10
response_timeout	response_timeout	The maximum time of a request between the System Controller and a component before the request is timed out	5000ms
cors.allowed_origins	allowed_origins	Comma-separated list of origin addresses that are allowed	["*"]
cors.allowed_methods	allowed_methods	Comma-separated list of HTTP methods that the service accepts	[“GET”, “POST”, “PUT”, “PATCH”, “DELETE”]
cors.allowed_headers	allowed_headers	Comma-separated list of headers that are allowed	["*"]
cors.exposed_headers	exposed_headers	Comma-separated list of headers that are allowed for exposure	[""]
cors.allow_credentials	allow_credentials	Allow the xKHR to set credentials cookies	false
cors.max_age	max_age	How long the preflight cache is stored before a new must be made	300
custom_headers.[N].key	key	Custom headers, the key of the header, e.g.: `Cache-Control`	None
custom_headers.[N].value	value	Custom headers, the value to the key of the header, e.g.: `no-cache`	None
allow_any_version	allow_any_version	Allow components of any version to connect. When set to false, components with another major version than the System Controller will be rejected	false

2 - Agile Live 6.0.0 developer reference

Agile Live 6.0.0 developer reference

2.1 - REST API v2

Reference for the Agile Live System Controller REST API

The following is a rendering of the OpenAPI for the Agile Live System Controller using Swagger. It does not have a backend server, so it cannot be run interactively.

This API is available from the server at the base URL /api/v2.

2.2 - Agile Live Rendering Engine command documentation

Reference for the Agile Live Rendering Engine commands

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

Background

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

The video mixer data path

There are eight different node types used in this mixer.

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 Select node simply forwards one of the available sources to its output.
The Transform node takes one input stream and transforms it (scaling and translating) to one output stream.
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. This is known as “key & fill” in broadcasting.
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 Chroma Key node takes one input stream, and by setting appropriate parameters for the keying, it will remove areas with the key color from the incoming video stream both affecting the alpha and color channels
The Fade to black node takes one input stream, which it can fade to or from black gradually, and then outputs that stream.
The Output node has one input stream and will output that stream out from the video mixer, back to the Rendering Engine

There are six different flows into this mixer. There is the one starting with the Transition node, which represents the main program that is being produced. Overlaying on top of that is one key+fill graphics overlay (starting with an Alpha Combine node which can combine two video inputs with key form one and fill from another, or both from the same source), then there is a chroma key overlay, which can be used to add green screen effects (Starting with a Select node), then there are two instances of picture-in-picture flows (also starting with select nodes) and on top of that another graphics overlay, called HTML graphics in the illustration, but which can be used with any source where the key and fill comes from the same source. The overlay flows are inserted into the main program using Alpha over nodes.

Each video command in the Rendering Engine command protocol targets one of these nodes.

Transitions

The main flow of the video mixer can be controlled with the following commands:

transition cut <input_slot> - Cut (hot punch) the program output to the given input slot. This won’t affect the preview output.
transition preview <input_slot> - Preview the given input slot. This won’t affect the program output.
transition cut - Cut between the current program and preview outputs, effectively swapping their place.
transition panic <input_slot> - Cut (hot punch) both the preview and program output to the given input slot.

transition type <type> - Set the transition type to use for transitions hereafter. Valid modes are:
- fade - Fade (mix) from one source to the next
- wipe_left - Wipe from one source to the next, wipe going from right side of the screen to the left
- wipe_right - Wipe from one source to the next, wipe going from left side of the screen to the right
transition auto <duration_ms> - Perform an automatic transition from the current program output to the current preview output, lasting for <duration_ms> milliseconds. The currently set transition type is used.
transition factor <factor> - Manually set the position/factor of the transition. <factor> should be between 0.0 and 1.0, where 0.0 is the value before the transition starts and 1.0 is the end of the transition. Note that setting this value to 1.0 will effectively swap place of program and preview output, resetting the transition factor to 0.0 internally. Control panels using this command must take this into consideration to not cause a sudden jump in the transition once the physical control is moved again. Sending this command will interrupt any ongoing automatic transition.

Key and fill

The key and fill graphics flow will be inserted before the picture-in-picture flows, and will therefore be rendered under them. The graphics flow 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.

Picture-in-Picture

The two picture-in-picture boxes can be controlled with these commands:

pip1_select cut <input_slot> - Choose which input slot to forward. Changing looks like a cut.
pip1_transform scale <factor> - Set the scale of the picture-in-picture box, relative the original size. Parameter factor must be > 0. Default is 1.0.
pip1_transform x <position> - Set the X offset of the top left corner of the picture-in-picture box, relative the top left corner of the frame. Position is measured in percent of frame width, where 0.0 is the left side of the frame and 1.0 is the right side of the frame. Values outside of the range 0, 1 are valid. Default is 0.0.
pip1_transform y <position> - Set the Y offset of the top left corner of the picture-in-picture box, relative the top left corner of the frame. Position is measured in percent of frame height, where 0.0 is the top of the frame and 1.0 is the bottom of the frame. Values outside of the range 0, 1 are valid. Default is 0.0.
pip1_alpha_over factor <factor> - Manually set the transparency multiplier for the picture-in-picture 1 Alpha over node. The value <factor> should be a float between 0.0 and 1.0, where 0.0 means that the picture-in-picture box is completely invisible and 1.0 means that the box is fully visible. Default is 0.0.
pip1_alpha_over fade to <duration_ms> - Start an automatic fade from the current factor to a fully visible picture-in-picture box over the duration of <duration_ms> milliseconds.
pip1_alpha_over fade from <duration_ms> - Start an automatic fade from the current factor to a fully invisible picture-in-picture box over the duration of <duration_ms> milliseconds.

For the second picture-in-picture flow, replace pip1 with pip2.

Chroma Key

The nodes of the chroma key branch of the graph can be controlled with these commands:

chroma_key_select cut <input_slot> - Choose which input slot to forward. Changing looks like a cut.
chroma_key r <value> - Set the red component of the chroma key color. Should be a float between 0.0 and 1.0.
chroma_key g <value> - Set the green component of the chroma key color. Should be a float between 0.0 and 1.0.
chroma_key b <value> - Set the blue component of the chroma key color. Should be a float between 0.0 and 1.0.
chroma_key distance <value> - Set the distance parameter, ranging from 0.0 to 1.0, telling how far from the key color is also considered a part of the key. Larger values will result in more colors being included, 0.0 means only the exact key color is considered.
chroma_key falloff <value> - Set the falloff parameter, ranging from 0.0 to 1.0, which makes edges smoother. A lower value means harder edges between the key color and the parts to keep, a higher value means a more smooth falloff between removed and kept parts.
chroma_key spill <value> - Set the color spill reduction parameter, ranging from 0.0 to 1.0, which will desaturate the key color in the parts of the image that are left. Useful for hiding green rims around objects in from of a green screen etc. 0.0 means off and a higher value means more colors further away from the chroma key color will be desaturated.
chroma_key color_picker <x_factor> <y_factor> <square_size> - Set the chroma key by sampling the pixels covered by the square area of size square_size x square_size. The position x,y is set by <x_factor> * width of video and <y_factor> * height of video. <x_factor> & <y_factor> should be a float between 0.0 and 1.0. The <square_size> should be an integer > 0.0.
chroma_key alpha_as_video <value> - Instead of writing an alpha mask, set the alpha value as the RGB value, creating a grayscale image of the mask. Value should be 0.0 or 1.0.
chroma_key show_key_color <value> - Draw a 100x100 box in upper left corner with the current chroma key (RGB) value. Value should be 0.0 or 1.
chroma_key show_color_picker <value> - Draw a pink border around the area where the color picker will sample a new chroma key. Value should be 0.0 or 1.
chroma_key_transform scale <factor> - Set the scale of the chroma key output, relative the original size. Parameter factor must be > 0.0. Default is 1.0.
chroma_key_transform x <position> - Set the X offset of the top left corner of the chroma key output, relative the top left corner of the frame. Position is measured in percent of frame width, where 0.0 is the left side of the frame and 1.0 is the right side of the frame. Values outside of the range 0.0, 1.0 are valid. Default is 0.0.
chroma_key_transform y <position> - Set the Y offset of the top left corner of the chroma key output, relative the top left corner of the frame. Position is measured in percent of frame height, where 0.0 is the top of the frame and 1.0 is the bottom of the frame. Values outside of the range 0.0, 1.0 are valid. Default is 0.0.
chroma_key_alpha_over factor <factor> - Manually set the transparency multiplier for the chroma key Alpha over node. The value <factor> should be a float between 0.0 and 1.0, where 0.0 means that the chroma key output is completely invisible and 1.0 means that the chroma key output is fully visible. Default is 0.0.
chroma_key_alpha_over fade to <duration_ms> - Start an automatic fade from the current factor to a fully visible chroma key output over the duration of <duration_ms> milliseconds.
chroma_key_alpha_over fade from <duration_ms> - Start an automatic fade from the current factor to a fully invisible chroma key output over the duration of <duration_ms> milliseconds.

Graphics overlay (HTML)

The overlay graphics flow, marked with HTML in the illustration. This will be inserted on top of both the key and fill and picture-in-picture. It can be controlled with these commands:

html_select cut <input_slot> - Choose which input slot to use for the graphics. It must contain both fill and key (such as the HTML graphics), otherwise, no parts of the layer will be transparent. Changing looks like a cut.
html_alpha_over factor <factor> - Manually set the transparency multiplier for the graphics overlay Alpha over node. The value <factor> should be a float between 0.0 and 1.0, where 0.0 means that the graphics is completely invisible and 1.0 means that it is fully visible. Default is 0.0.
html_alpha_over fade to <duration_ms> - Start an automatic fade from the current factor to a fully visible graphics over the duration of <duration_ms> milliseconds.
html_alpha_over fade from <duration_ms> - Start an automatic fade from the current factor to a fully invisible graphics over the duration of <duration_ms> milliseconds.

Fade to black

The fade to black node can be controlled via the following 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 Router commands

The same audio router is used to route specific audio channels from an input slot of the Rendering Engine to an input channel strip on the audio mixer. By default, it has no audio routes set up. The router can be controlled with the following commands:

audio map <input_slot> <channel> mono <input_strip> - Map the <channel> from input slot <input_slot> as a mono channel into input strip <input_strip> of the audio mixer
audio map <input_slot> <left_channel> stereo <input_strip> - Map the <left_channel> and <left_channel> + 1 from input slot <input_slot> as a stereo pair into input strip <input_strip> of the audio mixer ’ audio map reset <input_strip> - Remove the current mapping from <input_strip> of the audio mixer.

Audio commands

The audio mixer and audio router have the following data path:

Audio mixer block diagram

To control the pre-gain of each input strip use:

audio gain <input_strip> <level_dB> - Set the pre-gain level of a specific input in dB. Parameter <level> should be a floating point number. Default is 0.0.

To control the low-pass filter of each input strip use:

audio lpf <input_strip> freq <value> - Set the cutoff frequency for the low-pass filter in an input strip. <value> is the frequency in Hz as a floating point number. The frequency range is 20 Hz to 20 kHz. Setting a value of 20 kHz or higher will bypass the filter.
audio lpf <input_strip> q <value> - Set the q-value for the low-pass filter in an input strip. The q-value controls the steepness of cutoff curve with a higher value being a steeper slope. The value is a floating point number ranging from 0.4 to 6.0. The default value is 0.7.

To control the high-pass filter of each input strip use:

audio hpf <input_strip> freq <value> - Set the cutoff frequency for the high-pass filter in an input strip. <value> is the frequency in Hz as a floating point number. The frequency range is 20 Hz to 20 kHz. Setting a value of 20 Hz or lower will bypass the filter.
audio hpf <input_strip> q <value> - Set the q-value for the high-pass filter in an input strip. The q-value controls the steepness of cutoff curve with a higher value being a steeper slope. The value is a floating point number ranging from 0.4 to 6.0. The default value is 0.7.

To control the parametric equalizer of each input strip use (the equalizer has three bands):

audio eq <input_strip> <band> freq <value> - Set the frequency of a specific band in the parametric equalizer. Here <band> is a zero based index of the band, where 0 is the first band with the lowest frequency. <value> is a floating point number with the frequency in Hz
audio eq <input_strip> <band> gain <value> - Set the gain of a specific band in the parametric equalizer. Here <band> is a zero based index of the band, where 0 is the first band with the lowest frequency. <value> is a floating point number with the gain in dB.
audio eq <input_strip> <band> q <value> - Set the q-value of a specific band in the parametric equalizer to shape the falloff of the band. Here <band> is a zero based index of the band, where 0 is the first band with the lowest frequency. <value> is a floating point number with the q-value where a higher value means a more pointy curve. Default value is 0.7.
audio eq <input_strip> <band> type <type> - Set the type of falloff to use for a specific band in the parametric equalizer. Here <band> is a zero based index of the band, where 0 is the first band with the lowest frequency. <type> is either of low, band or high, where low and high is a low and high shelf filter and band is a band pass filter. By default, the first band is low shelf, the last band is high shelf and any bands inbetween are band pass.

To control the panning of each input strip use:

audio pan <input_strip> <factor> - Pan the mono or stereo input of an input strip to the left or right. The range of <factor> is between -1.0 and +1.0, where 0.0 means center (no panning), negative values means more to the left and positive value more to the right. Values outside this range will be clamped. A value of +/- 1.0 means that there will only be audio in the left/right channel.

To control the dynamic range compressor of each input strip use:

audio comp <input_strip> threshold <value> - Set the threshold for activation of the compressor. The threshold is a negative dB value ranging from -30 dB to 0 dB. The volume of audio which is above the threshold value will be reduced (compressed). The default value is 0 dB, i.e. only compression if the audio signal is overloaded.
audio comp <input_strip> ratio <value> - Set the compression ratio for audio exceeding the loudness threshold. The value is the numerator in the compression ratio <value>:1. For instance, if the value is set to 4, the compression ratio is 4:1 and volume overshoot above the threshold will be scaled down to 25 %. The ratio numerator is a floating point number in the range from 1.0 to 24.0, with 4.0 as the default value.
audio comp <input_strip> knee <value> - Set the width of the soft knee in decibels. Instead of simply turning the compression completely on or off at the threshold, the knee defines a volume range in which the compression ratio follows a curve, the “knee”. The knee is a floating point number between 0 dB and 30 dB, with a default value of 2.5 dB.
audio comp <input_strip> attack <value> - Set the attack time of the compressor in milliseconds. The attack time determines how long it takes to reach the full compression after the threshold has been exceeded. The value is a floating point number in the range from 0.1 ms to 120 ms. The default value is 50 ms.
audio comp <input_strip> release <value> - Set the release time of the compressor in milliseconds. The release time determines how long it takes to return to zero compression when the volume is below the compression threshold. The value is a floating point number in the range from 10 ms to 1000 ms. The default value is 200 ms.
audio comp <input_strip> gain <value> - Set the make-up gain i decibels. Since the compression filter lowers the volume of louder audio sections it can be desirable to increase the gain after the filtering. The gain value increases the audio volume with the specified number of decibels. The value is a floating point number in the range from 0 dB to 24 dB. The default value is 0 dB.

To control the volume faders and master volume faders use:

audio volume <input_strip> <output> <level> - Set the volume level of a specific input in proportion to its original strength for a given output. Parameter <level> should be a floating point number, where 0.0 means that the input slot is not mixed into the output at all 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.
audio mastervolume <output> <level> - Set the master volume level of an 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. Default is 1.0.

HTML rendering

html create <input_slot> <width> <height> - Create a new HTML browser instance with the canvas size of width x height pixels and output the rendered frames to the given input slot
html close <input_slot> - Close the HTML browser instance on the given input slot
html load <input_slot> <url> - Load a new URL in the HTML browser on the given input slot
html execute <input_slot> <java script> - Execute JavaScript in the HTML browser on the given input slot. The JavaScript snippet might span over multiple lines and may contain spaces.

Media player

media create <input_slot> <filename> - Create a new media player instance with the given media file and output the rendered frames to the given input slot.
media load <input_slot> <filename> - Load another file into an existing media player on the given input slot. This will reset the start, duration and looping parameters of that media player.
media close <input_slot> - Close the media player instance on the given input slot
media play <input_slot> - Start/resume playing the currently loaded media file in the media player on the given input slot
media pause <input_slot> - Pause the media player on the given input slot
media seek <input_slot> <time_ms> - Seek the media player on the given input slot to a time point time_ms milliseconds from the start of the media file and pause the playback at the first frame. Use media play <input_slot> to resume the playback
media set_start <input_slot> <start_time_ms> - Set the start time of the looping section of the media player on the given input slot to a time point start_time_ms milliseconds from the start of the media file. It will still be possible to seek before this time point and play the video from there.
media set_duration <input_slot> <duration_ms> - Set the duration of the playing/looping section of the media player on the given input slot to duration_ms milliseconds from the start_time_ms of the media file. The duration will be clamped in case it spans past the end of the media file. A running media player will either stop at this point, or loop the video depending on the state of the looping parameter
media set_looping <input_slot> <true/false> - Set if the media should loop from the start time when the media player on the given input slot hits either the end of the looping section defined by the start time and duration, or the end of the media file. If set to false, the media player will stop at the end of the section or at the end of the file instead of looping it from the start point.

2.3 - C++ SDK

Agile Content Live C++ SDK reference

Agile Content Live C++ SDK reference.

2.3.1 - Classes

Classes

namespace ACL
namespace AclLog
A namespace for logging utilities.
- class CommandLogFormatter
  This class is used to format log entries for Rendering Engine commands.
- class FileLocationFormatterFlag
  A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.
- class ThreadNameFormatterFlag
struct AlignedAudioFrame
AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.
struct AlignedFrame
A frame of aligned data that is passed to the rendering engine from the MediaReceiver. A DataFrame contains a time stamped frame of media, which might be video, audio and auxiliary data such as subtitles. A single DataFrame can contain one or multiple types of media. Which media types are included can be probed by nullptr-checking/size checking the data members. The struct has ownership of all data pointers included. The struct includes all logic for freeing the resources held by this struct and the user should therefore just make sure the struct itself is deallocated to ensure all resources are freed.
namespace ControlDataCommon
- struct ConnectionStatus
  Connection status struct containing information about a connection event.
- struct Response
  A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
- struct StatusMessage
  A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.
class ControlDataReceiver
A ControlDataReceiver can receive messages from a sender or another ControlDataReceiver using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a receiving or listening side, as well as a sending side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests.
- struct IncomingRequest
  An incoming request to this ControlDataReceiver.
- struct ReceiverResponse
  A response message to a request.
- struct Settings
  Settings for a ControlDataReceiver.
class ControlDataSender
A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.
- struct Settings
  Settings for a ControlDataSender.
class DeviceMemory
RAII class for a CUDA memory buffer.
class ISystemControllerInterface
An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server. An ISystemControllerInterface can have a parent-child relationship with other interfaces, where the children are aware of which their parent interface is. This is useful for components that provides extra features for another component, but where the components are still to be considered as two separate entities with separate connections to the System controller.
- struct Callbacks
  A struct containing the callbacks that needs to be registered by the component using this interface.
- struct Response
  A response to a request, consists of a status code and an (optional) parameters JSON object.
class IngestApplication
- struct Settings
namespace IngestUtils
class MediaReceiver
A MediaReceiver contains the logic for receiving, decoding and aligning incoming media sources from the Ingests. The aligned data is then delivered to the Rendering Engine which is also responsible for setting up the MediaReceiver. The MediaReceiver has a builtin multi view generator, which can create output streams containing composited subsets of the incoming video sources. This class is controlled using an ISystemControllerInterface provided when starting it.
- struct NewStreamParameters
  A struct containing information on the format of an incoming stream.
- struct Settings
  Settings for a MediaReceiver.
class MediaStreamer
MediaStreamer is a class that can take a single stream of uncompressed video and/or audio frames and encode and output it in some way to some interface. This interface can either be a stream to a network or writing down the data to a file on the hard drive. This class is configured from two interfaces. The input configuration (input video resolution, frame rate, pixel format, number of audio channels…) is made through this C++ API. The output stream is then started from the System Controller. Any of these configurations can be made first. The actual stream to output will start once the first call to.
- struct Configuration
  The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.
class PipelineSystemControllerInterfaceFactory
class SystemControllerConnection
An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.
- struct Settings
  Settings for a SystemControllerConnection.
namespace TimeCommon
- struct TAIStatus
- struct TimeStructure
namespace UUIDUtils
A namespace for UUID utility functions.
namespace spdlog

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.1 - AclLog::CommandLogFormatter

AclLog::CommandLogFormatter

This class is used to format log entries for Rendering Engine commands.

#include <AclLog.h>

Inherits from spdlog::formatter

Public Functions

	Name
	CommandLogFormatter()
void	format(const spdlog::details::log_msg & msg, spdlog::memory_buf_t & dest) override
std::unique_ptr< spdlog::formatter >	clone() const override

Public Functions Documentation

function CommandLogFormatter

CommandLogFormatter()

function format

void format(
    const spdlog::details::log_msg & msg,
    spdlog::memory_buf_t & dest
) override

function clone

std::unique_ptr< spdlog::formatter > clone() const override

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.2 - AclLog::FileLocationFormatterFlag

AclLog::FileLocationFormatterFlag

A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

#include <AclLog.h>

Inherits from spdlog::custom_flag_formatter

Public Functions

	Name
void	format(const spdlog::details::log_msg & msg, const std::tm & , spdlog::memory_buf_t & dest) override
std::unique_ptr< custom_flag_formatter >	clone() const override

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & msg,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.3 - AclLog::ThreadNameFormatterFlag

AclLog::ThreadNameFormatterFlag

Inherits from spdlog::custom_flag_formatter

Public Functions

	Name
void	format(const spdlog::details::log_msg & , const std::tm & , spdlog::memory_buf_t & dest) override
std::unique_ptr< custom_flag_formatter >	clone() const override

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & ,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.4 - AlignedAudioFrame

AlignedAudioFrame

AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.

#include <AlignedFrame.h>

Public Attributes

	Name
std::vector< float >	mSamples
uint8_t	mNumberOfChannels
uint32_t	mNumberOfSamplesPerChannel

Public Attributes Documentation

variable mSamples

std::vector< float > mSamples;

variable mNumberOfChannels

uint8_t mNumberOfChannels = 0;

variable mNumberOfSamplesPerChannel

uint32_t mNumberOfSamplesPerChannel = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.5 - AlignedFrame

AlignedFrame

#include <AlignedFrame.h>

Public Functions

	Name
	AlignedFrame() =default
	~AlignedFrame() =default
	AlignedFrame(AlignedFrame const & ) =delete
AlignedFrame &	operator=(AlignedFrame const & ) =delete
std::shared_ptr< AlignedFrame >	makeShallowCopy() const Make a shallow copy of this AlignedFrame (video and audio pointers will point to the same video and audio memory buffers as in the frame copied from)

Public Attributes

	Name
int64_t	mCaptureTimestamp
int64_t	mRenderingTimestamp
std::shared_ptr< DeviceMemory >	mVideoFrame
PixelFormat	mPixelFormat
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mWidth
uint32_t	mHeight
AlignedAudioFramePtr	mAudioFrame
uint32_t	mAudioSamplingFrequency

Public Functions Documentation

function AlignedFrame

AlignedFrame() =default

function ~AlignedFrame

~AlignedFrame() =default

function AlignedFrame

AlignedFrame(
    AlignedFrame const & 
) =delete

function operator=

AlignedFrame & operator=(
    AlignedFrame const & 
) =delete

function makeShallowCopy

std::shared_ptr< AlignedFrame > makeShallowCopy() const

Make a shallow copy of this AlignedFrame (video and audio pointers will point to the same video and audio memory buffers as in the frame copied from)

Return: A pointer to a new frame, which is a shallow copy of the old one, pointing to the same video and audio memory buffers

Public Attributes Documentation

variable mCaptureTimestamp

int64_t mCaptureTimestamp = 0;

The TAI timestamp in microseconds since the TAI epoch when this frame was captured by the ingest

variable mRenderingTimestamp

int64_t mRenderingTimestamp = 0;

The TAI timestamp in microseconds since the TAI epoch when this frame should be delivered to the rendering engine

variable mVideoFrame

std::shared_ptr< DeviceMemory > mVideoFrame = nullptr;

variable mPixelFormat

PixelFormat mPixelFormat = PixelFormat::kUnknown;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 0;

variable mWidth

uint32_t mWidth = 0;

variable mHeight

uint32_t mHeight = 0;

variable mAudioFrame

AlignedAudioFramePtr mAudioFrame = nullptr;

variable mAudioSamplingFrequency

uint32_t mAudioSamplingFrequency = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.6 - ControlDataCommon::ConnectionStatus

ControlDataCommon::ConnectionStatus

Connection status struct containing information about a connection event.

#include <ControlDataCommon.h>

Public Functions

	Name
	ConnectionStatus() =default
	ConnectionStatus(ConnectionType mConnectionType, const std::string & mIp, uint16_t mPort)

Public Attributes

	Name
ConnectionType	mConnectionType
std::string	mIP
uint16_t	mPort

Public Functions Documentation

function ConnectionStatus

ConnectionStatus() =default

function ConnectionStatus

inline ConnectionStatus(
    ConnectionType mConnectionType,
    const std::string & mIp,
    uint16_t mPort
)

Public Attributes Documentation

variable mConnectionType

ConnectionType mConnectionType = ConnectionType::DISCONNECTED;

variable mIP

std::string mIP;

variable mPort

uint16_t mPort = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.7 - ControlDataCommon::Response

ControlDataCommon::Response

A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.

#include <ControlDataCommon.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage
uint64_t	mRequestId The actual message.
std::string	mFromUUID The ID of the request this is a response to.

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

variable mRequestId

uint64_t mRequestId = 0;

The actual message.

variable mFromUUID

std::string mFromUUID;

The ID of the request this is a response to.

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.8 - ControlDataCommon::StatusMessage

ControlDataCommon::StatusMessage

A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

#include <ControlDataCommon.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage
std::string	mFromUUID The actual message.

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

variable mFromUUID

std::string mFromUUID;

The actual message.

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.9 - ControlDataReceiver

ControlDataReceiver

A ControlDataReceiver can receive messages from a sender or another ControlDataReceiver using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a receiving or listening side, as well as a sending side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests. More…

#include <ControlDataReceiver.h>

Public Classes

	Name
struct	IncomingRequest An incoming request to this ControlDataReceiver.
struct	ReceiverResponse A response message to a request.
struct	Settings Settings for a ControlDataReceiver.

Public Functions

	Name
	ControlDataReceiver() Default constructor, creates an empty object.
	~ControlDataReceiver() Destructor. Will disconnect from the connected receivers and close the System controller connection.
bool	configure(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, const Settings & settings) Configure this ControlDataReceiver and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.
bool	sendStatusMessageToSender(const std::vector< uint8_t > & message) Send a status message to the (directly or indirectly) connected ControlDataSender. In case this ControlDataReceiver has another ControlDataReceiver as sender, that receiver will forward the status message to the sender.
bool	sendRequestToReceivers(const std::vector< uint8_t > & request, uint64_t & requestId) Send a request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.
bool	sendMultiRequestToReceivers(const std::vector< std::vector< uint8_t » & request, uint64_t & requestId) Send a multi-message request to the connected ControlDataReceivers asynchronously. This request will only be sent to ControlDataReceivers on the sending side of this receiver. In case a receiver is located between this ControlDataReceiver and the sender, neither of those will see this request. The response will be sent to the response callback asynchronously.
	ControlDataReceiver(ControlDataReceiver const & ) =delete
ControlDataReceiver &	operator=(ControlDataReceiver const & ) =delete
std::string	getVersion() Get application version.
std::string	getBuildInfo() Get application build information.

Detailed Description

class ControlDataReceiver;

A ControlDataReceiver can send status messages back to the sender. In case of chained receivers, the message will be forwarded back to the sender. A user of the ControlDataReceiver can register callbacks to receive requests and status messages. There is also an optional “preview” callback that is useful in case the incoming messages are delayed (have a delay > 0). This callback will then be called as soon as the request message arrives, to allow the user to prepare for when the actual delayed request callback is called.

Public Functions Documentation

function ControlDataReceiver

ControlDataReceiver()

Default constructor, creates an empty object.

function ~ControlDataReceiver

~ControlDataReceiver()

Destructor. Will disconnect from the connected receivers and close the System controller connection.

function configure

bool configure(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
)

Configure this ControlDataReceiver and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.

Parameters:

controllerInterface The interface to the System controller, used for communicating with this ControlDataReceiver
settings The settings to use for this ControlDataReceiver

Return: True on success, false otherwise

function sendStatusMessageToSender

bool sendStatusMessageToSender(
    const std::vector< uint8_t > & message
)

Parameters:

message The status message

Return: True in case the message was sent successfully, false otherwise.

function sendRequestToReceivers

bool sendRequestToReceivers(
    const std::vector< uint8_t > & request,
    uint64_t & requestId
)

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async response.

Return: True if the request was successfully sent, false otherwise

function sendMultiRequestToReceivers

bool sendMultiRequestToReceivers(
    const std::vector< std::vector< uint8_t >> & request,
    uint64_t & requestId
)

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async response.

Return: True if the request was successfully sent, false otherwise

function ControlDataReceiver

ControlDataReceiver(
    ControlDataReceiver const & 
) =delete

function operator=

ControlDataReceiver & operator=(
    ControlDataReceiver const & 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “1.0.0”

function getBuildInfo

static std::string getBuildInfo()

Get application build information.

Return: a string with the current build information such as git hashes of all direct dependencies

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.10 - ControlDataReceiver::IncomingRequest

ControlDataReceiver::IncomingRequest

An incoming request to this ControlDataReceiver.

#include <ControlDataReceiver.h>

Public Attributes

	Name
std::vector< std::vector< uint8_t > >	mMessages
std::string	mSenderUUID The actual messages.
std::string	mRequesterUUID UUID of the sender/forwarder that sent the request to this ControlDataReceiver.
uint64_t	mRequestID UUID of the requester (the original sender, creating the request)
int64_t	mSenderTimestampUs The requester’s unique id of this request.
int64_t	mDeliveryTimestampUs The TAI timestamp when this message was sent from the sender/forwarder in micro sec since TAI epoch.

Public Attributes Documentation

variable mMessages

std::vector< std::vector< uint8_t > > mMessages;

variable mSenderUUID

std::string mSenderUUID;

The actual messages.

variable mRequesterUUID

std::string mRequesterUUID;

UUID of the sender/forwarder that sent the request to this ControlDataReceiver.

variable mRequestID

uint64_t mRequestID = 0;

UUID of the requester (the original sender, creating the request)

variable mSenderTimestampUs

int64_t mSenderTimestampUs =
            0;

The requester’s unique id of this request.

variable mDeliveryTimestampUs

int64_t mDeliveryTimestampUs =
            0;

The TAI timestamp when this message was sent from the sender/forwarder in micro sec since TAI epoch.

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.11 - ControlDataReceiver::ReceiverResponse

ControlDataReceiver::ReceiverResponse

A response message to a request.

#include <ControlDataReceiver.h>

Public Attributes

	Name
std::vector< uint8_t >	mMessage

Public Attributes Documentation

variable mMessage

std::vector< uint8_t > mMessage;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.12 - ControlDataReceiver::Settings

ControlDataReceiver::Settings

Settings for a ControlDataReceiver.

#include <ControlDataReceiver.h>

Public Attributes

	Name
std::function< void(const IncomingRequest &)>	mPreviewIncomingRequestCallback
std::function< ReceiverResponse(const IncomingRequest &)>	mIncomingRequestCallback
std::function< void(const ControlDataCommon::ConnectionStatus &)>	mConnectionStatusCallback
std::function< void(const ControlDataCommon::Response &)>	mResponseCallback Callback for connection events.

Public Attributes Documentation

variable mPreviewIncomingRequestCallback

std::function< void(const IncomingRequest &)> mPreviewIncomingRequestCallback;

Callback called as soon as this ControlDataReceiver gets the request, as a “preview” of what requests will be delievered.

variable mIncomingRequestCallback

std::function< ReceiverResponse(const IncomingRequest &)> mIncomingRequestCallback;

The actual callback used when this ControlDataReceiver gets a request and wants a response back. This callback will delay and deliver the request according to this receiver’s configured delay.

variable mConnectionStatusCallback

std::function< void(const ControlDataCommon::ConnectionStatus &)> mConnectionStatusCallback;

variable mResponseCallback

std::function< void(const ControlDataCommon::Response &)> mResponseCallback;

Callback for connection events.

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.13 - ControlDataSender

ControlDataSender

#include <ControlDataSender.h>

Public Classes

	Name
struct	Settings Settings for a ControlDataSender.

Public Functions

	Name
	ControlDataSender() Default constructor, creates an empty object.
	~ControlDataSender() Destructor. Will disconnect from the connected receivers and close the System controller connection.
bool	configure(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, const Settings & settings) Configure this ControlDataSender and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.
bool	sendRequestToReceivers(const std::vector< uint8_t > & request, uint64_t & requestId) Send a request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.
bool	sendMultiRequestToReceivers(const std::vector< std::vector< uint8_t » & request, uint64_t & requestId) Send a multi-message request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.
	ControlDataSender(ControlDataSender const & ) =delete
ControlDataSender &	operator=(ControlDataSender const & ) =delete
std::string	getVersion() Get application version.
std::string	getGitRevision() Get git revision which application was built on.
std::string	getBuildInfo() Get application build information.

Public Functions Documentation

function ControlDataSender

ControlDataSender()

Default constructor, creates an empty object.

function ~ControlDataSender

~ControlDataSender()

Destructor. Will disconnect from the connected receivers and close the System controller connection.

function configure

bool configure(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
)

Parameters:

controllerInterface The interface to the System controller, used for communicating with this ControlDataSender
settings The Settings to use for this ControlDataSender

Return: True on success, false otherwise

function sendRequestToReceivers

bool sendRequestToReceivers(
    const std::vector< uint8_t > & request,
    uint64_t & requestId
)

Send a request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async responses.

Return: True if the request was successfully sent, false otherwise

function sendMultiRequestToReceivers

bool sendMultiRequestToReceivers(
    const std::vector< std::vector< uint8_t >> & request,
    uint64_t & requestId
)

Send a multi-message request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.

Parameters:

request The request message
requestId The unique identifier of this request. Used to identify the async responses.

Return: True if the request was successfully sent, false otherwise

function ControlDataSender

ControlDataSender(
    ControlDataSender const & 
) =delete

function operator=

ControlDataSender & operator=(
    ControlDataSender const & 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “1.0.0”

function getGitRevision

static std::string getGitRevision()

Get git revision which application was built on.

Return: a string with the current git revision, e.g. “v2.1.0-231-gcd012ab”, followed by “-dirty” in case there are changes made to the Git repo.

function getBuildInfo

static std::string getBuildInfo()

Get application build information.

Return: a string with the current build information such as git hashes of all direct dependencies

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.14 - ControlDataSender::Settings

ControlDataSender::Settings

Settings for a ControlDataSender.

#include <ControlDataSender.h>

Public Attributes

	Name
std::function< void(const ControlDataCommon::ConnectionStatus &)>	mConnectionStatusCallback
std::function< void(const ControlDataCommon::Response &)>	mResponseCallback
std::function< void(const ControlDataCommon::StatusMessage &)>	mStatusMessageCallback

Public Attributes Documentation

variable mConnectionStatusCallback

std::function< void(const ControlDataCommon::ConnectionStatus &)> mConnectionStatusCallback;

variable mResponseCallback

std::function< void(const ControlDataCommon::Response &)> mResponseCallback;

variable mStatusMessageCallback

std::function< void(const ControlDataCommon::StatusMessage &)> mStatusMessageCallback;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.15 - DeviceMemory

DeviceMemory

RAII class for a CUDA memory buffer.

#include <DeviceMemory.h>

Public Functions

	Name
	DeviceMemory() =default Default constructor, creates an empty object, without allocating any memory on the device.
	DeviceMemory(size_t numberOfBytes) Constructor allocating the required number of bytes.
	DeviceMemory(size_t numberOfBytes, cudaStream_t cudaStream) Constructor allocating the required number of bytes by making an async allocation. The allocation will be put in the given CUDA stream.
	DeviceMemory(void * deviceMemory) Constructor taking ownership of an already allocated CUDA memory pointer. This class will free the pointer once it goes out of scope.
bool	allocateMemory(size_t numberOfBytes) Allocates device memory. The memory allocated will automatically be freed by the destructor.
bool	allocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Allocates device memory. The memory allocated will automatically be freed by the destructor.
bool	reallocateMemory(size_t numberOfBytes) Reallocates device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.
bool	reallocateMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Asynchronously reallocate device memory. Already existing memory allocation will be freed before the new allocation is made. In case this DeviceMemory has no earlier memory allocation, this method will just allocate new CUDA memory and return a success status.
bool	allocateAndResetMemory(size_t numberOfBytes) Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.
bool	allocateAndResetMemoryAsync(size_t numberOfBytes, cudaStream_t cudaStream) Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.
bool	freeMemory() Free the device memory held by this class. Calling this when no memory is allocated is a no-op.
bool	freeMemoryAsync(cudaStream_t cudaStream) Deallocate memory asynchronously, in a given CUDA stream. Calling this when no memory is allocated is a no-op.
void	setFreeingCudaStream(cudaStream_t cudaStream) Set which CUDA stream to use for freeing this DeviceMemory. In case the DeviceMemory already holds a CUDA stream to use for freeing the memory, this will be overwritten.
	~DeviceMemory() Destructor, frees the internal CUDA memory.
template T *	getDevicePointer() const
size_t	getSize() const
	DeviceMemory(DeviceMemory && other)
DeviceMemory &	operator=(DeviceMemory && other)
void	swap(DeviceMemory & other)
	DeviceMemory(DeviceMemory const & ) =delete DeviceMemory is not copyable.
DeviceMemory	operator=(DeviceMemory const & ) =delete

Public Functions Documentation

function DeviceMemory

DeviceMemory() =default

Default constructor, creates an empty object, without allocating any memory on the device.

function DeviceMemory

explicit DeviceMemory(
    size_t numberOfBytes
)

Constructor allocating the required number of bytes.

Parameters:

numberOfBytes Number of bytes to allocate

Exceptions:

std::runtime_error In case the allocation failed

function DeviceMemory

explicit DeviceMemory(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Constructor allocating the required number of bytes by making an async allocation. The allocation will be put in the given CUDA stream.

Parameters:

size Number of bytes to allocate
cudaStream The CUDA stream to put the async allocation in. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Exceptions:

std::runtime_error In case the async allocation failed to be put in queue.

Note:

The method will return as soon as the allocation is put in queue in the CUDA stream, i.e. before the actual allocation is made. Using this DeviceMemory is only valid as long as it is used in the same CUDA stream, or in case another stream is used, only if that stream is synchronized first with respect to cudaStream.
In case the

function DeviceMemory

explicit DeviceMemory(
    void * deviceMemory
)

Constructor taking ownership of an already allocated CUDA memory pointer. This class will free the pointer once it goes out of scope.

Parameters:

deviceMemory CUDA memory pointer to take ownership over.

function allocateMemory

bool allocateMemory(
    size_t numberOfBytes
)

Allocates device memory. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate

Return: True on success, false if there is already memory allocated by this instance, or if the CUDA malloc failed.

function allocateMemoryAsync

bool allocateMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Allocates device memory. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate
cudaStream The CUDA stream to use for the allocation. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Return: True on success, false if there is already memory allocated by this instance, or if the CUDA malloc failed.

function reallocateMemory

bool reallocateMemory(
    size_t numberOfBytes
)

Parameters:

numberOfBytes Number of bytes to allocate in the new allocation

Return: True on success, false if CUDA free or CUDA malloc failed.

function reallocateMemoryAsync

bool reallocateMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Parameters:

numberOfBytes Number of bytes to allocate in the new allocation
cudaStream The CUDA stream to use for the allocation and freeing of memory. A reference to this stream will also be saved internally to be used to asynchronously free them memory when this instance goes out of scope.

Return: True on success, false if CUDA free or CUDA malloc failed.

function allocateAndResetMemory

bool allocateAndResetMemory(
    size_t numberOfBytes
)

Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate

Return: True on success, false if there is already memory allocated by this instance, or if any of the CUDA operations failed.

function allocateAndResetMemoryAsync

bool allocateAndResetMemoryAsync(
    size_t numberOfBytes,
    cudaStream_t cudaStream
)

Allocates device memory and resets all bytes to zeroes. The memory allocated will automatically be freed by the destructor.

Parameters:

numberOfBytes Number of bytes to allocate
cudaStream The CUDA stream to use for the allocation and resetting. A reference to this stream will also be saved internally to be used to asynchronously free them memory when the instance goes out of scope.

Return: True on success, false if there is already memory allocated by this instance, or if any of the CUDA operations failed.

function freeMemory

bool freeMemory()

Free the device memory held by this class. Calling this when no memory is allocated is a no-op.

See: freeMemoryAsync instead.

Return: True in case the memory was successfully freed (or not allocated to begin with), false otherwise.

function freeMemoryAsync

bool freeMemoryAsync(
    cudaStream_t cudaStream
)

Deallocate memory asynchronously, in a given CUDA stream. Calling this when no memory is allocated is a no-op.

Parameters:

cudaStream The CUDA stream to free the memory asynchronously in

Return: True in case the memory deallocation request was successfully put in queue in the CUDA stream.

Note:

The method will return as soon as the deallocation is put in queue in the CUDA stream, i.e. before the actual deallocation is made.
It is the programmer’s responsibility to ensure this DeviceMemory is not used in another CUDA stream before this method is called. In case it is used in another CUDA stream, sufficient synchronization must be made before calling this method (and a very good reason given for not freeing the memory in that CUDA stream instead)

function setFreeingCudaStream

void setFreeingCudaStream(
    cudaStream_t cudaStream
)

Set which CUDA stream to use for freeing this DeviceMemory. In case the DeviceMemory already holds a CUDA stream to use for freeing the memory, this will be overwritten.

Parameters:

cudaStream The new CUDA stream to use for freeing the memory when the destructor is called.

function ~DeviceMemory

~DeviceMemory()

Destructor, frees the internal CUDA memory.

function getDevicePointer

template <typename T  =uint8_t>
inline T * getDevicePointer() const

Template Parameters:

T The pointer type to return

Return: the CUDA memory pointer handled by this class. Nullptr in case no memory is allocated.

function getSize

size_t getSize() const

Return: The size of the CUDA memory allocation held by this class.

function DeviceMemory

DeviceMemory(
    DeviceMemory && other
)

function operator=

DeviceMemory & operator=(
    DeviceMemory && other
)

function swap

void swap(
    DeviceMemory & other
)

function DeviceMemory

DeviceMemory(
    DeviceMemory const & 
) =delete

DeviceMemory is not copyable.

function operator=

DeviceMemory operator=(
    DeviceMemory const & 
) =delete

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.16 - IngestApplication

IngestApplication

Public Classes

	Name
struct	Settings

Public Functions

	Name
	IngestApplication() Constructor, creates an empty IngestApplication without starting it.
	~IngestApplication() Destructor.
bool	start(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, const Settings & settings) Start this IngestApplication given an interface to the System Controller and an UUID.
bool	stop() Stop this IngestApplication.
std::string	getVersion() Get application version.
std::string	getGitRevision() Get git revision which application was built on.
std::string	getBuildInfo() Get application build information.
std::string	getLibraryVersions() Get the versions of the libraries available at runtime, among others, CUDA version, BMD and NDI versions.

Public Functions Documentation

function IngestApplication

IngestApplication()

Constructor, creates an empty IngestApplication without starting it.

function ~IngestApplication

~IngestApplication()

Destructor.

function start

bool start(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
)

Start this IngestApplication given an interface to the System Controller and an UUID.

Parameters:

controllerInterface The interface for communication with the System Controller
settings The settings for the IngestApplication

Return: True if the IngestApplication was successfully started, false otherwise

function stop

bool stop()

Stop this IngestApplication.

Return: True if the IngestApplication was successfully stopped, false otherwise

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “1.0.0”

function getGitRevision

static std::string getGitRevision()

Get git revision which application was built on.

Return: a string with the current git revision, e.g. “v1.0.0”, or “v2.1.0-231-gcd012ab”

function getBuildInfo

static std::string getBuildInfo()

Get application build information.

Return: a string with the current build information such as git hashes of all direct dependencies

function getLibraryVersions

static std::string getLibraryVersions()

Get the versions of the libraries available at runtime, among others, CUDA version, BMD and NDI versions.

Return: a string with the currently found versions of the libraries used by this application

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.17 - IngestApplication::Settings

IngestApplication::Settings

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.18 - ISystemControllerInterface

ISystemControllerInterface

An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server. An ISystemControllerInterface can have a parent-child relationship with other interfaces, where the children are aware of which their parent interface is. This is useful for components that provides extra features for another component, but where the components are still to be considered as two separate entities with separate connections to the System controller.

#include <ISystemControllerInterface.h>

Inherited by SystemControllerConnection

Public Classes

	Name
struct	Callbacks A struct containing the callbacks that needs to be registered by the component using this interface.
struct	Response A response to a request, consists of a status code and an (optional) parameters JSON object.

Public Types

Name

enum class uint32_t

StatusCode { SUCCESS = 3001, TOO_MANY_REQUESTS = 3101, UUID_ALREADY_REGISTERED = 3201, FORMAT_ERROR = 3202, ALREADY_CONFIGURED = 3203, OUT_OF_RESOURCES = 3204, NOT_FOUND = 3205, INTERNAL_ERROR = 3206, CONNECTION_FAILED = 3207, TIMEOUT_EXCEEDED = 3208, KEY_MISMATCH = 3209, UNKNOWN_REQUEST = 3210, MALFORMED_REQUEST = 3211, ALREADY_IN_USE = 3212}
Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions

	Name
virtual	~ISystemControllerInterface() =default Virtual destructor.
virtual std::optional< std::string >	sendMessage(const std::string & messageTitle, const nlohmann::json & parameters) =0 Send a message containing a JSON object to the controller.
virtual bool	registerRequestCallback(const Callbacks & callbacks) =0 Register the callbacks to call for events in this class.
virtual bool	connect() =0 Connect to the System controller.
virtual bool	disconnect() =0 Disconnect from the System controller.
virtual bool	isConnected() const =0
virtual std::string	getUUID() const =0
virtual bool	hasParent() const =0
virtual std::shared_ptr< ISystemControllerInterface >	getParentInterface() const =0

Public Types Documentation

enum StatusCode

Enumerator	Value	Description
SUCCESS	3001	3000-3099 Info/Notifications
TOO_MANY_REQUESTS	3101	3100-3199 Warnings
UUID_ALREADY_REGISTERED	3201	3200-3299 Error
FORMAT_ERROR	3202
ALREADY_CONFIGURED	3203
OUT_OF_RESOURCES	3204
NOT_FOUND	3205
INTERNAL_ERROR	3206
CONNECTION_FAILED	3207
TIMEOUT_EXCEEDED	3208
KEY_MISMATCH	3209
UNKNOWN_REQUEST	3210
MALFORMED_REQUEST	3211
ALREADY_IN_USE	3212

Public Functions Documentation

function ~ISystemControllerInterface

virtual ~ISystemControllerInterface() =default

Virtual destructor.

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) =0

Send a message containing a JSON object to the controller.

Parameters:

messageTitle The title of the status type or request
parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplemented by: SystemControllerConnection::sendMessage

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) =0

Parameters:

callbacks The callbacks to use when events in this class happen

Return: True on successful registration, false if some callback is not set or if already connected

Reimplemented by: SystemControllerConnection::registerRequestCallback

function connect

virtual bool connect() =0

Connect to the System controller.

Return: True on successful connection, false on error or if already connected

Reimplemented by: SystemControllerConnection::connect

function disconnect

virtual bool disconnect() =0

Disconnect from the System controller.

Return: True on successful disconnection, false on error or if not connected

Reimplemented by: SystemControllerConnection::disconnect

function isConnected

virtual bool isConnected() const =0

Return: True if connected to the System controller, false otherwise

Reimplemented by: SystemControllerConnection::isConnected

function getUUID

virtual std::string getUUID() const =0

Return: The UUID of this interface to the System controller

Reimplemented by: SystemControllerConnection::getUUID

function hasParent

virtual bool hasParent() const =0

Return: True if this component has a parent ISystemControllerInterface, false otherwise

Reimplemented by: SystemControllerConnection::hasParent

function getParentInterface

virtual std::shared_ptr< ISystemControllerInterface > getParentInterface() const =0

Return: A pointer to parent’s ISystemControllerInterface, if any. Returns nullptr in case there is no parent

Reimplemented by: SystemControllerConnection::getParentInterface

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.19 - ISystemControllerInterface::Callbacks

ISystemControllerInterface::Callbacks

A struct containing the callbacks that needs to be registered by the component using this interface.

#include <ISystemControllerInterface.h>

Public Attributes

	Name
std::function< Response(const std::string &, const nlohmann::json &)>	mRequestCallback
std::function< void(uint32_t, const std::string &, const std::error_code &)>	mConnectionClosedCallback

Public Attributes Documentation

variable mRequestCallback

std::function< Response(const std::string &, const nlohmann::json &)> mRequestCallback;

variable mConnectionClosedCallback

std::function< void(uint32_t, const std::string &, const std::error_code &)> mConnectionClosedCallback;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.20 - ISystemControllerInterface::Response

ISystemControllerInterface::Response

A response to a request, consists of a status code and an (optional) parameters JSON object.

#include <ISystemControllerInterface.h>

Public Attributes

	Name
StatusCode	mCode
nlohmann::json	mParameters

Public Attributes Documentation

variable mCode

StatusCode mCode;

variable mParameters

nlohmann::json mParameters;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.21 - MediaReceiver

MediaReceiver

#include <MediaReceiver.h>

Public Classes

	Name
struct	NewStreamParameters A struct containing information on the format of an incoming stream.
struct	Settings Settings for a MediaReceiver.

Public Types

	Name
enum class uint32_t	TallyBorderColor { kNone, kRed, kGreen, kYellow} Available colors for tally border in multi view.

Public Functions

	Name
	MediaReceiver() Default constructor.
	~MediaReceiver() Default destructor.
bool	start(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, CUcontext cudaContext, const Settings & settings) Start the MediaReceiver. This method will call connect on the System controller interface and set up the callbacks from the interface to call internal methods.
void	stop() Stop the MediaReceiver.
std::function< void(const AlignedFramePtr &)>	getCustomMultiViewSourceInput(uint32_t inputSlot, const std::string & name ="") This method allows the Rendering Engine to provide custom input sources to the Multi-view generator to send video streams that can be added to the multi-views. This could for instance be used for adding a “preview” of the video stream the rendering engine is about to cut to.
bool	removeCustomMultiViewSourceInput(uint32_t inputSlot) Remove a custom multi-view generator source input earlier registered using the `getCustomMultiViewSourceInput` method.
void	setTallyBorder(uint32_t inputSlot, TallyBorderColor color) Set tally border color in the multi-views for a specific input slot.
void	clearTallyBorder(uint32_t inputSlot) Remove tally border in the multi-views for a specific input slot.
void	clearAllTallyBorders() Remove all tally borders.
MediaReceiver::TallyBorderColor	getTallyBorder(uint32_t inputSlot) const get tally border color for an input slot
	MediaReceiver(MediaReceiver const & ) =delete MediaReceiver is neither copyable nor movable.
	MediaReceiver(MediaReceiver && ) =delete
MediaReceiver &	operator=(MediaReceiver const & ) =delete
MediaReceiver &	operator=(MediaReceiver && ) =delete
std::string	getVersion() Get application version.
std::string	getBuildInfo() Get application build information.
std::string	getLibraryVersions() Get versions of the libraries available at runtime, among others, CUDA runtime and driver versions.

Public Types Documentation

enum TallyBorderColor

Enumerator	Value	Description
kNone
kRed
kGreen
kYellow

Available colors for tally border in multi view.

Public Functions Documentation

function MediaReceiver

MediaReceiver()

Default constructor.

function ~MediaReceiver

~MediaReceiver()

Default destructor.

function start

bool start(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    CUcontext cudaContext,
    const Settings & settings
)

Start the MediaReceiver. This method will call connect on the System controller interface and set up the callbacks from the interface to call internal methods.

Parameters:

controllerInterface The ISystemControllerInterface to use for this MediaReceiver. The interface should be configured (Such as setting the IP address and port of the System Controller if a server based System Controller is used) but not connected before passed to this method. This method will internally set the callbacks before connecting to the controller. If the controller is already connected or if the controller is not configured, this method will return false. This class will take ownership of the smart pointer.
cudaContext The CUDA context to use for this MediaReceiver. The frames will delivered as CUDA pointers, valid in this context, and the multi-view generator will use this context for rendering and encoding.
settings The settings to use for the MediaReceiver.

Return: True if the MediaReceiver was started successfully, false otherwise.

function stop

void stop()

Stop the MediaReceiver.

function getCustomMultiViewSourceInput

std::function< void(const AlignedFramePtr &)> getCustomMultiViewSourceInput(
    uint32_t inputSlot,
    const std::string & name =""
)

Parameters:

inputSlot The input slot this source will be “plugged in” to. The custom input sources share the input slots with the streams connected from Ingests. This means that it is probably a good idea to use higher numbered slots for these custom inputs, such as numbers from 1000, so that the lower numbers, 1 and up, can be used by the connected video cameras, as the input slot number will also be used when cutting.
name Optional human readable name of this stream, to be presented to the System Controller.

See: MediaReceiver::Settings::mDecodedFormat.

Precondition: The AlignedFrame sent to this function must have the same pixel format as this MediaReceiver is configured to deliver to the Rendering Engine,

function removeCustomMultiViewSourceInput

bool removeCustomMultiViewSourceInput(
    uint32_t inputSlot
)

Remove a custom multi-view generator source input earlier registered using the getCustomMultiViewSourceInput method.

Parameters:

inputSlot The input slot the custom multi-view source input is connected to, that should be removed

Return: True if the custom multi-view source input was successfully removed, false in case there was no custom input registered for the given input slot, or in case of an internal error.

function setTallyBorder

void setTallyBorder(
    uint32_t inputSlot,
    TallyBorderColor color
)

Set tally border color in the multi-views for a specific input slot.

Parameters:

inputSlot the input slot for a source
color the color to set

function clearTallyBorder

void clearTallyBorder(
    uint32_t inputSlot
)

Remove tally border in the multi-views for a specific input slot.

Parameters:

inputSlot the input slot for a source

function clearAllTallyBorders

void clearAllTallyBorders()

Remove all tally borders.

function getTallyBorder

MediaReceiver::TallyBorderColor getTallyBorder(
    uint32_t inputSlot
) const

get tally border color for an input slot

Parameters:

inputSlot the input slot to get color for

Return: the tally border color for the given input slot

function MediaReceiver

MediaReceiver(
    MediaReceiver const & 
) =delete

MediaReceiver is neither copyable nor movable.

function MediaReceiver

MediaReceiver(
    MediaReceiver && 
) =delete

function operator=

MediaReceiver & operator=(
    MediaReceiver const & 
) =delete

function operator=

MediaReceiver & operator=(
    MediaReceiver && 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “1.0.0”

function getBuildInfo

static std::string getBuildInfo()

Get application build information.

Return: a string with the current build information such as git hashes of all direct dependencies

function getLibraryVersions

static std::string getLibraryVersions()

Get versions of the libraries available at runtime, among others, CUDA runtime and driver versions.

Return: a string with the currently found versions of the libraries used by this application

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.22 - MediaReceiver::NewStreamParameters

MediaReceiver::NewStreamParameters

A struct containing information on the format of an incoming stream.

#include <MediaReceiver.h>

Public Attributes

	Name
uint32_t	mVideoHeight
uint32_t	mVideoWidth
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mAudioSampleRate

Public Attributes Documentation

variable mVideoHeight

uint32_t mVideoHeight = 0;

variable mVideoWidth

uint32_t mVideoWidth = 0;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 1;

variable mAudioSampleRate

uint32_t mAudioSampleRate = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.23 - MediaReceiver::Settings

MediaReceiver::Settings

Settings for a MediaReceiver.

#include <MediaReceiver.h>

Public Attributes

	Name
PixelFormat	mDecodedFormat The pixel format delivered to the rendering engine.
std::function< std::function< void(const AlignedFramePtr &)>uint32_t inputSlot, const std::string &streamID, const NewStreamParameters &newStreamParameters)>	mNewConnectionCallback
std::function< void(uint32_t inputSlot)>	mClosedConnectionCallback
bool	mUseMultiViewer
bool	mDeliverOld Set to true if this MediaReceiver should have a multi-view generator.
CUstream	mAlignedFrameFreeStream

Public Attributes Documentation

variable mDecodedFormat

PixelFormat mDecodedFormat = PixelFormat::kRgba64Le;

The pixel format delivered to the rendering engine.

variable mNewConnectionCallback

std::function< std::function< void(const AlignedFramePtr &)>uint32_t inputSlot, const std::string &streamID, const NewStreamParameters &newStreamParameters)> mNewConnectionCallback;

Parameters:

inputSlot can be seen as a virtual SDI input on a hardware mixer and should be used by the Rendering engine to identify sources. For example, if a source is connected to input slot 5, the button “Cut to camera 5” on the control panel ought to cut to this stream. The MediaReceiver is responsible for making sure only one stream can be connected to an input slot at a time. This callback might be called multiple times with the same input slot, however, in case the stream has been disconnected and the mClosedConnectionCallback has been called for that input slot earlier.
streamID is the identification string of the video/audio source on the Ingest. A Rendering engine might have the same StreamID connected multiple times (for instance if two different alignments are used for the same source) so this should not be used as an unique identifier for the stream.
newStreamParameters contains information on the pending incoming stream to allow the Rendering engine to decide if it can receive it or not.

variable mClosedConnectionCallback

std::function< void(uint32_t inputSlot)> mClosedConnectionCallback;

Parameters:

inputSlot The input slot that was disconnected

variable mUseMultiViewer

bool mUseMultiViewer = false;

variable mDeliverOld

bool mDeliverOld = false;

Set to true if this MediaReceiver should have a multi-view generator.

variable mAlignedFrameFreeStream

CUstream mAlignedFrameFreeStream = nullptr;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.24 - MediaStreamer

MediaStreamer

MediaStreamer is a class that can take a single stream of uncompressed video and/or audio frames and encode and output it in some way to some interface. This interface can either be a stream to a network or writing down the data to a file on the hard drive. This class is configured from two interfaces. The input configuration (input video resolution, frame rate, pixel format, number of audio channels…) is made through this C++ API. The output stream is then started from the System Controller. Any of these configurations can be made first. The actual stream to output will start once the first call to. More…

#include <MediaStreamer.h>

Public Classes

	Name
struct	Configuration The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.

Public Functions

	Name
	MediaStreamer() Default constructor.
	~MediaStreamer() Destructor. This will stop the output stream if not already done by calling.
bool	configure(const std::shared_ptr< ISystemControllerInterface > & controllerInterface, CUcontext cudaContext) Configure this MediaStreamer and connect it to the System controller. This must be called before any call to the.
bool	setInputFormatAndStart(const Configuration & configuration) Set the input format of this MediaStreamer and start the streamer. The.
bool	stopAndResetFormat() Stop streaming and reset the format. A call to this method will stop any output streams set up by the ISystemControllerInterface and reset the input format set by the.
bool	hasFormatAndIsRunning() const
bool	hasOpenOutputStream() const
bool	outputData(const AlignedFramePtr & frame) Output data through this streamer. The AlignedFrame::mRenderingTimestamp of the frame will be used as PTS when encoding the uncompressed frame.
std::string	getVersion() Get application version.
std::string	getBuildInfo() Get application build information.

Detailed Description

class MediaStreamer;

See: outputData is made.

Public Functions Documentation

function MediaStreamer

MediaStreamer()

Default constructor.

function ~MediaStreamer

~MediaStreamer()

Destructor. This will stop the output stream if not already done by calling.

See: stop.

function configure

bool configure(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    CUcontext cudaContext
)

Configure this MediaStreamer and connect it to the System controller. This must be called before any call to the.

Parameters:

controllerInterface The interface to the System controller, used for communicating with this MediaStreamer
cudaContext The CUDA context to use for this MediaStreamer. The frames passed to this instance should be valid in this CUDA context. The streamer will use this context for preprocessing and encoding.

See:

Return: True if the streamer was successfully connected to the System controller

function setInputFormatAndStart

bool setInputFormatAndStart(
    const Configuration & configuration
)

Set the input format of this MediaStreamer and start the streamer. The.

Parameters:

configuration The configuration with the format of the frames that will be sent to this MediaReceiver

See:

configure method must be called before this method is called. This method must be called before any call to
outputData. If the format should be reset, the
stopAndResetFormat method should be called first and then this method can be called again to reset the format.

Return: True if the streamer was successfully started, false otherwise

function stopAndResetFormat

bool stopAndResetFormat()

Stop streaming and reset the format. A call to this method will stop any output streams set up by the ISystemControllerInterface and reset the input format set by the.

See: setInputFormatAndStart method. The connection to the ISystemControllerInterface will be kept.

Return: True if the stream was successfully stopped and the format reset, or if the format was not set before this method was called, false on error.

function hasFormatAndIsRunning

bool hasFormatAndIsRunning() const

Return: True if the input format is set and the OutputStreamer is running, false otherwise

function hasOpenOutputStream

bool hasOpenOutputStream() const

See:

outputData will be discarded without being encoded, as there is no stream to output them to. This method can be used to check if the frame even needs to be produced by the rendering engine. Note however, that the
outputData method will still log the frames sent to it as received, even if they are not encoded when the output stream is closed.

Return: True if the output stream of the MediaStreamer is currently open and outputting the data, false otherwise. In case this returns false all frames passed to

function outputData

bool outputData(
    const AlignedFramePtr & frame
)

Output data through this streamer. The AlignedFrame::mRenderingTimestamp of the frame will be used as PTS when encoding the uncompressed frame.

Parameters:

frame The data frame to output, with video data in CUDA memory

See: setInputFormatAndStart method, or if the format has not been set by a call to that method.

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “1.0.0”

function getBuildInfo

static std::string getBuildInfo()

Get application build information.

Return: a string with the current build information such as git hashes of all direct dependencies

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.25 - MediaStreamer::Configuration

MediaStreamer::Configuration

The input configuration of the frames that will be sent to this MediaStreamer. The output stream configuration is made from the System controller via the ISystemControllerInterface.

#include <MediaStreamer.h>

Public Attributes

	Name
PixelFormat	mIncomingPixelFormat
uint32_t	mWidth
uint32_t	mHeight
uint32_t	mFrameRateN
uint32_t	mFrameRateD
uint32_t	mAudioSampleRate
uint32_t	mNumAudioChannels

Public Attributes Documentation

variable mIncomingPixelFormat

PixelFormat mIncomingPixelFormat = PixelFormat::kUnknown;

variable mWidth

uint32_t mWidth = 0;

variable mHeight

uint32_t mHeight = 0;

variable mFrameRateN

uint32_t mFrameRateN = 0;

variable mFrameRateD

uint32_t mFrameRateD = 0;

variable mAudioSampleRate

uint32_t mAudioSampleRate = 0;

variable mNumAudioChannels

uint32_t mNumAudioChannels = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.26 - PipelineSystemControllerInterfaceFactory

PipelineSystemControllerInterfaceFactory

Public Functions

	Name
	PipelineSystemControllerInterfaceFactory(const std::string & systemControllerIP, uint16_t systemControllerPort, const std::string & systemControllerPostfix, const std::string & psk, const std::string & myIP, bool useHTTPS, bool allowInsecureHTTPS, const std::string & customCaCertFile) Constructor.
	PipelineSystemControllerInterfaceFactory(PipelineSystemControllerInterfaceFactory const & ) =delete
	PipelineSystemControllerInterfaceFactory(PipelineSystemControllerInterfaceFactory const && ) =delete
PipelineSystemControllerInterfaceFactory &	operator=(PipelineSystemControllerInterfaceFactory const & ) =delete
PipelineSystemControllerInterfaceFactory &	operator=(PipelineSystemControllerInterfaceFactory const && ) =delete
std::shared_ptr< SystemControllerConnection >	getMediaReceiverInterface(const std::string & name) Get the interface to the MediaReceiver. Multiple calls to this method will return the same interface. Internally the UUID is randomly generated and the correct type is set.
std::shared_ptr< SystemControllerConnection >	createMediaStreamerInterface(const std::string & name) Create a new SystemControllerInterface to a MediaStreamer. Multiple calls to this method will return new interfaces each time. Internally the UUID is randomly generated, the correct type is set and the MediaReceiver is set as parent. The.
std::shared_ptr< SystemControllerConnection >	createControlReceiverInterface(const std::string & name) Create a new SystemControllerInterface to a ControlReceiver. Multiple calls to this method will return new interfaces each time. Internally the UUID is randomly generated, the correct type is set and the MediaReceiver is set as parent. The.

Public Functions Documentation

function PipelineSystemControllerInterfaceFactory

PipelineSystemControllerInterfaceFactory(
    const std::string & systemControllerIP,
    uint16_t systemControllerPort,
    const std::string & systemControllerPostfix,
    const std::string & psk,
    const std::string & myIP,
    bool useHTTPS,
    bool allowInsecureHTTPS,
    const std::string & customCaCertFile
)

Constructor.

Parameters:

systemControllerIP The IP address of the System controller to connect to.
systemControllerPort The network port of the System controller to connect to.
systemControllerPostfix The postfix of the System controller’s address, to chose which API endpoints to use.
psk The Pre-shared key used for authorization at the System controller.
myIP The public IP address of the pipeline, i.e. the external IP used to connect to the pipeline.
useHTTPS If HTTPS should be used instead of HTTP
allowInsecureHTTPS Set to true to allow self-signed HTTPS certificates. Should normally be false.
customCaCertFile Full path to CA certificate file for verifying server cert, optional.

function PipelineSystemControllerInterfaceFactory

PipelineSystemControllerInterfaceFactory(
    PipelineSystemControllerInterfaceFactory const & 
) =delete

function PipelineSystemControllerInterfaceFactory

PipelineSystemControllerInterfaceFactory(
    PipelineSystemControllerInterfaceFactory const && 
) =delete

function operator=

PipelineSystemControllerInterfaceFactory & operator=(
    PipelineSystemControllerInterfaceFactory const & 
) =delete

function operator=

PipelineSystemControllerInterfaceFactory & operator=(
    PipelineSystemControllerInterfaceFactory const && 
) =delete

function getMediaReceiverInterface

std::shared_ptr< SystemControllerConnection > getMediaReceiverInterface(
    const std::string & name
)

Get the interface to the MediaReceiver. Multiple calls to this method will return the same interface. Internally the UUID is randomly generated and the correct type is set.

Parameters:

name The human readable name of the MediaReceiver to provide to the System controller

Return: A configured connection on success, otherwise nullptr

function createMediaStreamerInterface

std::shared_ptr< SystemControllerConnection > createMediaStreamerInterface(
    const std::string & name
)

Create a new SystemControllerInterface to a MediaStreamer. Multiple calls to this method will return new interfaces each time. Internally the UUID is randomly generated, the correct type is set and the MediaReceiver is set as parent. The.

Parameters:

name The human readable name of the MediaStreamer to provide to the System controller

See: getMediaReceiverInterface must be called before this method is called

Return: A configured connection on success, otherwise nullptr

function createControlReceiverInterface

std::shared_ptr< SystemControllerConnection > createControlReceiverInterface(
    const std::string & name
)

Create a new SystemControllerInterface to a ControlReceiver. Multiple calls to this method will return new interfaces each time. Internally the UUID is randomly generated, the correct type is set and the MediaReceiver is set as parent. The.

Parameters:

name The human readable name of the ControlReceiver to provide to the System controller

See: getMediaReceiverInterface must be called before this method is called to generate the parent interface.

Return: A configured connection on success, otherwise nullptr

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.27 - SystemControllerConnection

SystemControllerConnection

An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.

#include <SystemControllerConnection.h>

Inherits from ISystemControllerInterface

Public Classes

	Name
struct	Settings Settings for a SystemControllerConnection.

Public Types

	Name
enum class uint32_t	ComponentType { kIngest, kMediaReceiver, kMediaStreamer, kControlDataReceiver, kControlDataSender} Enumeration of component types the component using this SystemControllerConnection can tell the System Controller to be seen as.

Public Functions

	Name
	SystemControllerConnection()
	~SystemControllerConnection() override
bool	configure(const Settings & settings, const std::shared_ptr< ISystemControllerInterface > & parentInterface =nullptr) Configure this connection. This method should be called before calling.
virtual bool	connect() override Connect to the server using the settings set with the.
virtual bool	isConnected() const override
virtual std::string	getUUID() const override
virtual std::optional< std::string >	sendMessage(const std::string & messageTitle, const nlohmann::json & parameters) override Send a message containing a JSON object to the system controller server.
virtual bool	disconnect() override Disconnect from the server.
virtual bool	registerRequestCallback(const Callbacks & callbacks) override Register callbacks to call when getting requests from the server or the server connection is lost.
virtual bool	hasParent() const override
virtual std::shared_ptr< ISystemControllerInterface >	getParentInterface() const override
	SystemControllerConnection(SystemControllerConnection const & ) =delete
	SystemControllerConnection(SystemControllerConnection && ) =delete
SystemControllerConnection &	operator=(SystemControllerConnection const & ) =delete
SystemControllerConnection &	operator=(SystemControllerConnection && ) =delete

Additional inherited members

Public Classes inherited from ISystemControllerInterface

	Name
struct	Callbacks A struct containing the callbacks that needs to be registered by the component using this interface.
struct	Response A response to a request, consists of a status code and an (optional) parameters JSON object.

Public Types inherited from ISystemControllerInterface

Name

enum class uint32_t

StatusCode { SUCCESS, TOO_MANY_REQUESTS, UUID_ALREADY_REGISTERED, FORMAT_ERROR, ALREADY_CONFIGURED, OUT_OF_RESOURCES, NOT_FOUND, INTERNAL_ERROR, CONNECTION_FAILED, TIMEOUT_EXCEEDED, KEY_MISMATCH, UNKNOWN_REQUEST, MALFORMED_REQUEST, ALREADY_IN_USE}
Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions inherited from ISystemControllerInterface

	Name
virtual	~ISystemControllerInterface() =default Virtual destructor.

Public Types Documentation

enum ComponentType

Enumerator	Value	Description
kIngest
kMediaReceiver
kMediaStreamer
kControlDataReceiver
kControlDataSender

Enumeration of component types the component using this SystemControllerConnection can tell the System Controller to be seen as.

Public Functions Documentation

function SystemControllerConnection

SystemControllerConnection()

function ~SystemControllerConnection

~SystemControllerConnection() override

function configure

bool configure(
    const Settings & settings,
    const std::shared_ptr< ISystemControllerInterface > & parentInterface =nullptr
)

Configure this connection. This method should be called before calling.

Parameters:

settings The settings to use when connecting to the server
parentInterface Optional parent interface that this interface is a child of. Setting this to nullptr means that this interface does not have a parent interface

See: connect.

Return: True if successfully configured, false otherwise

function connect

virtual bool connect() override

Connect to the server using the settings set with the.

See: configure method.

Return: True if connection was successful, false otherwise

Reimplements: ISystemControllerInterface::connect

function isConnected

virtual bool isConnected() const override

Return: True if this class is connected to the server, false otherwise

Reimplements: ISystemControllerInterface::isConnected

function getUUID

virtual std::string getUUID() const override

Return: The UUID of this interface to the System controller

Reimplements: ISystemControllerInterface::getUUID

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) override

Send a message containing a JSON object to the system controller server.

Parameters:

messageTitle The title of the status type or request
parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplements: ISystemControllerInterface::sendMessage

function disconnect

virtual bool disconnect() override

Disconnect from the server.

Return: True if successfully disconnected, false on internal error

Reimplements: ISystemControllerInterface::disconnect

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) override

Parameters:

callbacks The callbacks to set

Return: True if successfully registered, false if a callback is not set, or if already connected to the server

Reimplements: ISystemControllerInterface::registerRequestCallback

function hasParent

virtual bool hasParent() const override

Return: True if this component has a parent ISystemControllerInterface, false otherwise

Reimplements: ISystemControllerInterface::hasParent

function getParentInterface

virtual std::shared_ptr< ISystemControllerInterface > getParentInterface() const override

Return: A pointer to parent’s ISystemControllerInterface, if any. Returns nullptr in case there is no parent

Reimplements: ISystemControllerInterface::getParentInterface

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection const & 
) =delete

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection && 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection const & 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection && 
) =delete

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.28 - SystemControllerConnection::Settings

SystemControllerConnection::Settings

Settings for a SystemControllerConnection.

#include <SystemControllerConnection.h>

Public Attributes

	Name
std::string	mSystemControllerIP
uint16_t	mSystemControllerPort
std::string	mSystemControllerPostfix
std::string	mPSK
std::string	mUUID
ComponentType	mType
std::string	mName
std::string	mMyIP
std::chrono::milliseconds	mConnectTimeout
bool	mEnableHTTPS
bool	mInsecureHTTPS
std::string	mCustomCaCertFile

Public Attributes Documentation

variable mSystemControllerIP

std::string mSystemControllerIP;

variable mSystemControllerPort

uint16_t mSystemControllerPort;

variable mSystemControllerPostfix

std::string mSystemControllerPostfix;

variable mPSK

std::string mPSK;

variable mUUID

std::string mUUID;

variable mType

ComponentType mType;

variable mName

std::string mName;

variable mMyIP

std::string mMyIP;

variable mConnectTimeout

std::chrono::milliseconds mConnectTimeout {
            3000};

variable mEnableHTTPS

bool mEnableHTTPS;

variable mInsecureHTTPS

bool mInsecureHTTPS;

variable mCustomCaCertFile

std::string mCustomCaCertFile;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.29 - TimeCommon::TAIStatus

TimeCommon::TAIStatus

Public Attributes

	Name
StratumLevel	mStratum
bool	mHasLock
double	mTimeDiffS

Public Attributes Documentation

variable mStratum

StratumLevel mStratum = StratumLevel::UnknownStratum;

variable mHasLock

bool mHasLock = false;

variable mTimeDiffS

double mTimeDiffS = 0.0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.1.30 - TimeCommon::TimeStructure

TimeCommon::TimeStructure

Public Attributes

	Name
uint64_t	t1
uint64_t	t2
uint64_t	t3
uint64_t	t4
uint64_t	token
uint64_t	dummy1
uint64_t	dummy2
uint64_t	dummy3

Public Attributes Documentation

variable t1

uint64_t t1 = 0;

variable t2

uint64_t t2 = 0;

variable t3

uint64_t t3 = 0;

variable t4

uint64_t t4 = 0;

variable token

uint64_t token = 0;

variable dummy1

uint64_t dummy1 = 0;

variable dummy2

uint64_t dummy2 = 0;

variable dummy3

uint64_t dummy3 = 0;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2 - Files

Files

dir build
- dir install
  - dir include
    - file include/AclLog.h
    - file include/AlignedFrame.h
    - file include/Base64.h
    - file include/ControlDataCommon.h
    - file include/ControlDataReceiver.h
    - file include/ControlDataSender.h
    - file include/DeviceMemory.h
    - file include/ISystemControllerInterface.h
    - file include/IngestApplication.h
    - file include/IngestUtils.h
    - file include/MediaReceiver.h
    - file include/MediaStreamer.h
    - file include/PipelineSystemControllerInterfaceFactory.h
    - file include/PixelFormat.h
    - file include/SystemControllerConnection.h
    - file include/TimeCommon.h
    - file include/UUIDUtils.h

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2.1 - include/AclLog.h

include/AclLog.h

Namespaces

Name
AclLog A namespace for logging utilities.

Classes

	Name
class	AclLog::CommandLogFormatter This class is used to format log entries for Rendering Engine commands.
class	AclLog::ThreadNameFormatterFlag
class	AclLog::FileLocationFormatterFlag A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <filesystem>
#include <string>

#include <spdlog/details/log_msg.h>
#include <spdlog/fmt/fmt.h>
#include <spdlog/formatter.h>
#include <spdlog/pattern_formatter.h>
#include <sys/prctl.h>

namespace AclLog {

enum class Level {
    kTrace,    // Detailed diagnostics (for development only)
    kDebug,    // Messages intended for debugging only
    kInfo,     // Messages about normal behavior (default log level)
    kWarning,  // Warnings (functionality intact)
    kError,    // Recoverable errors (functionality impaired)
    kCritical, // Unrecoverable errors (application must stop)
    kOff       // Turns off all logging
};

void init(const std::string& name);

void initCommandLog(const std::string& name);

void setLevel(Level level);

void logCommand(const std::string& origin, const std::string& command);

AclLog::Level getLogLevel();

size_t getMaxFileSize();

size_t getMaxLogRotations();

std::filesystem::path getLogFileFullPath(const std::string& name);

class CommandLogFormatter : public spdlog::formatter {
public:
    CommandLogFormatter();
    void format(const spdlog::details::log_msg& msg, spdlog::memory_buf_t& dest) override;
    [[nodiscard]] std::unique_ptr<spdlog::formatter> clone() const override;

private:
    std::unique_ptr<spdlog::pattern_formatter> mCommandLogPattern;
};

inline std::string getThreadName() {
    static const size_t RECOMMENDED_BUFFER_SIZE = 20;
    static thread_local std::string name;

    if (name.empty()) {
        char buffer[RECOMMENDED_BUFFER_SIZE];
        int retval = prctl(PR_GET_NAME, buffer);
        if (retval == -1) {
            throw spdlog::spdlog_ex("Failed to get thread name: ", errno);
        }
        name = std::string(buffer);
    }
    return name;
}

class ThreadNameFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg&, const std::tm&, spdlog::memory_buf_t& dest) override {
        std::string threadName = getThreadName();
        dest.append(threadName.data(), threadName.data() + threadName.size());
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<ThreadNameFormatterFlag>();
    }
};

class FileLocationFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg& msg, const std::tm&, spdlog::memory_buf_t& dest) override {
        if (!msg.source.empty()) {
            using namespace spdlog::details;

            dest.push_back('[');
            const char* filename = short_filename_formatter<null_scoped_padder>::basename(msg.source.filename);
            fmt_helper::append_string_view(filename, dest);
            dest.push_back(':');
            fmt_helper::append_int(msg.source.line, dest);
            dest.push_back(']');
        }
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<FileLocationFormatterFlag>();
    }
};

} // namespace AclLog

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2.2 - include/AlignedFrame.h

include/AlignedFrame.h

Classes

Name

struct

AlignedAudioFrame
AlignedAudioFrame is a frame of interleaved floating point audio samples with a given number of channels.

struct

Types

	Name
using std::shared_ptr< AlignedAudioFrame >	AlignedAudioFramePtr
using std::shared_ptr< const AlignedAudioFrame >	AlignedAudioFrameConstPtr
using std::shared_ptr< AlignedFrame >	AlignedFramePtr

Functions

	Name
AlignedAudioFramePtr	createAlignedAudioFrame(uint8_t numberOfChannels, uint32_t numberOfSamplesPerChannel) Create a new AudioFrame with a given amount of samples allocated and all samples initialized to 0.0f.
AlignedAudioFramePtr	extractChannel(AlignedAudioFrameConstPtr sourceFrame, uint8_t channelIndex) Extract one channel from an AlignedAudioFrame as a new AlignedAudioFrame. The new AlignedAudioFrame will share no data with the original frame, meaning the new frame can be edited without corrupting the old one.

Types Documentation

using AlignedAudioFramePtr

using AlignedAudioFramePtr =  std::shared_ptr<AlignedAudioFrame>;

using AlignedAudioFrameConstPtr

using AlignedAudioFrameConstPtr =  std::shared_ptr<const AlignedAudioFrame>;

using AlignedFramePtr

using AlignedFramePtr =  std::shared_ptr<AlignedFrame>;

Functions Documentation

function createAlignedAudioFrame

AlignedAudioFramePtr createAlignedAudioFrame(
    uint8_t numberOfChannels,
    uint32_t numberOfSamplesPerChannel
)

Create a new AudioFrame with a given amount of samples allocated and all samples initialized to 0.0f.

Parameters:

numberOfChannels Number of channels to allocate space for
numberOfSamplesPerChannel Number of samples per channel to allocate space for

Return: Shared pointer to the new AudioFrame

function extractChannel

AlignedAudioFramePtr extractChannel(
    AlignedAudioFrameConstPtr sourceFrame,
    uint8_t channelIndex
)

Parameters:

sourceFrame The frame to extract a channel from
channelIndex The zero-based channel index to extract

Return: Shared pointer to a new mono AlignedAudioFrame, or nullptr if channel is out of bounds

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <array>
#include <iostream>
#include <memory>
#include <vector>

#include <cuda_runtime_api.h>

#include "DeviceMemory.h"
#include "PixelFormat.h"

struct AlignedAudioFrame {
    // The samples interleaved
    std::vector<float> mSamples;
    uint8_t mNumberOfChannels = 0;
    uint32_t mNumberOfSamplesPerChannel = 0;
};

using AlignedAudioFramePtr = std::shared_ptr<AlignedAudioFrame>;
using AlignedAudioFrameConstPtr = std::shared_ptr<const AlignedAudioFrame>;

AlignedAudioFramePtr createAlignedAudioFrame(uint8_t numberOfChannels, uint32_t numberOfSamplesPerChannel);

AlignedAudioFramePtr extractChannel(AlignedAudioFrameConstPtr sourceFrame, uint8_t channelIndex);

struct AlignedFrame {

    AlignedFrame() = default;

    ~AlignedFrame() = default;

    AlignedFrame(AlignedFrame const&) = delete;            // Copy construct
    AlignedFrame& operator=(AlignedFrame const&) = delete; // Copy assign

    [[nodiscard]] std::shared_ptr<AlignedFrame> makeShallowCopy() const;

    int64_t mCaptureTimestamp = 0;

    int64_t mRenderingTimestamp = 0;

    // Video
    std::shared_ptr<DeviceMemory> mVideoFrame = nullptr;
    PixelFormat mPixelFormat = PixelFormat::kUnknown;
    uint32_t mFrameRateN = 0;
    uint32_t mFrameRateD = 0;
    uint32_t mWidth = 0;
    uint32_t mHeight = 0;

    // Audio
    AlignedAudioFramePtr mAudioFrame = nullptr;
    uint32_t mAudioSamplingFrequency = 0;
};

using AlignedFramePtr = std::shared_ptr<AlignedFrame>;

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2.3 - include/Base64.h

include/Base64.h

Functions

	Name
std::string	encodeBase64(const uint8_t * data, size_t size) Base64 encode some data.
std::string	encodeBase64(const std::vector< uint8_t > & data) Base64 encode some data.
std::vector< uint8_t >	decodeBase64(const std::string & data) Decode some Base64 encoded data.

Functions Documentation

function encodeBase64

std::string encodeBase64(
    const uint8_t * data,
    size_t size
)

Base64 encode some data.

Parameters:

data Pointer to the data to encode with Base64
size The length of the data to encode with Base64

Return: The resulting Base64 encoded string

function encodeBase64

std::string encodeBase64(
    const std::vector< uint8_t > & data
)

Base64 encode some data.

Parameters:

data The data to encode with Base64

Return: The resulting Base64 encoded string

function decodeBase64

std::vector< uint8_t > decodeBase64(
    const std::string & data
)

Decode some Base64 encoded data.

Parameters:

data The Base64 encoded string to decode

Return: The resulting decoded data

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <string>
#include <vector>

std::string encodeBase64(const uint8_t* data, size_t size);

std::string encodeBase64(const std::vector<uint8_t>& data);

std::vector<uint8_t> decodeBase64(const std::string& data);

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2.4 - include/ControlDataCommon.h

include/ControlDataCommon.h

Namespaces

Name
ControlDataCommon

Classes

	Name
struct	ControlDataCommon::ConnectionStatus Connection status struct containing information about a connection event.
struct	ControlDataCommon::Response A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
struct	ControlDataCommon::StatusMessage A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

Source code

// Copyright (c) 2022, Edgeware AB. All rights reserved.

#pragma once

#include <cstdint>
#include <string>
#include <vector>

namespace ControlDataCommon {

enum class ConnectionType { CONNECTED, DISCONNECTED };

struct ConnectionStatus {

    ConnectionStatus() = default;

    ConnectionStatus(ConnectionType mConnectionType, const std::string& mIp, uint16_t mPort)
        : mConnectionType(mConnectionType)
        , mIP(mIp)
        , mPort(mPort) {
    }

    ConnectionType mConnectionType = ConnectionType::DISCONNECTED;
    std::string mIP;
    uint16_t mPort = 0;
};

struct Response {
    std::vector<uint8_t> mMessage; 
    uint64_t mRequestId = 0;       
    std::string mFromUUID;         
};

struct StatusMessage {
    std::vector<uint8_t> mMessage; 
    std::string mFromUUID;         
};

} // namespace ControlDataCommon

Updated on 2024-01-25 at 12:02:05 +0100

2.3.2.5 - include/ControlDataReceiver.h

include/ControlDataReceiver.h

Classes

	Name
class	ControlDataReceiver A ControlDataReceiver can receive messages from a sender or another ControlDataReceiver using a network connection. It can also connect to and forward the incoming request messages to other receivers. The connections to the sender and the other receivers are controlled by an ISystemControllerInterface instance. The ControlDataReceiver has a `receiving` or `listening` side, as well as a `sending` side. The listening side can listen to one single network port and have multiple ControlDataSenders and ControlDataReceivers connected to that port to receive requests from them. On the sending side of the ControlDataReceiver, it can be connected to the listening side of other ControlDataReceivers, used to forward all incoming messages to that receiver, as well as sending its own requests.
struct	ControlDataReceiver::IncomingRequest An incoming request to this ControlDataReceiver.
struct	Cont