Releases

• 1: Release 6.0.0
• 2: Release 5.0.0
• 3: Release 4.0.0
• 4: Release 3.0.0
• 5: Release 2.0.0
• 6: Release 1.0.0
• 7: Upgrade instructions

1 - Release 6.0.0

Build date

2024-01-29

Release status

Type: Sixth production ready release

Release content

Product version

6.0.0

Release artifacts

Changelog

• From this release Agile Live will be released as .deb packages instead of an archive of binaries and shared libs.
• To simplify compatibility verifications, all components inside Agile Live now have the same version number as the version of the release they belong to, in this release 6.0.0. This means some components have received an older version number compared to earlier and some components have skipped several major versions.
• The component -> System Controller communication has been changed from a request-response type of communication to a one-way communication, where the System Controller won’t send a response back and the component won’t expect a response back.
• More informative error messages from the System Controller in case requests fail

Ingest

• Support for ingesting SRT sources. Both caller and listener mode is supported, with or without passphrase. Currently AVC and HEVC video codecs are supported and AAC audio. New SRT sources can be set up using the REST API.
• Counters for dropped_frames, lost_frames and duplicated_frames are now split into separate counters for audio and video called dropped_audio_frames, dropped_video_frames, lost_audio_frames and so on
• The NDI interface now supports interlaced NDI sources with individual fields
• The Ingest application now logs the enabled input interfaces more clearly and also outputs the API version of all interfaces supported on the machine.

Rendering Engine

• The Rendering Engine now supports playback of media files directly in the mixer itself. The player supports seeking as well as looping of the entire clip, or a section of the clip.
• The Rendering Engine can send information on the states of all media players to HTML pages. This way graphics can be shown for countdown until a clip ends, or to overlay such information to aid hosts in the studio.
• The generic control panel acl-tcpcontrolpanel now accepts multiple connections on a single port. As a result of this, the environment variable has changed name to ACL_TCP_ENDPOINT without an S and only accepts a single endpoint.
• Fix a crash when some invalid control commands was sent to the Rendering Engine.

Production Pipeline

• The visibility of the audio bars in the multi-views is now configurable per multi-view output.

Control Data Sender and Control Data Receiver

No changes

System Controller

• Fields are not correctly marked as “required” or “optional” in the OpenAPI specification served from the System Controller
• Fixed a bug where the metrics for retransmitted_packets and sent_bytes on the GET requests to multi-view did not increment
• The PSK is now checked for complexity. A too simple PSK (for instance just the same letter repeated 32 times) will not be accepted anymore
• Fix for CVE-2023-44487: DOS with HTTP/2
• The list of locations where the System Controller searches for the acl_sc_settings.json file has changed to just two locations: /etc/opt/agile_live followed by the current working directory.
• The log file of the System Controller is now created with file permissions that let any user read it
• The public IP of Pipelines are now included in the REST API

Known limitations

Media Player

Videos will be stretched in case the video played does not have the same aspect ratio as the Rendering Engine is using.

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

MPEG-TS over UDP

For Outputs and multi-view outputs it is currently not possible to bind to a specific IP and port with MPEG-TS over UDP, even if local_ip and local_port are exposed in the REST API.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

Security

No known issues

2 - Release 5.0.0

Build date

2023-10-09

Release status

Type: Fifth production ready release

Release content

Product version

5.0.0

Release artifacts

Library details

libacl-ingest.so

Version: 11.0.0

Library containing the core Ingest functionality used by the acl-ingest executable.

libacl-productionpipeline.so

Version: 12.0.0

Library containing the MediaReceiver, MediaStreamer and ControlDataReceiver classes, used to implement a Rendering Engine. Also used by the acl-renderingengine application

libacl-controldatasender.so

Version: 11.0.0

Library containing the ControlDataSender class, used to send control messages to a ControlDataReceiver component.

Changelog

• It is now possible to use hostnames instead of just IP addresses for ACL_SYSTEM_CONTROLLER_IP environment variable.
• HTTPS and client authentication are now enabled by default in the system
• The new environment variable ACL_CUSTOM_CA_CERT_FILE makes it possible to set a custom CA certificate to use for verifying the system controller’s certificate. This can be used in cases when the CA certificate cannot be added to the list of OS trusted CA certificates.
• SRT logs are now printed to the components’ log files and not just to the terminal

Ingest 11.0.0

• SRT connections to Production Pipelines will now automatically try to reconnect in case the network link goes down.

Rendering Engine 3.0.0

• The Rendering Engine now features a built in HTML renderer using the Chromium web engine through Chromium Embedded Framework. The HTML renderer is capable of opening multiple “browsers”, connected to input slots of the operator’s choice, rendering HTML graphics hosted by HTTP servers or even loading regular webpages.
• A new chroma key node was added to make green screen effects possible.
• The internal audio mixer now features a high pass and a low pass filter

Production Pipeline 12.0.0

• The cadence and speed/quality balance can now be set for the MediaStreamer and Multi view outputs
• MediaStreamer now supports multiple output streams (e.g. both SRT and UDP, or multiple SRTs and UDP outputs with different settings), as long as they use the same encoding settings.
• Performance of the Production Pipeline has been improved. The load on the NvDec chip is reduced by up to ~50% and the load on the CUDA cores reduced by up to ~60% in certain conditions.
• The Multi View outputs now show peak meter audio bars for all views, which makes solving audio problems much easier, as one can see both the audio of the incoming and outgoing video streams.
• The Random Access Indicator (RAI) is now correctly set in the MPEG-TS output streams
• Outputs with SRT in caller mode will now start even if the connection was not successfully made. The SRT connection will try to connect until it succeeds, or is manually closed down. In case the network link is broken, the SRT caller will try to keep connecting until it succeeds or is manually closed down.

Control Data Sender 11.0.0 and Control Data Receiver 12.0.0

• The release now features a new acl-websocketcontrolpanel, which works like the already existing acl-tcpcontrolpanel, but allows for multiple clients to connect via WebSocket to the control panel instead.
• It is now possible to use hostnames instead of just IP addresses when connecting a Control Data Sender or Receiver to another Control Data Receiver.
• Fix bug where it was not possible to disconnect a Control Data Sender/Control Panel from a Receiver and connect it to another Receiver on another port.

System Controller 5.0.0

• The REST API now correctly flags parameters with a default value in the Swagger documentation. These values does not need to be passed in the JSON blob with the REST API call. Parameters without a default value are correctly flagged as required in the documentation.
• The Outputs part of the REST API has been updated to support multiple output streams from the same output component. The name of the REST API endpoints has been moved from pipelines/{uuid}/outputs/{output_uuid}/stream to pipelines/{uuid}/outputs/{output_uuid}/streams to reflect this. The POST request will return an id integer to identify the stream within the Output component. A new endpoint [DELETE] pipelines/{uuid}/outputs/{output_uuid}/streams/{stream_id} has been added to close a specific stream. All streams of an output can be closed with the old [DELETE] pipelines/{uuid}/outputs/{output_uuid}/streams endpoint.
• System controller now logs to file. Default log location is /tmp with the log file prefixed with acl-system-controller.
• Requests to the REST API are now rate limited to prevent overloading the components and to mitigate DOS attacks.
• The IPBB cadence and speed/quality balance can now be specified for the encoder in both Output streams and Multiview output streams.
• Prometheus endpoint now stops reporting metrics for closed streams.
• Improve execution time of [DELETE] streams/{stream_uuid}
• Authentication has been added to the Prometheus endpoint.
• The parameters ip and port in the [GET] pipelines/{uuid}/outputs/{output_uuid}/streams has been corrected to remote_ip and remote_port. Their values are now reported correctly.
• Security of the System Controller has been improved in several ways.
• Prometheus endpoint has been updated with some missing statistics
• The missing audio_mapping parameter has been added to the [GET] ingests/{uuid}/streams/{stream_uuid} and [GET] pipelines/{uuid}/streams/{stream_uuid} endpoints.
• The sent_bytes parameter of the output statistics is now incremented as expected for both Multi View outputs and Output streams.
• Fixed a bug where the System Controller application would crash when started with a filename as -settings-path parameter.

Known limitations

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

MPEG-TS over UDP

For Outputs and multi-view outputs it is currently not possible to bind to a specific IP and port with MPEG-TS over UDP, even if local_ip and local_port are exposed in the REST API.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

Security

No known issues

3 - Release 4.0.0

Build date

2023-06-16

Release status

Type: Fourth production ready release

Release content

Product version

4.0.0

Release artifacts

Library details

libacl-ingest.so

Version: 10.0.0

Library containing the core Ingest functionality used by the acl-ingest executable.

libacl-productionpipeline.so

Version: 11.0.0

Library containing the MediaReceiver, MediaStreamer and ControlDataReceiver classes, used to implement a Rendering Engine. Also used by the acl-renderingengine application

libacl-controldatasender.so

Version: 9.0.0

Library containing the ControlDataSender class, used to send control messages to a ControlDataReceiver component.

Changelog

• The system now requires Chrony as the NTP client for time synchronization. See NTP instructions for more details. The applications will not start if Chrony reports an drift greater than 5 ms.
• New environment variables ACL_LOG_MAX_FILE_SIZE and ACL_LOG_MAX_LOG_ROTATIONS to control the number and size of the rotated log files for the applications
• Fix parsing of boolean environment variables

Ingest 10.0.0

• Support for transporting up to 16 channels of audio to the production, where a subset of the channels can be selected.
• Added support for using Opus as audio codec in transport to the Production Pipeline. This codec has a lower delay compared to the existing AAC codec. The user can now select codec per connected stream.
• Improved handling of NDI sources.
• Handle cases when SDI sources deliver one extra or one too few audio sample.
• The built-in MediaSourceGenerator now has a lower audio level of -20 LUFS.

Rendering Engine 2.0.0

• New audio mixer implementation with per-input-strip three-band parametric equalizer, compressor and panning.
• New automatic transition types: left and right wipe
• Add support for picture-in-picture effects. Currently the rendering engine support two separate picture-in-picture effects with an additional graphic effect on top.
• All control commands executed by a rendering engine is now written to a log file in /tmp
• Fix bug where disconnecting a source would leave the last frame frozen in the input slot with corrupted audio.

Production Pipeline 11.0.0

• It is now possible to include input slots where no stream has been connected yet to a multi-view output. The view will be empty until a source has been connected to that input slot, with the label visible.
• Views in the multi-view will remain after the corresponding input slot has been disconnected, showing a black frame with the label. The video will automatically turn up again when another stream is connected to the same input slot.
• Fix bug where the multi-view output would stop sending video when none of the sources in the multi-view were connected.
• Add support for SRT in caller mode for multi-view outputs and MediaStreamer outputs.
• Add support for setting the SRT latency and an optional passphrase for the multi-view outputs and MediaStreamer outputs.
• MediaReceiver API has a new method removeCustomMultiViewSourceInput to remove a custom feedback input earlier registered using getCustomMultiViewSourceInput.
• Improved latency of video decoder with ~1 frame.

Control Data Sender 9.0.0 and Control Data Receiver 10.0.0

• Fix application crash with acl-tcpcontrolpanel on connection failure.
• Updated control command protocol for video commands, where the first word addresses the node in the graph to make the change to. This allows for the same node to be used multiple times. See Rendering Engine commands for more details on the new protocol.
• Updated API where multiple, separate control commands can be sent in the same message, guaranteed to be delivered to the Rendering Engine at the same time point. The new method sendMultiRequestToReceivers is used to send such messages. The old API for sending just a single control command per message is unchanged.
• Raise the maximum control message length to 65535 bytes.

System Controller 4.0.0

• Expose a number of new metrics from the components for system monitoring in the REST API and Prometheus endpoint, including average/min/max encode and decode durations per stream, frame counters for video and audio in multiple locations, statistics for outgoing output streams and round trip time and measured bandwidth on the contribution links.
• The POST /streams endpoint now require an audio_mapping to know which audio channels to transport to the production. Use "[[0,1]]" for the same behavior as in previous versions (i.e. transport only channels 0 and 1, encoded as stereo).
• New counter lost_frames for Pipeline streams. It counts fully lost frames, not only broken frames, as the received_broken_frames counter.
• The counter lost_packets in the GET /ingests/{uuid}/streams endpoints has been removed in favor for the lost_packets and dropped_packets in the Pipeline.
• Counter queuing_video_frames has changed name to video_frames_in_queue.
• REST API now correctly returns the selected port when automatic port selection is requested (by setting the local_port to 0), instead of returning the port number as 0.
• REST API now show if sources are active or inactive, instead of hiding inactive sources (a source is active if it is ready to be used, as opposed to an inactive source, which has been seen earlier, but not any longer)
• Fix bug where the wrong port numbers of Control Connections would be shown in REST-API for port numbers automatically assigned by the OS.

Known limitations

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

MPEG-TS over UDP

For Outputs and multi-view outputs it is currently not possible to bind to a specific IP and port with MPEG-TS over UDP, even if local_ip and local_port are exposed in the REST API.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

Security issues

There is no rate limiting implemented in any of the components. Should the application be running in a network where ports are accessible to unauthorized users, there is a risk of a denial of service (DOS). The network should be configured with firewall rules closing out unauthorized users.

Encryption (HTTPS) is not enabled by default in acl-system-controller. This means that pre-shared keys (PSK) used for encrypted communication between components and the System Controller will be exchanged in the clear and could be revealed.

Client authentication is not enabled by default in acl-system-controller so anyone with access to HTTP on the machine hosting acl-system-controller will have access to the REST API.

Even when client authentication is enabled, there is no enforcement of the length or format of the password. Also note that HTTPS should be enabled when using client authentication since the credentials would otherwise be sent in clear text.

It is strongly recommended to enable both HTTPS and client authentication.

4 - Release 3.0.0

Build date

2023-01-23

Release status

Type: Third production ready release

Release content

Product version

3.0.0

Release artifacts

Library details

libacl-ingest.so

Version: 9.0.0

Library containing the core Ingest functionality used by the acl-ingest executable.

libacl-productionpipeline.so

Version: 10.0.0

Library containing the MediaReceiver, MediaStreamer and ControlDataReceiver classes, used to implement a Rendering Engine. Also used by the acl-renderingengine application

libacl-controldatasender.so

Version: 9.0.0

Library containing the ControlDataSender class, used to send control messages to a ControlDataReceiver component.

Changelog

Ingest 9.0.0

• Ingesting interlaced sources is now supported both with the Intel and Nvidia encoders. De-interlacing is automatically applied to interlaced input, so no extra work is needed by the user of the REST API when setting up the stream compared to a progressive source. The implementation supports de-interlacing 50i sources into 50p.
• The Ingest now supports encoding JPEG thumbnails using Nvidia GPUs. For now, only the first Nvidia GPU will be used on multi-GPU systems.
• Earlier when encoding HEVC with the Intel encoder, the setup would fail in case any of the fast, faster, good or better speed/quality settings were used, as these were not supported by the encoder. Now these settings are automatically changed to the closest supported setting, i.e. fast and good is changed to balanced, faster to fastest and better to best.
• The Intel JPEG encoder now supports encoding JPEGs with a width that is not evenly divisible by 16. Also requests for thumbnails with odd number of pixels in width/height will automatically be encoded with one extra pixel in width/height compared to the request, instead of failing the request.
• The Intel JPEG encoder now supports encoding thumbnails of interlaced sources.

Rendering Engine 1.0.0

No new features since last release.

Production Pipeline 10.0.0

• The network endpoints of the incoming streams from the Ingests are now closed after the Ingest has connected.

Control Data Sender 9.0.0 and Control Data Receiver 10.0.0

• Support for connecting multiple ControlDataSenders (or Receivers) to a single ControlDataReceiver is now working again.
• Improved verification of the established connection between ControlData components.
• Message delay can now be set per incoming connection to a ControlDataReceiver.

System Controller 3.0.0

• New version of the REST API, v2, which is served from /api/v2. The API has been reorganized and cleaned up to make it easier to use.
• Streams and Control Connections now get their own unique UUIDs when created using the REST API. This UUID is then used to reference the connection when making changes to and closing the connection. The UUID is returned when the connection is created and is also shown when querying information from the components on both sides of the connection. The old connection_id concept has been completely removed.
• The endpoints related to Control Connections are now on the top level and the same endpoints are used whether the connection is originating from a ControlDataSender or a ControlDataReceiver. Both Control Connections and Streams are now closed using their UUID and the corresponding DELETE endpoints. Also the PATCH endpoints use the UUID of the connection to identify the connection to make changes to.
• The Output and Control Receiver endpoint has been moved in under the Pipeline endpoint to better show their tight connection. When querying the Pipeline endpoint it will return its Outputs and Control Receivers.
• The parameter id used for an Ingest’s sources has been changed to source_id.
• The parameters resolution_x and resolution_y have been changed to width and height.
• The endpoint for /components has been removed in favor for the /ingests, /pipelines and /controlpanels endpoints.
• The thumbnail endpoint now has a new parameter encoder where the user can explicitly request that a certain encoder should be used for encoding the thumbnail. Current options are intel_gpu, nvidia_gpu or auto, where the last option will make the Ingest select the best encoder that is supported on the hardware the Ingest is running on.

Known limitations

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

Audio channels

Only stereo audio is supported with two channels embedded per connected input.

Security issues

There is no rate limiting implemented in any of the components. Should the application be running in a network where ports are accessible to unauthorized users, there is a risk of a denial of service (DOS). The network should be configured with firewall rules closing out unauthorized users.

Encryption (HTTPS) is not enabled by default in acl-system-controller. This means that pre-shared keys (PSK) used for encrypted communication between components and the System Controller will be exchanged in the clear and could be revealed.

Client authentication is not enabled by default in acl-system-controller so anyone with access to HTTP on the machine hosting acl-system-controller will have access to the REST API.

Even when client authentication is enabled, there is no enforcement of the length or format of the password. Also note that HTTPS should be enabled when using client authentication since the credentials would otherwise be sent in clear text.

It is strongly recommended to enable both HTTPS and client authentication.

5 - Release 2.0.0

Build date

2022-11-17

Release status

Type: Second production ready release

Release content

Product version

2.0.0

Release artifacts

Library details

libacl-ingest.so

Version: 8.0.0

Library containing the core Ingest functionality used by the acl-ingest executable.

libacl-productionpipeline.so

Version: 9.0.0

Library containing the MediaReceiver, MediaStreamer and ControlDataReceiver classes, used to implement a Rendering Engine. Also used by the acl-renderingengine application

libacl-controldatasender.so

Version: 8.0.0

Library containing the ControlDataSender class, used to send control messages to a ControlDataReceiver component.

Changelog

The supported OS has changed from Ubuntu 20.04 LTS to Ubuntu 22.04 LTS. Official support for Ubuntu 20.04 LTS is dropped from this release.

Ingest 8.0.0

• Changed to epoch aligned timestamps
• Improve duplicating and dropping of frames to cover up drifting cameras
• Expose counters for dropped, duplicated and lost frames per source in the REST API
• Fix a memory leak when generating thumbnails
• Interlaced sources are now shown in the REST API and correctly marked as interlaced
• Improved support for detecting connection and disconnection of SDI cables at runtime, as well as changes in the format of the sent SDI stream.
• Applications are now stopped by pressing Ctrl-C instead of pressing enter to prevent accidental stopping
• Thumbnails and source info are now cached for each source to improve response time in the REST API. This means that sources that are not connected to any production will only update its thumbnails and source info every ~5 seconds or so. Sources that are connected will update the info continuously.
• The field active for sources in the REST API was not working before and has now been removed in favor for a new field in_use which indicates if a source is currently being streamed somewhere or not.
• Log files will now get a unique name by appending the date of creation to the filename
• Log files will now have the same log level as the terminal output
• Appending the --help flag to the ingest executable will print information about the binary and list the environment variables
• A stack trace is now printed in case the application should crash

Rendering Engine 1.0.0

• First version of the Rendering Engine application
• Support for program, preview and cutting between them
• Support for fading between sources over a given time
• Support for graphics with key (alpha) by ingesting the fill and key (color and alpha) as two separate sources
• Support for fade to black
• Support for setting the audio volume per source

Production Pipeline 9.0.0

• Support for tally borders in the Multi-view generator with new API for setting and clearing the borders from the Rendering Engine in the MediaReceiver class.
• Updated API for passing video memory to and from the Rendering Engine, now uses RAII classes for automatic memory handling. See upgrade guide for more details.
• The MediaReceivernow passes the mRenderingTimestamp to the Rendering Engine, i.e. the timestamp when the frame was delivered.
• Alignment is internally rounded to the nearest even frame time. This together with the changes in the Ingest results in that the frames delivered to the RenderingEngine will have rendering timestamps that are evenly devisable by the frame time.
• PTS in MediaStreamers are now calculated based on the mRenderingTimestamp, instead of a newly taken timestamp when the frame was sent to the MediaStreamer. This will make the PTSes of the output streams equidistant, even if the Rendering Engine jitters slightly.
• New class PipelineSystemControllerInterfaceFactory to help Rendering Engine implementors in creation of SystemControllerConnections by reducing code duplication

Control Data Sender 8.0.0 and Control Data Receiver 9.0.0

• The control channel between ControlDataSenders and ControlDataReceivers are now encrypted by default. Read more about it in the security tutorial
• The support for connecting multiple ControlDataSenders or ControlDataReceivers to another ControlDataReceiver is temporarily disabled.

System Controller 2.0.0

• Added support for HTTPS communication with the REST API and encrypted connections between the components and the System Controller. Read about how to activate it in the security tutorial
• Components now automatically reconnects to the System Controller in case they loose connection to it. This means that the System Controller can be restarted during a broadcast and all components will automatically reconnect to it once it turns up again on the network. It also means that components can be started before the System Controller and get connected as soon as the System Controller is started
• REST API now features basic authentication. Read more about it in the security tutorial
• Streams (of audio and video) between Ingests and Production Pipelines are now automatically encrypted when set up by the System controller
• Control connections between Control Panels and Production Pipelines are now automatically encrypted when set up by the System controller
• Fix a bug where the System Controller would not search for the config file in all the directories listed in the documentation. Also make the application search in the application’s directory and not only the current working directory.
• New endpoint [PATCH] /pipelines/{uuid}/streamconnections/{connection_id} to change the alignment of an already created stream during runtime. Note that changing the alignment will cause the audio and video of that stream to make a sudden jump and/or freeze for a moment, so it is not recommended to do this on stream connections that are on air
• The endpoint [POST] /stream now has improved error messages in case the System Controller failed to start the stream. The endpoint also closes the Pipeline’s stream connection instead of leaving it open in case the Ingest failed to start the stream
• The [DELETE] endpoints for the specific components has been removed in favor for the general [DELETE] /components/{uuid} endpoint
• Fix a bug where the System Controller would crash in some rare cases when a component is shut down at the same time as a REST request is using that component.
• Fix some false positive log outputs

Known limitations

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

Number of Control Senders per Control Receiver

For now the system is limited to only connect one Control Sender (or Receiver) to another Control Receiver. This means that, for now, it is only possible to connect a single Control Panel to a production.

Audio channels

Only stereo audio is supported with two channels embedded per connected input.

Security issues

There is no rate limiting implemented in any of the components. Should the application be running in a network where ports are accessible to unauthorized users, there is a risk of a denial of service (DOS). The network should be configured with firewall rules closing out unauthorized users.

Encryption (HTTPS) is not enabled by default in acl-system-controller. This means that pre-shared keys (PSK) used for encrypted communication between components and the System Controller will be exchanged in the clear and could be revealed.

Client authentication is not enabled by default in acl-system-controller so anyone with access to HTTP on the machine hosting acl-system-controller will have access to the REST API.

Even when client authentication is enabled, there is no enforcement of the length or format of the password. Also note that HTTPS should be enabled when using client authentication since the credentials would otherwise be sent in clear text.

It is strongly recommended to enable both HTTPS and client authentication.

6 - Release 1.0.0

Build date

2022-06-23

Release status

Type: First production ready release

Release content

Product version

1.0.0

Release artifacts

Library details

libacl-ingest.so

Version: 7.0.0

Library containing the IngestApplication class used to implement an Ingest component.

libacl-productionpipeline.so

Version: 8.0.0

Library containing the MediaReceiver, MediaStreamer and ControlDataReceiver classes, used to implement a Rendering Engine.

libacl-controldatasender.so

Version: 7.0.0

Library containing the ControlDataSender class, used to send control messages to a ControlDataReceiver component.

Changelog

Ingest 7.0.0

• New metrics are available for the Ingest streamconnections in the REST API that can be used to monitor the streams.
• Fixed bug where the Ingest would crash with a std::runtime_error if grabbing a thumbnail on hardware without an Intel CPU with integrated GPU.
• Improved error messages for encoders and sources.
• Missing fields in the REST API for the Ingests have been added, such as max_network_latency_ms for streamconnections.
• Logs are now automatically flushed every 5 seconds.
• The class StaticIngestSystemController has been removed, please use the SystemControllerConnection class and the system controller instead.

Production Pipeline 8.0.0

• New metrics are available for the Pipeline streamconnections and Output in the REST API that can be used to monitor the streams.
• Fixed the AUD format in MEPG-TS output of the Pipelines when using HEVC, which earlier caused clicks in the audio channel and a lot of Invalid NAL unit 4, skipping. errors when playing back the streams using ffmpeg.
• Support for labels (so-called “Under Monitor Display”, UMD) in the multi-view outputs. The labels are set through the REST API when setting up multi-view outputs and can be changed at runtime.
• Missing fields in the REST API for the Pipelines have been added, such as max_network_latency_ms, alignment_ms and convert_color_range for streamconnections.
• Fixed DTS calculation for output streams in both the Multi-view generator and Output components.
• The network connections between a ControlDataReceiver and other ControlDataReceivers are now using TCP as protocol instead of SRT, which means that the messages are delivered as soon as they arrive and that no control messages will be dropped due to to timeouts in the transport.
• Fixed a minor CUDA memory leak in the multi-view generator that caused a slow, constantly growing GPU memory usage.
• Fixed CUDA memory corruption sometimes occurring when stopping and quickly restarting a multi-view output.
• Nvidia Ampere GPUs are now working with older CUDA drivers than version 510.
• Logs are now automatically flushed every 5 seconds.
• The classes StaticMediaReceiverSystemController and StaticMediaStreamerSystemController have been removed, please use the SystemControllerConnection class and the system controller instead.

Control Data Sender 7.0.0 and Control Data Receiver 8.0.0

• The network connections between a ControlDataSender and ControlDataReceivers are now using TCP as protocol instead of SRT, which means that the messages are delivered as soon as they arrive and that no control messages will be dropped due to timeouts in the transport.
• The classes StaticControlDataSenderSystemController and StaticControlDataReceiverSystemController have been removed, please use the SystemControllerConnection class and the System Controller instead.

System Controller 1.0.0

• Support for setting CORS and custom HTTP response headers in the configuration file.
• Improved validation of HTTP request payloads and improved error messages.
• New endpoint for deleting any type of component, [DELETE] /component.
• New, built-in Prometheus exporter, accessible through endpoint at [GET] /metrics.
• The version of the running system controller is now returned in each HTTP response in the X-Binary-Version header.

Known limitations

GPU performance

The GPU utilization in the Ingest status message is currently not working. Use intel_gpu_top and/or nvidia-smi instead.

Drivers

You need to install the CUDA Toolkit on Ingest machines, even if they don’t have Nvidia cards.

MPEG-TS output

The timestamps in the MPEG-TS output are not equidistant, which might confuse some playback tools. Playback the stream using a tool that works for now, such as ffmpeg.

Pre-shared key

The pre-shared key used to authorize components in the System controller is currently hard-coded into the Ingest application. This means that the psk in the System controller’s example config file must be used, otherwise is it not possible to connect an Ingest to the system.

7 - Upgrade instructions

Upgrade to 6.0.0 from 5.0.0

System Controller

• In endpoints /ingests/{uuid}?expand=true, /ingests/{uuid}/sources and /ingest/{uuid}/sources/{source_id} these three metrics has been split into audio and video variants: acl_ingest_source_dropped_frames has been split into acl_ingest_source_dropped_audio_frames and acl_ingest_source_dropped_video_frames, metric acl_ingest_source_duplicated_frames is split into acl_ingest_source_duplicated_audio_frames and acl_ingest_source_duplicated_video_frames; and acl_ingest_source_lost_frames is split into acl_ingest_source_lost_audio_frames and acl_ingest_source_lost_video_frames.
• In case the entropy of the PSK set in the System Controller was too low, the System Controller won’t start. Generate a new PSK and use that one.
• The System Controller does not longer search for the configuration file acl_sc_settings.json in the directories /etc/acl_system_controller, /app,/service,/acl_system_controller or /opt/acl_system_controller. Either put the file in the current working directory of the system controller application, in the directory /etc/opt/agile_live, or explicitly point at the directory of the config file using the flag --settings-path <PATH> when starting the System Controller.

Rendering Engine

• For the acl-tcpcontrolpanel the environment variable ACL_TCP_ENDPOINTS has changed name to ACL_TCP_ENDPOINT and only accept a single endpoint. This endpoint will now accept multiple connections.

C++ SDK

• AlignedFrame::PixelFormat has been replaced with ACL::PixelFormat, found in PixelFormat.h.
• ISystemControllerInterface::sendRequest has been replaced with ISystemControllerInterface::sendMessage, the System Controller will no longer send a response on messages. Since connection is over TCP, if the message could be sent, it has arrived properly to the System Controller, so there is no need for a response message that verifies that.

Upgrade to 5.0.0 from 4.0.0

System Controller

• Endpoints /pipelines/{uuid}/outputs/{output_uuid}/stream have been moved to /pipelines/{uuid}/outputs/{output_uuid}/streams to indicate multiple streams for the same Output can be created. The POST request takes the same parameters as before, but returns an ID of the newly created stream, which is globally unique together with the UUID of the Output. As of now, it is only possible to start multiple streams if the encoder settings match for all streams. Use the new endpoint [DELETE] /pipelines/{uuid}/outputs/{output_uuid}/streams/{stream_id} to stop a stream with a given ID.
• The response of [GET] /pipelines/{uuid}/outputs/{output_uuid}/streams differs from the old variant. In the new one not just a single active stream is presented, but a list of active_streams.
• The [POST] /pipelines/{uuid}/outputs/{output_uuid}/stream and [POST] /pipelines/{uuid}/multiviews endpoints now support setting the pic_mode and speed_quality_balance to control the quality of the encoding. While they don’t have to be explicitly specified in the REST API request as they have default values (pic_mode_ip and balanced), it might be desirable to manually specify them.

ProductionPipeline

• MediaReceiver::start has changed signature. It now takes a CUcontext as the second parameter, which should be a CUDA context reference to the device to run the CUDA operations on.
• The MediaReceiver::Settings struct has a new parameter mAlignedFrameFreeStream which should be a CUDA stream within the CUDA context passed to the MediaReceiver::start method, to use as the stream to make the asynchronous free on, after all the DeviceMemory pointers have been released.
• MediaStreamer::configure now has a second parameter to a CUcontext, which is the CUDA context defining which device to run the MediaStreamer on.
• PipelineSystemControllerInterfaceFactory constructor now takes an extra customCaCertFile parameter, pointing out an optional CA certificate file to use for validating certificates from the System Controller.

Upgrade to 4.0.0 from 3.0.0

System Controller

• The endpoint POST /streams now require two additional parameters audio_format and audio_mapping. The first one selects if AAC-LC or the new Opus codec should be used for audio encoding. AAC-LC has slightly higher quality, but is slower to encode. Opus has a lower latency and gives better quality at lower bitrates. The second parameter, audio_mapping tells the Ingest which audio channels to pick from the source and if they should be encoded as mono or stereo streams. (Stereo streams save bandwidth, but does not need to be used as stereo in the Rendering Engine). For example the mapping [4, [1, 2], 0] will result in 4 channels out in the Rendering Engine, where the channel with index 4 is output at index 0 and encoded as a mono channel, index 1 and 2 in the Ingest are encoded as stereo and output at channels 1 and 2 in the output and channel 0 in the input is encoded as mono and output to channel 3 in the output. Channel 4 in the input (and 5 and above) are ignored. To get the same behavior as in the previous release, pass AAC-LC and [[0,1]] respectively for audio_format and audio_mapping.
• Metric queueing_video_frames has changed name to video_frames_in_queue.
• In POST /pipelines/{uuid}/outputs/{output_uuid}/stream and POST /pipelines/{uuid}/multiviews the parameters ip and port are removed and replaced by four parameters called local_ip, local_port, remote_ip and remote_port. In MPEG-TS over SRT mode, their useage depends on the SRT mode. When in listener mode (srt_mode == listener) only the local_ip and local_port are used to set the address to listen to. Set local_port to 0, to make the OS automatically pick an available port. In SRT caller mode both local_ip, local_port and remote_ip, remote_port are used. The remote_* ones define the remote address to connect to and the local* ones the local address to bind to. To get the old behavior, where the local bind address is automatically chosen, set local_ip to 0.0.0.0 and local_port to 0 to automatically pick an unused port. For MPEG-TS over UDP mode, set the address to send the stream to using the remote_* parameters (The local_* variants should be present but must be set to 0.0.0.0 and 0, currently).
• The output of the GET /pipelines/{uuid}/outputs/{output_uuid}/stream and GET /pipelines/{uuid}/multiviews endpoints have changed the layout. See the REST API documentation for more details.
• The video_kilobit_rate parameter in GET /pipelines/{uuid}/streams/{stream_uuid} has been removed. Use the same parameter in the GET /ingests/{uuid}/streams/{stream_uuid} endpoint instead.
• The counter lost_packets in the GET /ingests/{uuid}/streams/{stream_uuid} endpoint has been removed in favor for the lost_packets and dropped_packets in the Pipeline.

ProductionPipeline

• The API of ControlDataReceiver::IncomingRequest has changed to get an std::vector of messages (std::vector<uint8_t>), to allow multiple messages to be delivered at the same time point. Just loop through the messages and handle them as before.
• The settings for mDebugVideo and mDebugAudio has been removed from MediaReceiver::Settings.

Upgrade to 3.0.0 from 2.0.0

System Controller

• The System Controller uses the new API prefix /api/v2, so all calls must update to this API version. The old API /api/v1 has been removed.
• All calls to the Control Receiver and Output endpoints must be updated, as these have been moved in under the /pipelines endpoint. See the REST API reference for details.
• When setting up Control Connections, the old [POST] /controlpanels/{uuid}/controlconnections and [POST] /controlpanels/{uuid}/controlconnections endpoints have been replaced with a single endpoint [POST] /controlconnections. The sending side component (whether a Control Panel or a Control Receiver) is passed as a parameter in the JSON HTTP body. Delete endpoints for controlconnections formerly under Control Panel and Control Receiver, have been replaced with a single endpoint [DELETE] /controlreceivers/{uuid}, which will close both sides of the connection.
• When closing streams, the [DELETE] /ingests/{uuid}/streamconnections/{connection_id} and [DELETE] /pipeline/{uuid}/streamconnections/{connection_id} have been replaced by a single endpoint [DELETE] /streams/{uuid}, which will close down both sides of the Stream.
• The endpoints for getting information from either the Ingest or Pipeline end of a Stream has been moved from [GET] /ingests/{uuid}/streamconnections/{connection_id} and [GET] /pipeline/{uuid}/streamconnections/{connection_id}to [GET] /ingests/{uuid}/streams/{stream_uuid} and [GET] /pipeline/{uuid}/streams/{stream_uuid}, where stream_uuid is the system-wide, unique identifier of the stream and is the same UUID on both the Ingest and Pipeline side of the connection in contrast to the old connection_id which was different in the Ingest and the Pipeline.
• The endpoint for changing the alignment of a stream has been moved from [PATCH] /pipelines/{uuid}/streamconnections/{connection_id} to [PATCH] /streams/{uuid}.
• The parameter id referring to a source has changed name to source_id in [POST] /streams and in responses from the Ingest when querying for information on the Sources or Streams.
• The parameters resolution_x and resoulution_y have changed name to width and height in several endpoints, among others the [POST] /streams and [POST] /ingests/{uuid}/sources/{source_id}/thumbnail.
• The thumbnails endpoint has been moved from [POST] /ingests/{uuid}/thumbnail to [POST] /ingests/{uuid}/sources/{source_id}/thumbnail, passing the source_id parameter in the path instead of the JSON HTTP body.
• The new encoder parameter must be specified when requesting thumbnails using the [POST] /ingests/{uuid}/sources/{source_id}/thumbnail endpoint. Set it to auto unless a specific implementation is required.

Upgrade to 2.0.0 from 1.0.0

System Controller

• Make sure to generate a new PSK (pre-shared key) for the acl_sc_settings.json file. This will be used to authorize components connecting to the System controller. All components connecting to the System controller must use the same PSK set using the environment variable ACL_SYSTEM_CONTROLLER_PSK. In case a component is started without the environment variable it will log an error and stop. Read more about this in the Security tutorial.

ProductionPipeline

• The API of the former struct AlignedData::DataFrame has changed.
  • The namespace AlignedData has been removed and the struct itself has been renamed to AlignedFrame. The enums CompressedVideoFormat and PixelFormat and typedef AudioSampleRow have been moved inside the struct.
  • The field mPTS has been removed and replaced by two new fields mCaptureTimestamp and mRenderingTimestamp, where the first is the TAI timestamp in mircoseconds since the UNIX epoch when the frame was captured by the Ingest and the second one is the timestamp when the frame was delivered to the Rendering Engine from the MediaReceiver. Both these timestamps are rounded to the nearest even frame step since the UNIX epoch, which should make it easier to group frames with the same rendering time. The mRenderingTimestamp is also used by the OutputStreamer to calculate the timestamps for the outgoing streams, so in case the Rendering Engine creates new AlignedFrame instances, make sure this value is incremented correctly for each frame that is put to the OutputStreamer.
  • The CUDA pointer mVideoDataCudaPtr has been removed in favor for an std::shared_ptr to an RAII class called DeviceMemory that keeps track of the CUDA memory pointer adn releases the memory automatically once not longer used by anyone. This makes it possible for the Rendering Engine to make copies of the shared pointer and then discard the AlignedFrame it was delivered with, in order to, for instance, cache the video frame or to handle video and audio data separately. Please do remember that the DeviceMemory from the AlignedFrames delivered by the MediaReceiver is read-only and should never be changed by any CUDA kernel, as this memory is also used by the multi-view generator to generate the multi-view outputs. The Rendering Engine might copy the shared pointer and keep it at long as it wants to, but never change the content of the DeviceMemory or write to the CUDA memory pointed to by it. AlignedFrames (and DeviceMemory instances made outside of an AlignedFrame) created by the Rendering Engine can of course be changed and used freely.