Skip to content

Stream Configuration Templates

With an increasing number of streams with similar settings (10+), it becomes a challenging task for an Administrator to manage. Keeping an eye on every stream and adjusting the settings of every stream is ineffective and time-consuming. It also increases the likelihood of making a mistake or missing something. That is where stream configuration templates or just templates come in handy.

Stream configuration template defines a set of settings to be applied to several streams to provide a more organized and manageable way of configuration for the streams.

So the advantages of using templates are:

  1. Configuration pieces reusability.

  2. Decomposing complex configurations into simpler and more manageable pieces.

  3. Decreasing duplication of configuration settings.

  4. Simplifying change management to duplicate pieces of settings for different streams.

  5. Increasing clarity and readability of the configuration.

  6. Reducing the amount of time and effort to manage configuration settings and keeping it up-to-date.

All in all, stream configuration templates in Flussonic help you manage the settings of a large number 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.

Templates and prefixes

Following option is similar to live, that is connected with dynamic names for the streams. Template creates one publishing point with one or more publishing locations, depending on the number of prefixes you define, whereas live option only creates one publishing location for one publishing point.

Dynamic name is a term used to describe a name of a publishing stream not known to Flussonic in advance.

prefix is used to form a stream name. The general structure for a stream name is as follows: PREFIX/STREAM_NAME.

So the configuration may look like this (url publish:// is crucial here):


template example_template {
  prefix foo;
  prefix bar;

  url publish://;
  backup priv/bunny.mp4;
  source_timeout 2;
}

We specified two prefixes in example_template: foo and bar, which enabled a backup file and a source timeout.
So when you publish the stream to Flussonic, the name of the stream will have one of the two possible formats, depending on chosen publishing location: foo/STREAM_NAME or bar/STREAM_NAME.
For example, if you publish an RTMP stream to foo, the URL will look as follows: rtmp://FLUSSONIC-IP/foo/STREAM_NAME.

Simply put, all settings within the template with prefixes apply to the streams published under the name of the prefix(es) (foo/STREAM_NAME and bar/STREAM_NAME in our example).

This option also works for stream playback.