Source failover¶

For various reasons, a video source may temporarily disappear or even become offline. To avoid a situation where consumers do not have any video, it is necessary to prepare alternative stream sources in order to broadcast them in the absence of the main source until it is restored. Flussonic provides seamless automatic source switching.

On this page:

• Redundant sources
• Failover conditions
• Options for configuring source failover
• Changing sources manually
• Recording to an archive
• Using a file as a redundant source
• How 'backup' is different from 'input file://'
• Failover file options
• Transcoding a failover file
• Emergency button

Redundant sources¶

To maximize service uptime for your subscribers, you can use the Source Failover feature. By specifying multiple sources, you instruct Flussonic to automatically failover to the secondary data sources if the primary source becomes unavailable. Flussonic supports using video streams and files as secondary sources.

Source switching happens when the stream becomes disconnected, or when there are no incoming frames from the source for more than 60 seconds (and 180 seconds for hls://, playlist://, timeshift:// sources).

How source failover works¶

After Flussonic Media Server switches to a secondary source, it will periodically check if the first source is up. When the first source comes back online, Flussonic will fall back to it.

Example

The stream example_stream has two sources. If no frames come from the first source for 20 seconds, then Flussonic will switch to the second source.

stream failover_example_stream1 {
  input udp://239.0.0.1:1236 source_timeout=20;
  input tshttp://localhost:80/clock2/mpegts;
}
stream clock1 {
  input fake://fake;
  push udp://239.0.0.1:1236 multicast_loop;
}
stream clock2 {
  input fake://fake;
}

Failover conditions¶

Flussonic monitors only the time since last frame was received from the source, and switches to another source if there were no incoming frames received within a certain timeframe.

Flussonic doesn't monitor conditions like video or audio loss or increased volume of MPEG-TS CC errors.

Options for configuring source failover¶

source_timeout¶

The source_timeout option specifies the period of time, in seconds, for which Flussonic will wait for new frames until it considers the source as lost. The default timeout is 60 seconds (180 seconds for hls://, playlist://, timeshift:// sources).

You can specify source_timeout for both the entire stream and for each of the video sources. The source_timeout option of a video source has priority over the source_timeout option of its parent stream. Example:

stream backup_timeout {
    input publish:// source_timeout=10;
    input fake://fake source_timeout=5;
    source_timeout 20;
}

If you think that switching occurs too often, you can increase the source_timeout so that there are no "jumps" from one source to another. On the other hand, in order not to wait for a long time until Flussonic switches to another source, you can reduce the timeout.

The timeout is not taken into account when you switch sources manually.

priority¶

You can assign priorities to stream sources, and Flussonic will take priorities into account when switching to another source. The source with priority=1 has the first priority, the source with priority=2 has the second priority, and so on.

By default, the first source in the list has the highest priority and the last source in the list has the lowest priority. If priority is not specified for some sources, then the default order is applied.

Flussonic checks priorities only after it determines all sources that are active.

If the priority of an unavailable (offline) source is equal to the priority of the currently played source, then Flussonic will not try to fall back to the source that has become unavailable.

stream example_stream {
  input fake://fake priority=2 source_timeout=30;
  input tshttp://10.2.4.5:9000/channel/5 priority=1 source_timeout=10;
}

The rules of switching sources according to their priority and state (whether a source is available or not) apply to published sources as well as any other ones.

Changing sources manually¶

Flussonic supports manual source switching.

To change the source of a stream manually, without waiting for the timeout:

• In the stream settings, change the order of sources. Use this if priority was not specified.

For example, move the second source up, and Flussonic will switch to it.

• In the stream settings, edit the priority of sources

For example, set priority=2 instead of priority=1 and priority=2 instead of priority=1, and Flussonic will switch to the source with the highest priority.

• Enable another source via the API.

Recording to an archive¶

If a DVR location is configured, Flussonic will start archiving video from the active source.

The system makes no distinction between live sources and local video files. If Flussonic has switched to a file source, the contents of this file will be written to archive.

It is possible to use a static video as a failover data source.

stream backup_example_stream1 {
  input tshttp://example.com/origin;
  input file://vod/bunny.mp4;
  dvr /storage;
}

In the example above, the fallback video file would be written to the DVR archive. To avoid writing a fallback video file to the archive when all of the sources are down, you should use the backup directive instead of a static video URL. See also further on this page.

Using a file as a redundant source¶

You can use static video (video files) as a failover data source.

Files can be specified in two different ways, each leading to a certain behavior of Flussonic at source failover.

Using the input file:// schema to list a file as one of stream sources¶

  stream backup_example_stream2 {
    input tshttp://10.0.4.5:9000/channel/5;
    input file://vod/bunny.mp4;
  }

Flussonic supports MP4 and MPEG-TS files (.ts).

Using the backup option to set a file as the failover data source¶

To set a file as a failover data source for the main stream, use the backup option. Flussonic shows this file without actually switching sources. This is useful in certain cases. Learn more

  stream backup_example_stream3 {
    input tshttp://10.0.4.5:9000/channel/5;
    backup vod/bunny.mp4;
  }

How 'backup' is different from 'input file://'¶

Unlike source switching with the source input file://<VOD location>, when a fallback file is used, Flussonic technically does not switch to another source. This is especially useful for published streams to prevent numerous closings of a socket with a publishing client.

The fallback file specified in backup <VOD location> is not transcoded and not written to DVR, unless you configure otherwise. The file source input file://<VOD location> is always written to DVR.

When use backup instead of input file://:

• In case of poor connection with the client that publishes video, Flussonic continues to receive frames without interrupting the connection with the client. This allows the client to continue the publishing session without having to start it over each time the source was switched. When the published stream disappears, viewers see the fallback file and understand that the broadcast is not over yet.
• When all sources are unstable and Flussonic switches between them too often, it is better to show a fallback file. If you use a file as one of the sources, viewers will see any video only after timeouts pass for each of the troubled sources.
• If you write the main stream to DVR and do not want to write the file too in order to prevent the file from appearing in the archived video.
• Using options like timeout for the main stream and the fallback file, you can manage which source to show during a publication session.

Failover file options (backup)¶

The fallback file takes the following options:

stream example {
    input udp://239.0.0.1:1234;
    backup vod/bunny.mp4 video_timeout=5 audio_timeout=10 timeout=20 dvr=true transcode=true;
    dvr /storage;
}

dvr=true¶

If the main stream has a configured DVR, then the fallback stream will be recorded to the archive too:

stream example {
    input udp://239.0.0.1:1234;
    backup vod/bunny.mp4 dvr=true;
    dvr /storage;
}

timeout=10¶

The time (in seconds) for Flussonic to switch to the fallback source if the main source stops sending frames. The important thing here is that the source remains active (connected), allowing for a client-publisher to stay on the socket.

This option takes any type of frame into account.

Flussonic can switch to a fallback source only when there are no frames of a certain type (video or audio) coming, which allows better control of source switching. You can different timeout intervals for different frame kinds. To take into account only audio or only video frames, use the options audio_timeout or video_timeout (see further in this list).

If you do not specify timeout specifically for a fallback source, then in the absence of frames, source_timeout of the main source will be used.

By using timeout andsource_timeout together, you can:

• Set a longer timeout so that mobile clients manage to start streaming without being disconnected
• At the same time, switch to the fallback source as soon as possible.

For example, a WebRTC client app will stay connected for the specified time when the source stops sending frames. The fallback file is played during this time.

Example:

stream example {
    input publish:// source_timeout=20;
    input fake://fake;
    backup vod/bunny.mp4 timeout=1;
}

In this example:

Before the publication begins, the fake stream is played. Then the client app connects to Flussonic to stream video to it. If, after the connection was established, no frames arrived from the client during 20 seconds, then the client is forcibly disconnected and the demo source starts playing.

After the start of publication, if for 1 second there are no frames from the published stream, the file backup-file.mp4 starts to play. However, the publication source is not disconnected yet.

When the source resumes sending frames, the stream switches to the publisher client and the published video is played. However, if the source does not resume sending frames during 20 seconds, then the publisher client is forcibly disconnected and the demo source starts playing.

video_timeout=5¶

The time (in seconds) for Flussonic to switch to the fallback source if the main source stops sending video frames.

If you specify video_timeout,audio_timeout and at the same time timeout of the main source, switching will be triggered by a timeout, which will occur first. These options have the same priority.

audio_timeout=10¶

The time (in seconds) for Flussonic to switch to the fallback source if the main source stops sending audio frames.

If you specify video_timeout,audio_timeout and at the same time timeout of the main source, switching will be triggered by the timeout that occurs first. These options have the same priority.

transcode=true¶

See Transcoding the Failover File further on this page.

Transcoding the failover file¶

transcode=true¶

If the main stream is transcoded, then the fallback file will be transcoded too with the same parameters as the main stream.

stream backup_transcode {
    input udp://239.0.0.1:1235;
    source_timeout 5;
    backup vod/bunny.mp4 transcode=true;
    transcoder vb=1000k ab=64k;
}

This allows you to change transcoding parameters without the need to transcode the fallback file with new parameters. This also makes it unnecessary to prepare several fallback files with different bitrates.

Emergency button¶

You can configure an emergency button in Flussonic.

Emergency button is a mechanism, used to manage the start/stop of the stream source.

Flussonic checks emergency button status before starting the stream source.

To set an emergency button you should specify a path to the file, that will be providing information, using one of the two parameters for the source url in the stream settings: allow_if or deny_if.

Under what circumstances will the source start?

• File specified through allow_if contains 1 in it (allow_if=/PATH/TO/FILE carries 1).
• File specified through deny_if contains 0 in it (deny_if=/PATH/TO/FILE carries 0).

Therefore, in all the other cases the source will not start. Such as:

• File specified through allow_if contains 0 in it (allow_if=/PATH/TO/FILE carries 0).
• File specified through deny_if contains 1 in it (deny_if=/PATH/TO/FILE carries 1).
• File contains any other values except from 1 and 0.
• File does not exist.

The confuguration may look as follows:

stream example_stream {
    input m4f://FLUSSONIC-IP/STREAM_NAME deny_if=/PATH/TO/FILE;
    input udp://239.0.0.2:1236 allow_if=/PATH/TO/FILE;
}

In the example above we set 1 emergency button (/PATH/TO/FILE) to 2 sources (m4f:// and udp://239.0.0.2:1236). If /PATH/TO/FILE contains 1, then m4f:// source will not start, whereas udp://239.0.0.2:1236 will. Hence, if /PATH/TO/FILE contains 0, then m4f:// will start, whereas udp://239.0.0.2:1236 will not.

Summing up ("+" — source starts, "-" — source stops):