April 5, 2017

Emergency streams hot swap via Live Transcoder

Many of our customers requested us to support hot swap capabilities for live streaming scenarios.

This basically refers to use cases when there is some original (primary) stream active all the time, some substitute (secondary) stream to swap on some occasions, and either of the following actions needs to be done:

  • Emergency stream activation. The substitute stream is usually inactive but when it goes live, it must replace the original stream. Once the secondary stream becomes inactive, the original stream must be continued.
  • Failover stream. The substitute stream is active and once the original stream goes down, the data from substitute stream is taken. Once the original stream is back online, it replaces the substitute stream again.

Both cases require to make the swap smoothly from viewers point of view, which means a player must not stop the playback. Nimble Streamer handles both cases correctly. This article covers the first case.

Emergency stream hot swap is used for several cases, and the most notable example is the support of United States Emergency Alert System (EAS). It requires a broadcaster to replace any media with the content provided by EAS once it becomes available.

Let's take a look at the setup process of this capability.

Notice that RTMP, RTSP and Icecast inputs can be used in the pipeline without changes. SRT, RIST, MPEG-TS over HTTP and HLS pull need to have instant inactivity disconnect enabled.

Pipeline overview

There are two major points where we need to look at in order to understand this swapping process.

First one is about the decoding of original stream. To make streams swap smoothly with no glitches, our Live Transcoder needs to substitute the original content with new one. This can be done only during the decoding process where the encoded content is already "unfolded" but it hasn't yet been transformed by filters on further encoder. So the original stream cannot be passed through or just transmuxed.
The original stream which needs to be substituted, must always be decoded even if you encode it right after that without putting any filters on it. 
Second point is that original and substitution steams need to match in terms of viewer's perspective.
Both streams need to have equal video resolution and audio sample rate.

That being said, you will need to make a bit of a preparation for both original and substitute streams to make them be swapped properly.

Substitute stream setup

To prepare the stream you need to create transcoding scenario. Take a look at this sample one:

Video is decoded then scaled to the resolution of the original stream:

Audio should also be re-sampled to change the sample rate to the same value as in the original stream using "aformat" filter:

If two streams happen to have different audio sample rates, the sound will glitch at the moment of switching between them.

For more details on transcoding setup and usage, check our blog posts and also a set of short videos showing the process.

Now the substitution stream is ready and you can use it in original stream.

Original stream setup

As was mentioned earlier, the original stream must have all input streams to be decoded. Even if you want the stream to be passed-through, you need to add a decoder and an encoder blocks.

However in most time you need some transcoding to be done, here's one typical example. Notice the decoding for audio streams. In normal use case they should have been passed through but here you see two sets of decoding and encoding with no filtering.

Now you're ready to set up the swapping.

Hot swap settings

Now go to transcoders main page and click on Hot swap settings button.

New page will have just a New hot swap setting button.

Set up emergency for exact stream

Click on it to see a dialog for defining streams. Its pretty self-explanatory as you can tell.

Enter the original application and stream names, then Substitute application and stream names, and select Substitution type as Emergency.

Upon saving the setting, you will see it in the table.

Emergency substitution for specific stream

Set up emergency for all applications or streams

Besides specifying exact app and stream names, for emergency substitutes you may specify only an app or even not specify any original app or stream at all. In this case, all streams in the app or in general will be replaced upon receiving the incoming emergency stream.

Of course, you will still need a transcoding scenario for all original streams that are planned to be replaced.

Notice that wildcard streams in transcoder will not work for this case.

Emergency substitution for all streams in the application
But from hot swap rules perspective this will be just 1 simple rule.

That's it. Now whenever the substitute stream becomes available, it will replace the original stream. And once it's down, the original stream content will become available again.

Check the next article to see how you can use same feature for streaming failover setup.


There are cases when bandwidth goes unexpectedly too high right after the streams swap. This can be fixed by setting a maximum bandwidth limit in your transcoding scenario. You can use the approach described in "How to set up CBR (Constant Bit Rate)" section in this article.

Please also read Troubleshooting Live Transcoder article which described some corner cases.

Feel free to visit Live Transcoder webpage for other transcoding features description and contact us if you have any question.

Related documentation


  1. Could hotswap or emergency hotswap be used with a VOD file?

    1. Do you mean to have main stream as VOD file? No, it's not supported.


If you face any specific issue or want to ask some question to our team,

This will give much faster and precise response.
Thank you.

Note: Only a member of this blog may post a comment.