Skip to content

Stream Configuration Templates

Stream configuration templates in Flussonic help you manage settings of a large numbers of streams.

Flussonic configuration file

The Flussonic's entire configuration is stored in a single file — /etc/flussonic/flussonic.conf. The configuration has its own format, it is not JSON, YAML, or INI, but it is very simple and easy to read, which is why Flussonic Administrators often open the file and read it. Reading this file is faster than opening several pages in the web interface; configurations of a dozen streams are shown on a single screen of a text editor, and all global settings are immediately visible.

The simple syntax of the configuration file makes it convenient for editing too. Advanced Flussonic users often write the configuration in a text editor, the same way as they do when working with other server software, such as web servers.


http 80;
edit_auth flussonic password;

stream example {
    url udp://192.168.0.1:5000;
    dvr /storage 7d;
}

This is an example of a real configuration, where six lines are enough to define the port that Flussonic will listen on, set a password for the web interface, create a stream and configure its recording.

Prior to Flussonic 21.03

When there are more than 10-20 streams, not to mention hundreds, duplicate lines can appear in the configuration because the same options are applied to several streams:


stream channel1 {
    url udp://239.255.0.1:1234;
    transcoder vb=1000k deinterlace=true ab=128k;
    dvr /storage 1d;
}
stream channel2 {
    url udp://239.255.0.2:1234;
    transcoder vb=1000k deinterlace=true ab=128k;
    dvr /storage 1d;
}

Despite the fact that the configuration is perfectly readable, Administrators had to spend time monitoring the state of the configuration so that none of the streams lost options, or that an option only applied where needed. These time costs are especially noticeable when there are more than 2-3 servers, and when each server has a distinct role: a transcoder, a recorder, or a restreamer.

Templates introduction in Flussonic 21.03

We decided to make the configuration of a large number of streams more convenient. In Flussonic 21.03 we introduced configuration templates, the template section and the template option. This is what the same example looks like now:


template t1 {
    transcoder vb=1000k deinterlace=true ab=128k;
    dvr /storage 1d;
}
stream channel1 {
    url udp://239.255.0.1:1234;
    template t1;
}
stream channel2 {
    url udp://239.255.0.2:1234;
    template t1;
}

All general settings of streams are placed in a separate section, and only unique settings are defined within a stream. If there are at least 10 streams, you can already see how much more compact flussonic.conf becomes.

What's more, it is enough to assign the template to a stream once, and then work only with its configuration. This way, synchronization of stream settings on a cluster of transcoders will be reduced to copying the template between servers.

The template section supports the same options as the stream section.

Settings overriding in stream configuration

If one of your streams needs to override any of the parameters defined in the template, this can be done as follows:


template t1 {
    transcoder vb=1000k deinterlace=true ab=128k;
    dvr /storage 1d;
}
stream channel1 {
    url udp://239.255.0.1:1234;
    template t1;
    dvr s3://example.com 3d;
}

The local configuration of the stream channel1 has a priority over the setting from template t1. We recommend using this for testing or in rare cases because otherwise the templates will lose their purpose, a large number of overrides will return you to the situation when you had to manually track the configuration of each stream.

Global options of streams

Options such as auth,url_prefix, cluster_key could have been specified for all streams at once, but then there was a problem with exceptions control.


http 80;
auth http://middleware_example/auth;

stream channel1 { # the stream uses global auth
    url udp://239.255.0.1:1234;
}
stream channel2 { # the stream overrides global auth with local defined
    url udp://239.255.0.2:1234;
    auth securetoken://key;
}

In practice, it often turned out that not all streams needed to inherit the general configuration, and Administrators refused to use it. Explicit definition is clearer, better readable, and less error prone than implicit inheritance.


http 80;

stream channel1 {
    url udp://239.255.0.1:1234;
    auth http://middleware_example/auth;
}
stream channel2 {
    url udp://239.255.0.2:1234;
    auth securetoken://key;
}

Global options are very similar to templates, right? Therefore, starting from 21.03 you will see the message:


# Stream templates:
# Template globals currently applies to all streams without templates.
# This will change in future, explicit template usage is recommended.
#template globals {
    auth http://middleware_example/auth;
#}

In this release we will leave this unchanged but we plan to move the configuration to a separate template soon, which will be used by all streams without the specified template.

It becomes clear now that a stream can inherit configuration from only one template: either an explicitly specified one or global one, but not from both.

What next?

Templates will become key elements in managing a group of servers. We will work on their representation in the Flussonic UI to make template streams look as clear as in the configuration file. We also plan to add unique features to templates, for example, wildcards and 'on action' events that will allow you to implement very flexible scenarios. Flussonic Catena will manage templates, not per-stream configuration.

We are waiting for your feedback! Please contact technical support for any questions — we will show you how to apply new features in your scenario and expand the description.