2. User Guide¶
Describing Elecard CodecWorks¶
Elecard CodecWorks is a professional software solution for encoding/transcoding, real-time multiplexing into MPEG-2/AVC/HEVC with up to 16K resolution supporting multiscreen encoding and HLS/MPEG-DASH adapting streaming technologies. CodecWorks operates on the base of a wide range of hardware.
Activation¶
There are the following ways to activate Elecard CodecWorks:
HWkey License — unique identifying code is compiled based on target PC hardware configuration with the help of a special utility, and CodecWorks build is tied to this code. To receive the utility, contact Elecard Technical Support Team or your project coordinator;
HASP License — Elecard mails a HASP key which has a unique code and should be plugged into a PC where CodecWorks is going to be used.
Licensing and Technical Support¶
Elecard CodecWorks is available as a demo version or a registered product. By installing, copying, or otherwise using the SOFTWARE PRODUCT or any UPDATES, you agree to be bound by the terms of the “Elecard” End-User License Agreement (“EULA”). This EULA is a legal agreement between you (either an individual or a single entity) and Elecard for the “Elecard” software product(s) accompanying this EULA, which include(s) computer software and may include “online” or electronic documentation, associated media, and printed materials (“SOFTWARE PRODUCT”).
System Requirements¶
When choosing servers for CodecWorks, the following should be taken into consideration:
CPU performance is of crucial importance for real time encoding process. Take it into account when you choose hardware for the encoding server.
The disk selected for the program installation should have enough free space for saving of the system log (for highly detailed logs) and memory dump files (if the application fails or abnormally closes).
For QuickSync hardware accelerated encoding, the graphical chip Intel® Graphics is required.
For Nvidia hardware accelerated encoding, the graphics card Nvidia is required.
To manage encoding service via SNMP protocol, the corresponding service must be installed in the system.
System requirements depend on several factors:
type of task (encoding, transcoding, multiplexing, etc.);
format, resolution and bit rate of input/output streams;
signal processing functions (frame size changing, deinterlacing, frame conversion, etc.);
number of channels to be processed.
The minimal system requirements recommended for proper operation of Elecard CodecWorks:
Windows 10/11/ Server 2019(64 bit), Linux Ubuntu 22.04
SSD/HDD from 256 GB
RAM 16 GB (two-channels mode is required)
CPU encoding |
GPU encoding (Intel QuickSync) |
GPU encoding (Nvidia) |
CPU (Intel from 4 gen, Xeon e7/5/3 v3 and upper, Xeon E/W/D, AMD zen gen and upper) |
CPU (Intel from 5 gen, Xeon e3, Xeon E) |
CPU (Intel from 5 gen, Xeon e3, Xeon E) |
Graphics card is not required |
An integrated or discrete Intel Graphics |
Nvidia card |
Installation¶
Follow the installation procedure as described for your operating system:
Windows
Run Elecard CodecWorks Setup and follow instructions.
The software will be installed to
C:\Program Files\Elecard\Elecard CodecWorksCreated schemas will be saved in
C:\ProgramData\Elecard\CodecWorks
Ubuntu
To install all packages [1] at once, run the installer:
~sudo apt install ./Elecard-CodecWorks*.deb
/usr/bin/Elecard/CodecWorks./etc/Elecard/CodecWorks.Note
For the correct installation of the product, Internet access is required to download dependencies.
Server — the server part of CodecWorks responsible for the work of tasks, transcoding/multiplexing.
Base — the base installation includes a console manager for managing CodecWorks, this variant is suitable for scripting.
GUI — the graphic control application.
Web — the web interface.
Additional Driver Installation¶
Drivers for Intel QS Ubuntu¶
~sudo apt install libdrm2 libva2 libva-drm2 libigdgmm12 intel-media-va-driver-non-free libmfx1
~sudo usermod -a -G video <user>
~sudo usermod -a -G render <user>
~sudo reboot
Specify a real user name instead of <user>. To validate the driver installation, use the command:
~vainfo
Drivers for Nvidia Ubuntu¶
~sudo apt install nvidia-cuda-toolkit
To validate the driver installation, use the command:
~vainfo
Decoding AC3 Audio¶
~sudo install gstreamer1.0-libav
Deletion¶
To remove Elecard CodecWorks from your computer, follow the steps that are described for your operating system:
Windows
Open the folder
C:\Program Files\Elecard\Elecard CodecWorksand run Uninstall.exeTo complete uninstallation of Elecard CodecWorks, follow the onscreen instructions.
Ubuntu
Run the following command:
~sudo apt remove elecard-codecworks*
Features¶
CodecWorks provides the following functionality:
Adaptive streaming support over HLS/MPEG-DASH protocols;
Encoding schemas configurator;
Centralized control over several encoding servers via GUI and web-interface;
Accelerated GPU-based encoding for highest density possible;
Mechanism for quick back up in 1+1, N+1, N+M modes;
Redundancy mode and immediate automatic changeover to a redundant source in case of absence of input stream, CC errors, or if PID loss occurs;
Error notifications over the SNMP protocol;
Activation of the Color Bar Generator in case of absence of stream input, CC errors, or if PID loss occurs.
Integration with the CAS DRECRYPT system for reliable protection of content from unauthorized access.
Ability to overlay logo, change resolution and frame rate, convert interlaced video to progressive video, adjust audio levels.
Product Structure Description and Module Purpose¶
One operating system may contain only one encoding server that enables the following modules:
Encoding console is a software designed to create (start) the encoding schema. Receives and processes the control commands from the manager (via an intermediary — CodecWorks dispatcher), as well as controlling the license restrictions. One or more per server, depending on the number of licenses purchased. The encoding console is represented by a task in the web interface.
Dispatcher is a software (a console or a system service, depending on the user’s choice) that monitors encoding consoles, their initial startup, emergency restarts, communication with other devices on the network, and obtains server load statistics. One Channel Manager is run on one server.
Watcher is a software (a console or a system service, depending on the user’s choice) that monitors the dispatcher operation, emergency restart. Watcher, dispatcher, encoding consoles can be started as a system service or the console applications, depending on the user’s choice.
CodecWorks Manager is a GUI software that controls the operation of the encoding console, configures and starts the encoding schema according to user actions and collects statistics. One manager can be used to control multiple servers.
CodecWorks Manager (console) is a console application for controlling the operation of the encoding server from the command line.
Encoding schema is an XML document that contains all the information about the structure of DirectShow encoding graph or GStreamer pipeline and its settings (is a counterpart of GRF file used by Graph Edit application). Usually the schema can only be used on a specific server and with a specific input stream.
Encoding schema configurator is a module designed to create encoding schemas based on a set of predefined sections. Each section is a fragment of the encoding graph, describing its structure and parameter values, designed to perform a specific function (stream reception, decoding, encoding, etc.). In addition, templates can be used to prepare schemas.
Template is an XML document that is used for creation of encoding schema. It contains the limited set of sections defining the range of encoding tasks for which the template is designed. The use of templates is advisable in cases when complex non-standard encoding schemas are required. Templates are prepared by Elecard specialists.
Web Interface¶
Authentication and Managing User Roles¶
The Administrators group is default and cannot be deleted. To create a new group, click the Add Group button, and specify a group name. To save changes, click the Apply button. When clicking a group in the right part of a page, the settings of a group will open. The Permissions tab sets permissions for actions with the CodecWorks service and with encoding consoles. In the Users tab, there are list of group members. In this tab, you can create a new user, or change a password for the Administrator. To set a new password, click Administrator and click the Edit User icon.
Task Configurator¶
To open a task creation page, click the 
button in the Home page.
Then add a Source and select the input protocol. Specify the required fields Multicast address/port and click the Apply button. The IP (demux) input stream type implies UDP/RTP/SRT/RIST protocols with subsequent demultiplexing for further stream processing.
After specifying data, CodecWorks tries to receive a specified stream and shows available streams in the window. At this point, some programs can be excluded from a stream. Next, go to the created Transform element and select from pre-prepared templates the action to be performed with the stream. Now you need to select a streaming protocol. Go to an Output element and select required fields for streaming. You can change a schema name and save changes. After a task creation, it will appear in the list of inactive tasks. You can activate it manually.
Note
To prepare multi-bitrate tasks, the templates for multi-profile tasks should be added to installation packet. You can contact technical support to add the necessary templates for a specific task.
To create a task with a redundant source, before saving a task, you need to add the second source with the IP(reserving) type. Specify the required fields for a redundant source, and CodecWorks will use this source for redundancy.
Managing Task¶
As soon as a task is created, it appears in the list of inactive tasks. When hovering a task, the available actions such as Start/Stop/Restart are displayed. To delete inactive tasks, select tasks and click the Delete button. In the same way, you can enable/disable the manual mode for the CBG, or enable/disable the automatic enabling of the CBG. When clicking a task name, a page with statistics and task parameters will open. On this page, you can view an events journal of a particular task. If the input stream has been changed, you can edit the encoding process by clicking the Rebuild button.
Configuring Server¶
On the Service settings page in the General tab, you can change Service name, Multicast address for searching CodecWorks services in the network, IP address that will be used for that, and IP address of a web interface. The parameter Service start delay (s) specifies the delay before start of a CodecWorks service.
Note
When 0.0.0.0 is specified as the network interface, all available network interfaces will be used.
Configuring Service Redundancy¶
In the Source Redundancy tab, there are settings of conditions under which CodecWorks switches to a redundant source. Failover to a redundant source occurs when one of the following events take place:
CC Errors — occurs if 15 or more errors are detected every second for 5 seconds. The state ends when no errors are detected for 10 seconds.
No video signal/ no audio signal — implies the PID Loss/PMT changed states and the absence of audio/video data for 3 seconds. The state ends when video data becomes present for 3 seconds, and audio data is present for 2 seconds.
In case the source has not any redundant sources and one of the events occurs, the CBG will be enabled if this option is allowed for consoles.
The Switch back to primary source option allows reverse switching to the primary source when it restores. If the “When necessary” flag is set, the primary source takes priority. When the primary source is lost, switching to the redundant source is performed. Reverse switching is carried out as soon as the primary source signal restores. Otherwise, the current source is considered to be the one that is currently available.
Log and Rotation Settings¶
The Log and Rotation Settings window is subdivided into two tabs. In the Logging tab, you can specify a folder for storing logs and set logging levels for dispatcher, SNMP, and for consoles events. For logging consoles settings, you can set the same logging level for all consoles or select the logging level for the one console.
In the Rotation tab, you can set storing period and limit the size for log files, crash dumps, and redundant copies:
Log files — records of system messages into the log.
Crash dumps — process dumps in various situations caused by incorrect operation.
Redundant copies of schemas — schemas saved as backups in the console
/backupfolder after each schema setting change so that these changes can be reversed.
You can also specify a rotation period for log files, which is measured from the dispatcher start. During rotation, the storing period and size of files are checked. The files exceeding set thresholds will be deleted.
SNMP¶
Configuring SNMP Agent¶
Install the SNMP service:
~sudo apt-get install snmpd
Specify a community and path to a CodecWorks agent in the etc/snmp/snmpd.conf file:
rwcommunity elecard rocommunity elecard
In the file end, add path to the agent:
dlmod libcwSnmpAgent /bin/Elecard/CodecWorks/libcwSnmpAgent.so
Restart the SNMP service:
sudo systemctl restart snmpd.service
Configuring SNMP notifications¶
In CodecWorks, there is a possibility to send SNMP notifications to a desired trap point.
The installed version of CodecWorks contains two MIB files:
To configure SNMP notifications, go to Settings ➝ SNMP Settings.
The Add community button under the Communities column allows adding a name of your SNMP community.
The Add host button under the Hosts column allows adding destination addresses where traps for a chosen community will be sent. If usage of several destination addresses is required, repeat the procedure of hosts adding.
There are two types of trap notifications:
Application events — this notification type occurs one time. Application events are mostly connected with a state change. For instance, in the failover to a redundant source.
States — notify about the beginning and the end of the event. State is transmitted to the Status field, which may have active/cleared value. Notifications are sent twice: when entering an event by specific triggers and when exiting an event.
With trap notifications, CodecWorks can report about the problems related to an input stream, the start/stop of encoding schema work, a changeover to a redundant source, etc. In the Severity Levels tab, you can select console states and stream events that should be monitored. To enable or disable monitoring an event, select an appropriate value from the dropdown list in the Status column. In the Active/Cleared Level column, you can set a severity level that will be assigned to an event when it will be registered.
Structure of SNMP Notifications¶
There are four types of SNMP trap-notifications described in the ELECARD-CODECWORKS-MIB.mib file.
1. Notifications about changing CodecWorks service state (codecWorksState)
Such notifications characterize a certain state of the service and are sent twice: when an event occurs and when it ends. The notification contains the following fields:
status — a state status (active — if a state has occurred, cleared — if a state has ended);
trapName — a notification name;
trapMessage — a detailed description;
severityLevel — a severity level;
referenceNumber — a sequence number;
sequenceId — a parameter combining a start and end of a state (a state identifier is unique for each pair of notifications).
2. Notifications about events that has occurred with the CodecWorks service (codecWorksEvent)
These notifications imply the occurrence of some event, and are sent once when the event occurs. The notification contains the following fields:
trapName — a notification name;
trapMessage — a detailed description;
severityLevel — a severity level;
referenceNumber — a sequence number.
3. Notifications about changing state of CodecWorks encoding consoles (codecWorksChannelState)
Such notifications indicates a certain state of the encoding console and are sent twice: when an event occurs and when it ends. The notification contains the following fields:
status — a state status (active — if a state has occurred, cleared — if a state has ended);
trapName — a notification name;
trapMessage — a detailed description;
severityLevel — a severity level;
channelNumber — an encoding console number;
taskName — an encoding schema name;
referenceNumber — a sequence number of a notification;
sequenceId — a parameter combining a start and end of a state (a state identifier is unique for each pair of notifications).
4. Notifications about events of an encoding console (codecWorksChannelEvent)
These notifications characterize an event occurrence and are sent just once when an event happens. The notification contains the following fields:
trapName — a notification name;
trapMessage — a detailed description;
severityLevel — a severity level;
channelNumber — an encoding console number;
taskName — an encoding schema name;
referenceNumber — a sequence number of a notification.
Values of some fields can vary. The severityLevel field can take following values:
ok (1);
warning (2);
error (3);
major (4);
fatal (5).
Values of some fields trapName and trapMessage are described in the Table 1.
trapName |
trapMessage |
Description |
|---|---|---|
Backup server |
Host <host:port> is down, backup started |
Backup server start |
Service start |
Service started |
Service start |
Service stop |
Service stopped. <reason> |
Service disabling |
Console stop |
<reason> |
Stop of encoding console |
Channel error |
<reason> |
Error when transcoding |
Stream switch |
Stream switch |
Switching to other source |
Channel start player error |
<reason> |
Encoding start error |
Channel start error |
<reason> |
Encoding console start error |
Transcoding stop |
Transcoding stopped |
Transcoding stop |
Transcoding start |
Transcoding started |
Transcoding start |
No video signal |
Stream <stream number> - no video |
No video signal |
No video decoded |
Stream <stream number> - no decoded video frames |
Video stream cannot be decoded |
No audio signal |
Stream <stream number> - no audio |
Audio signal is not found |
No audio decoded |
Stream <stream number> - no decoded audio frames |
Audio stream cannot be decoded |
No input |
Stream <stream number> - no input |
Input stream is not found |
No output |
Stream <stream number> - no output on HLS Stream
Stream <stream number> - no output on DASH
|
HTTP protocol error when trying sending a segment |
TS errors |
Stream <stream number> - CC errors |
Errors in transport stream |
Color bar |
Stream <stream number> track <track number> - generating color bar
Stream <stream number> track <track number> - generating silence
|
Enabling the CBG by video or silence in audio streams |
Configuring Thresholds¶
You can apply your threshold configuration to tasks (encoding consoles). When exceeding these thresholds, some actions should be taken. The default configuration is Common.
Conditions for console automatic restart:
By time — restart the console every N minutes, the console will be restarted in the specified time period.
By used CPU time — restart the console when CPU load decreases and continues for the specified time.
By exceeding used RAM — restart the console if the CPU load exceeds the specified threshold for 5 seconds.
Log statistics every N seconds — console log records task statistics for each specified period.
Level of console logging — levels are cumulative, so that the lower trace level includes all previous logging levels. The recommended info level is set by default.
Configuring Server Redundancy¶
During operation, the backup server monitors the operation of the main server by periodically sending special signals to it and monitoring the receipt of responses. If there are no responses from the main server within a configurable period of time, the redundant server launches pre-configured encoding channels under its control. One redundant server can duplicate several working encoding servers (N+1 model). Several redundant servers can serve the same set of working servers (N+M model).
In the Home page, click the Redundancy button. The redundancy page contains two columns:
Main Servers — main nodes to be backed up by redundant servers.
Redundancy Servers — redundant servers that will start in case of problems with main servers.
When clicking the Add button, you can add one or several in the list. When the list is created, click the Save and Exit button. Server redundancy will be set up.
Note
By default, the server on which the redundancy is configured is automatically included in the list of backups.
Redundant server will start in case if connection to the working CodecWorks server is lost, i.e. when a dispatcher of a redundant server stops receiving responses from a dispatcher of a main server.
By clicking Settings on the Redundancy page, the Redundancy Settings window opens. You can configure update of schemas on the redundant servers, timeout for switching to the redundant server and triggers that will be used for switching.
If the Update schemas on redundant servers by time option is enabled, encoding schemas for redundant servers are automatically updated with the specified period after the service start or starting from the set time. Schemas can be updated at a specified interval after service start, the another option is to update schemas starting from the time specified by a user.
Number of failed requests — number of consecutive failed requests within the TCP session. If the specified number of failed requests in a row is reached, a redundant server will start.
Request timeout (milliseconds) — time between requests within the TCP session.
Failover timeout (milliseconds) — calculated parameter defining time of a problem detection on a primary server and failover to a redundant server.
Setting conditions for the server deactivation — functionality that provides switching to the redundant server if one of the specified conditions is satisfied. Deactivation settings are applied to the current server and other servers in a redundancy group. There are the following conditions for deactivation of the server and subsequent switching to the redundant server:
No input streams detected — when this condition is chosen, the server will be deactivated if there are no input streams for all active consoles.
Failure of publishing segments over WebDAV — when this condition is chosen, the server will be deactivated if all active consoles fail to publish OTT segments via WebDAV to the origin server.
CPU Usage — when this condition is chosen, the server will be deactivated if the specified CPU load threshold is exceeded within the set period.
Setting Action if conditions are met helps to configure a server behavior. If one or some conditions occur, a server can become a redundant or go to a deactivated state.
Note
You can set the server as a redundant server only for 1+1 redundancy mode.