Upgrade instructions
Agile Live 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 AlignedFrame
s 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.