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 two ways to activate Elecard CodecWorks described below:
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 (CentOS 7.9/Ubuntu 20.04)
SSD/HDD from 256 GB
ОЗУ 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.
CentOS
Make sure the repository project is installed on the system, or install it:
~sudo yum install epel-release
Run the installer:
~sudo yum install Elecard-CodecWorks*.rpm
usr/bin/Elecard/CodecWorks./etc/Elecard/CodecWorks.Note
For the correct installation of the product, Internet access is required to download dependencies.
Deletion¶
To remove Elecard CodecWorks from your computer, follow the steps that are described for your computer system:
Windows
Open the folder
C:\Program Files\Elecard\Elecard CodecWorksand run Uninstall.exeTo complete uninstallation of Elecard CodecWorks, follow the onscreen instructions.
Ubuntu/CentOS
Run the command for Ubuntu:
~sudo apt remove elecard-codecworks*
for CentOS:
~sudo yum erase elecard-codecworks
Features¶
CodecWorks provides the following functionality:
Adaptive streaming support over HLS/MPEG-DASH protocols;
Encoding schemas configurator;
Сentralized 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.
Web interface¶
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.
Setting of logging and rotation¶
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¶
In CodecWorks there is a possibility to send SNMP notifications to a desired trap point.
Configuring SNMP notifications¶
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-notiications 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 occured, 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 occured, 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 |
Described |
Backup server |
Host <host:port> is down, backup started |
Enabling of a backup server |
Service start |
Service started |
Service enabling |
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 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 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.