Skip to content

Using an external dynamic source of stream configuration

This information will be useful if you run a service where there are many Flussonic servers and thousands of ondemand-streams, and the stream configurations are being constantly updated. Here we describe how to provide stream configurations to Flussonics from a centralized external storage.

The business context is the following:

  • Your service uses a number of servers with Flussonic
  • There are up to several thousands ondemand published streams in total
  • There are thousands of users who request streams
  • Streams are published to Flussonic and can be restreamed to other destinations
  • The configuration files are frequently updated because published streams are created and deleted all the time.

Keeping configurations of all streams in a single file is not the best solution because with growing numbers of streams, the load on each Flussonic would be increased.

The solution is to store a stream's settings in a centralized external system and pass them to exactly that Flussonic server that is going to receive a certain published stream.

Thus, Flussonic does not need to have any information about streams that will be published on it. When Flussonic receives a request from a client device to play a stream, it first searches for the stream in the configuration file locally and if there is no such a stream, Flussonic connects to a special backend on the external server. The backend returns requested stream configurations.

Users add streams to the system before they are going to publish them, and the system thus has the settings for these streams. At the start of publication, Flussonic can get the necessary settings from the backend, which extracts them from the external system.

Plugin configuration

To organize the use of an external stream configuration source::

  1. Develop your own centralized system for keeping streams configurations and a backend for interactions with Flussonic servers. This backend will provide information about streams that you store and update in your system, external in relation to Flussonic.

    First, this backend must accept requests for a stream configuration that Flussonic sends in the JSON format:

    {"streams": ["stream_name1", "stream_name2", ... "stream_nameN"]}

    The key "streams" contains the list of stream name whose configurations Flussonic requests.

    And then this backend must return the JSON object with the settings of requested streams (in the same format as used by Flussonic in the API call modify_config /flussonic/api/modify_config). Response example:

    { "streams": { "stream_name2": { "urls": [ { "url": "fake://fake" } ] } } }

    The key streams contains the object.

    If the stream's configuration was not found, the backend returns null.

    The protocol of interaction of Flussonic and the backend will be described in more detail later.

  2. Add the config_remote plugin on each Flussonic server. To do so, add the following lines to /etc/flussonic/flussonic.conf:

plugin config_remote {
    backend http://backend1/ timeout=3;
    backend http://examplehost:5000/configuration timeout=3;
    refresh_interval 30;
    default failover_stream_name;

  • backend — Flussonic connects to the specified backend to get stream configurations. It connects only if it does not find an ondemand stream, published location, or VOD location with the requested name in its local cache. Flussonic connects to another backend if the previous one did not return the requested streams.

  • refresh_interval (optional) — The interval at which Flussonic periodically checks for configuration updates from the external system and refreshes the configurations of currently active streams.

  • default (optional) — The stream whose settings are passed to Flussonic if all the backends are not responding. This stream must be specified in the local configuration file as a stream.

The backend URL must end with a slash (/).

The default stream

If all the backends do not respond, or if the requested stream was not found, Flussonic switches to the default stream. This stream must be specified on the Flussonic where you configure the plugin as a stream (not as a VOD file).

ondemand failover_stream_name {
  url file://vod/bunny.mp4;
plugin config_remote {
  backend http://examplehost:5000/configuration timeout=3; 
  default failover_stream_name;

External streams in the Flussonic UI

The Flussonic UI shows the "external" streams that were started on this Flussonic through the config_remote plugin.

These streams are not added to the configuration file but stored in the local cache memory. Flussonic periodically checks if the stream configuration was updated in the external system and updates the local configuration accordingly.

The list of such streams can also be found via API /flussonic/api/read_config in the ephemerals section.

The configuration of such external streams cannot be edited on this Flussonic. The only allowed action is to stop a stream.

If a stream was working when all the backends got down, then the configuration of this stream will not change and the stream will go on playing.