Adding a failover

With THEOlive we want to make sure your viewers can continue watching your stream, even if there is an ingest failure or if there are connectivity problems in a certain location. It is hence possible to set up a failover stream. This means that if one stream is unavailable for a short amount of time, the player checks if the failover/backup stream is available and switches the player source automatically to this stream. In this case, the viewers only see a very small interruption and can continue watching without having to take action.

This can be accomplished through the following steps:

1. Create two channels and start them

You'll need to create two THEOlive channels via the API or management console. Let's say for example that we have the following channels with fictive IDs:

• Channel <channel-in-us-west> which is located in the us-west region
• Channel <channel-in-us-east> which is located in the us-east region

Don't forget to start both channels. If the failover stream isn't started, it will be impossible to switch to it when something goes wrong with the primary one!

2. Set the failoverId using the THEOlive API

Assume the channel with id <channel-in-us-west> should have a back-up that links to the <channel-in-us-east> channel. To make this work, we need to send a request to the PATCH https://api.theo.live/channels/<channel-in-us-west> endpoint to update the settings of <channel-in-us-west>. Passing the following JSON body with the request will set the <channel-in-us-east> channel as the failover/backup channel.

{
    "failoverId": "<channel-in-us-east>"
}

This will work as follows:

1. Before starting anything, the player will check if the primary stream is up and running (<channel-in-us-west> in our case).
2. If the stream is running, the player will start playing. If not, the player will check if the backup stream is running (<channel-in-us-east>). If this stream is running, it will be set as primary stream and the player will start playing. If this stream is down as well, a message will be shown that the live stream isn't started yet.
3. When the primary stream becomes unavailable after a while, the player will search if the backup stream is defined and switch to it if possible.
4. If this backup stream becomes unavailable after a while, the player will try to switch back to the primary stream.
5. This process will continue to work this way. If both streams are unavailable, the pre-live settings will be shown (an announcement message and optionally a poster image too).

For more information, please visit our API Reference.

Note that the failover can also easily be set in our management console on the Channel Details page: