SmartCETS

The SmartCETS service encrypts MPEG TS content in real time according to the ISO/IEC 23001-9 standard (part: “Common encryption of MPEG-2 transport streams”). Keys for encryption are requested according to the Common Encryption API for Widevine DRM protocol (hereinafter Widevine API). Encrypted content can either be recorded to a file or broadcast over UDP multicast. The list of input channels for encryption along with other configuration parameters is specified in the JSON file.

Command Line Arguments

–help, -h

Print the help to the console and exit.

–version, -v

Print the version to the console and exit.

–config-file, -c

Default value: smartCETS.json

The path to the main configuration file.

–log-config, -l

Default value: smartCETS.log.json

The path to the logging configuration file.

–log-file

Default value: smartCETS_%Y-%m-%d_%H-%M-%S.%N.log

Log file name pattern. This option is ignored if –log-config is specified.

The following variables can be used in the file name:

• Y — year,
• m — month,
• d — day,
• H — hour,
• M — minute,
• S — second,
• N — the file number among files with the same name.

If no variables are defined, the file will be rotated only on service restart.

Configuration File

The parameters from the “Global Parameters” list (see below) can only be present at the top level of the JSON configuration file. The parameters from the “Stream Parameters” list (see below) can only be present in the description of a specific encryption stream. The parameters from the “General Parameters” list (see below) can be present both at the top level and in the description of a particular stream. The value at the particular stream level taking precedence over the value at the top level.

“Batch” means a piece of content with a maximum duration of max_batch_duration_msec (or a maximum length of max_batch_size_bytes if the duration cannot be determined).

Global Parameters

threads, unsigned integer 

Default value: 4

The number of OS worker threads.

config_update_period, time units 

Default value: 1 hour

The frequency of checking the configuration file for changes

config_update_signal, integer 

Default value: SIGUSR1

When the SmartCETS process receives a signal with this number, the configuration file will be checked for changes.

streams

Type: array of objects
Default value: []

The list of streams to encrypt. For each stream, in addition to the parameters from the “Stream Parameters” list (see below), you can also specify parameters from the “General Parameters” list.

content_id_string, string 

The encrypted content ID specified as an arbitrary ASCII string (for example, “my_content”).

content_id_hex, HEX string 

The encrypted content ID specified as a hex string (for example, FF7755FA1AFE11)

content_id_base64, Base64 string 

The encrypted content ID specified as a base64 string.

source_url, string 

Default value: –

The data source URL.

sink_url, string 

The URL to encrypted content streaming.

user, string 

The name of the user whose rights the smartCETS process will have. If no parameter value is specified (an empty string), the process is delegated the rights of the user who started it.

group, string 

The name of the group whose rights the smartCETS process will have. If no parameter value is specified (an empty string), the process is delegated the rights of the user group that started it.

key_server_url, string 

The URL to access the key server.

retry_timeout, time units 

Default value: 30 seconds

The repetition period of requests in case of a read error from the source. If the value is 0, in case of a data source error, reading from the source will be stopped.

idle_timeout, time units 

Default value: 30 seconds

If during the next period of time with a length of idle_timeout no data is read from the source for any stream, smartCETS will print in the log an error message like

Content <content ID>: no data for at least <idle_timeout> seconds

The period for each stream is counted separately. If the value is 0, the message will not be printed.

smooth_transmission_by_pcr, boolean 

The flag that enables/disables the output stream broadcasting according to PCR.

If set to false, the encrypted content will be sent according to default_transmission_rate_bytes_per_sec for UDP or as it is received from the encoder buffer for other broadcasting types (piece by piece, roughly corresponding to the boundaries of PES packets in the source stream).

If set to true, the return time of each datagram (contains 7 MPEG2-TS packets) will be calculated according to PCR regardless of the broadcasting type.

If not specified, for UDP broadcasting is considered to be true, and for writing to a file or HTTP broadcasting it is considered to be false.

max_pcr_jitter_usec, unsigned integer 

Default value: 200000

The maximum allowable difference between adjacent PCR values in microseconds.

Relevant when smooth_transmission_by_pcr is true.

If this limit is exceeded, the content between violating PCR will be sent according to default_transmission_rate_bytes_per_sec.

default_transmission_rate_bytes_per_sec, unsigned integer 

Default value: 12500000

The content transmission rate in the absence of PCR (or incorrect PCR) in the input stream. It also applies to UDP broadcasts when smooth_transmission_by_pcr is false.

min_batch_duration_usec, unsigned integer 

Default value: 100

Defines the minimum allowed batch return time. In case the actual return rate for some reason begins to lag behind the required one (determined by PCR or default_transmission_rate_bytes_per_sec), a certain amount of batch will be sent for min_batch_duration_usec, so that the real speed will “catch up” with the required.

max_batch_size_bytes, data size 

Default value: 1,25 MBytes

The maximum allowable batch size. If there is more than max_batch_size_bytes bytes between adjacent PCR, this part of content will be broadcast at the rate corresponding to default_transmission_rate_bytes_per_sec.

max_transmission_buffer_duration_msec, unsigned integer 

Default value: 10000

The maximum total buffer duration between the encoder and the output multicast broadcaster. If the total duration of the content in the buffer exceeds the value of this parameter, the input data encryption is suspended until a space in the buffer appears.

min_transmission_buffer_duration_msec, unsigned integer 

Default value: 1000

The minimum total buffer duration between the encoder and the output multicast broadcaster. Broadcasting of encrypted content will not begin until content has accumulated with a total duration of min_transmission_buffer_duration_msec.

ts_error_print_period, time units 

Default value: 30 seconds

The frequency of printing information about input TS stream errors to the log (for example, about CC jumps). If there are no errors, nothing is printed.

video_key_type, string 

Default value: SD

The key type for video tracks. It is used to encrypt MPEG-TS according to the CETS standard. If specified, all video tracks available in the input stream will be encrypted with this key type. Supports the same set of values as widevine.key_type.

audio_key_type, string 

Default value: AUDIO

The key type for audio tracks. It is used to encrypt MPEG-TS according to the CETS standard. If specified, all audio tracks available in the input stream will be encrypted with this key type. Supports the same set of values as widevine.key_type.

Encryption parameters and Widevine parameters are also available for configuration (except key_type — the video_key_type and audio_key_type parameters are used instead).

Each channel configuration must have one (and only one) of the content_id_string, content_id_hex, and content_id_base64 parameters. These parameters allow you to set the content_id in a user-friendly way. The source_url and sink_url parameters are required. For more information about the URL format, see “Input and Output URL Formats”

enable_audio_encryption, boolean 

Default value: true

Flag to disable audio encryption.

Encryption Parameters and Features According to ISO/IEC 23001-9

This section provides the ISO/IEC 23001-9 encryption settings (part: “Common encryption of MPEG-2 transport streams”) in SmartMedia services.

Parameters

max_encryptor_buffer_size, integer 

Default value: 50000

The maximum allowed size of the encoder buffer in TS packets.

Due to the peculiarities of the ECM generation algorithm according to ISO/IEC 23001-9, it is necessary to buffer the full PES packet before encryption begins. This parameter limits the buffer size, so as not to accumulate content indefinitely if there is no PES header in the stream.

packets_between_pssh, integer 

Default value: 0

The minimum number of TS packets between adjacent PSSH in the output stream.

PSSH for all tracks are inserted into the stream only after the PMT, so the actual distance between the PSSH in the output stream will exceed the packets_between_pssh value by no more than the distance between adjacent PMTs in the stream.

packets_between_audio_ecm, integer 

Default value: 50000

[The minimum number of TS packets between adjacent ECMs in the audio track.

With this parameter, you can increase the frequency of inserting audio ECM into the stream (see “Encryption Algorithm Features”).

msec_between_audio_ecm, integer 

Default value: 100

Audio duration between adjacent ECMs (see “Encryption Algorithm Features”).

Encryption Algorithm Features

The encryption is performed according to the ISO/IEC 23001-9 standard, namely:

• the original MPEG-TS container is preserved (except PMT), unknown tracks are not encrypted;
• the descriptors described in ISO / IEC 23001-9 are added to the source stream PMT for each track to be encrypted;
• the payload of each found video/audio track is encrypted;
• the utility is able to find H.262, H.264 and H.265 video tracks and AAC/ADTS, AC3 and DTS tracks;
• the utility is implementing the recommendations of ISO/IEC 23001-9 for the encryption of the H.264/H.265 and AAC payload (i.e., does not encrypt a payload of the TS packet containing the VPS/SPS/PPS/SliceHeader and ADTS Fixed header);
• the payload of TS packets containing PES headers is not encrypted for H.262, AC3, and DTS;
• the packets containing PSSH for all encrypted tracks are inserted into the output stream after PMT; the insertion occurs no more frequently than in every packets_between_pssh packets;
• before each PES header, ECMs related to it are inserted into the stream. The content of ECMs corresponds to the ISO/IEC 23001-9 standard. ECMs can also be inserted inside a PES packet if at least one of the conditions is met:
  • the contents of the currently accumulated ECM do not fit into the payload of a single TS packet;
  • for audio tracks: since the last inserted ECM, more than packets_between_audio_ecm TS packets belonging to this audio track have been processed;
  • for audio tracks: the length of processed content since the last ECM inserted exceeds msec_between_audio_ecm.

Example Configuration

JSON

{  “key_server_url”:“http://10.65.50.167/cenc/getkey”,  “signer_name”:“widevine_test”,  “signer_key”:“deadbeefdeadbeefdeadbeefdeadbeef”,  “signer_iv”:“deadbeefdeadbeefdeadbeefdeadbeef”,  “crypto_period_length”:“10h”,  “crypto_period_count”:“3”,  “key_request_policy”:“request_when_last_key_expires”,  “smooth_transmission_by_pcr”:“true”,  “msec_between_audio_ecm”:30,  “streams”: [    {      “content_id_hex”:“6365747374657374”,      “source_url”:“udp://239.65.40.4:5001”,      “sink_url”:“udp://239.2.0.59:2020”    },    {      “content_id_string”:“another_content”,      “source_url”:“udp://239.2.0.56:2020”,      “sink_url”:“udp://239.2.0.62:2020”    }  ] }

Input and Output URL Formats

The source and sink URLs are URLs with the udp:// and file:// protocols (see IO URL params).