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.

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 many 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 {
    input 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.

Templates

We decided to make the configuration of many 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 {
    input udp://239.255.0.1:1234;
    template t1;
}
stream channel2 {
    input 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 {
    input udp://239.255.0.1:1234;
    template t1;
    dvr s3://minioadmin:minioadmin@minio:9001/test 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 on_play,url_prefix, cluster_key could have been specified for all streams at once, but then there was a problem with exceptions control.

on_play http://middleware_example/auth;

stream channel1 { # the stream uses global auth
    input udp://239.255.0.1:1234;
}
stream channel2 { # the stream overrides global auth with local defined
    input udp://239.255.0.2:1234;
    on_play 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.

stream channel1 {
    input udp://239.255.0.1:1234;
    on_play http://middleware_example/auth;
}
stream channel2 {
    input udp://239.255.0.2:1234;
    on_play 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 {
    on_play 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

This option 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.

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 (input publish:// is crucial here):

template example_template {
  prefix foo;
  prefix bar;

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

It is possible to use a special empty prefix (""). In this case the template allows to publish a stream with any prefix or even without a prefix.