Upgrade instructions

Upgrade to 9.0.0 from 8.0.0

• The acl-websocketcontrolpanel application has changed name to acl-websocketcontrolproxy. Apart from this, the application works the same way as before.

System Controller

• Before connecting streams to a Pipeline the endpoint [PUT] /pipelines/{uuid}/renderingengine/format must be called to set the required resolution and frame rate of the pipeline. Use [GET] /pipelines/{uuid}/renderingengine/format to get the currently set format. The PUT endpoint can only be called when all inputs, outputs and control connections are closed. At startup the default format is set to 1920x1080 50 FPS.

Upgrade to 8.0.0 from 7.0.0

The control protocol has been changed. For more information see the new protocol description.

System Controller

• The endpoint [POST] /pipelines/{uuid}/reset has been deprecated and moved to [POST] /pipelines/{uuid}/renderingengine/reset. The old endpoint is kept for backwards compatibility.

C++ SDK

• All C++ classes has been moved into the Acl namespace, make sure to prepend Acl:: where needed.
• The callbacks ControlDataSender::Settings::mConnectionStatusCallback and IControlDataReceiver::Settings::mConnectionStatusCallback has been removed and replaced by a new callback mConnectionEventCallback. With this the enum class ConnectionType and struct ConnectionStatus has been removed and replaced by enum class EventType and struct ConnectionEvent. With the old callback only connection notifications from the directly connected components would be sent to the user. With this new event callback, connection event notifications are propagated from other components, not directly connected to the user.
• ControlDataSender::sendRequestToReceivers and IControlDataReceiver::sendStatusMessageToSender and IControlDataReceiver::sendRequestToReceivers has parameter type of the request data from a vector<uint8_t> to an std::string. The ControlDataSender::sendRequestToReceivers also has two new parameters for requester UUID, used to identify clients of the control panel in case there are multiple such, and the number of hops to send the message.
• The ControlDataSender::sendMultiRequestToReceivers and IControlDataReceiver::sendMultiRequestToReceivers methods has been removed in favor for implementing multi message requests in the underlying protocol instead.
• IControlDataReceiver has changed from a push to a pull-based implementation where the mIncomingRequestCallback was removed and replaced by a getRequests method where the application can ask the IControlDataReceiver for all messages that should have been delivered by a specific time point. The mPreviewIncomingRequestCallback was also removed without a replacement.
• UUIDs now use a custom class instead of raw strings in the SDK.

Upgrade to 7.0.0 from 6.0.0

System Controller

• All REST API calls now must use the /api/v3 prefix
• The UUID of the Control Receivers has been removed, use the UUID of the Pipeline instead in [POST] /controlconnections
• All endpoints starting with /pipelines/{uuid}/controlreceivers have been removed. To get the statistics of the controlreceiver, see the controlreceiver part of the response from the [GET] /pipelines/{uuid}?expand=true request. In this response the connected_to has been renamed outgoing_connections and the list of incoming connections inside listening_interface has been moved out of that object and named incoming_connections
• The parameter connected_to in, among other endpoints, [GET] /controlpanels/{uuid} has been renamed to outgoing_connections
• The status JSON object for responses from controlreceivers, controlpanels and outputs has been removed and all parameters inside of it has been moved out

C++ SDK

• ControlDataReceiver and MediaStreamer classes have now been removed from the SDK and replaced by the interface classes IControlDataReceiver and IMediaStreamer. Use MediaReceiver::createMediaStreamerOutput to create new MediaStreamer instances and MediaReceiver::getControlDataReceiver to get the ControlDataReceiver instance.
• getGitRevision() and getBuildInfo() have been removed from the SDK. Use getVersion() instead.
• MediaReceiver::Settings now have a new function mResetCallback that must be set to a callback that should be called
• A new parameter const ControlDataReceiver::Settings& receiverSettings is required when calling MediaReceiver::start to set up the internal ControlDataReceiver.

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.