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’’).

For sales and licensing information, contact the Elecard Sales Department.
For technical support, contact the Elecard Technical Support Team.

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

  1. Run Elecard CodecWorks Setup and follow instructions.

  2. The software will be installed to C:\Program Files\Elecard\Elecard CodecWorks

  3. Created 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
The software will be installed to /usr/bin/Elecard/CodecWorks.
Created schemas will be saved in /etc/Elecard/CodecWorks.

Note

For the correct installation of the product, Internet access is required to download dependencies.

  1. Server - the server part of CodecWorks responsible for the work of tasks, transcoding/multiplexing.

  2. Base - the base installation includes a console manager for managing CodecWorks, this variant is suitable for scripting.

  3. GUI - the graphic control application.

  4. 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
The software will be installed to usr/bin/Elecard/CodecWorks.
Created schemas will be saved in /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

  1. Open the folder C:\Program Files\Elecard\Elecard CodecWorks and run Uninstall.exe

  2. To 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

Authorization and managing user roles

User authentication is used for differentiation of access rights between various user groups. Additionally, it provides the possibility to identify the author of changes.
When launching CodecWorks for the first time, use the default credentials to log in the web interface: username - Administrator, password - admin. To change a password or add a new account, go to a user page.
To open a user page, click a username in the right upper corner and select the Security Settings option from the menu. In the left part of a window, there are groups of users. Groups unite users with similar management rights.

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 Create_task_button 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 /backup folder 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.

Events for CodecWorks service and active tasks.
States of CodecWorks service and active tasks.

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.

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:

  1. Main Servers - main nodes to be backed up by redundant servers.

  2. 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.