Handle Live Stream Disconnects

How Mux handles disconnects

Before reading this guide, you created and set up a Live Stream by following these steps:

• You have connected your encoder (for example OBS, Wirecast, your live streaming app) to an RTMP ingest server as covered in this guide: Configure Broadcast Software).
• Mux sends the video.live_stream.connected event to your environment.
• When the encoder starts sending media to the ingest server, the webhook events video.live_stream.recording and then video.live_stream.active are delivered to your environment.

If everything goes smoothly, the encoder will keep sending media and the server will keep processing it, creating video segments and updating the HLS playlists with new pieces of video (to understand how this works read Reduce live stream latency). Since all of this streaming is happening live, the ingest server needs to know what it should do when the encoder disconnects unexpectedly.

What happens when the live stream disconnects either intentionally or due to a drop in the network? Mux sends the video.live_stream.disconnected event for the live stream to your environment. This is where the reconnect_window comes into play.

Reconnect Window

When you create the Live StreamAPI or update the Live StreamAPI, you can set the reconnect_window parameter in the Request JSON.

The Reconnect Window is the time in seconds that Mux should wait for the live stream broadcasting software to reconnect before considering the live stream finished and completing the recorded asset. As a default, Mux sets reconnect_window to 60 seconds for Standard Latency streams and zero seconds for Reduced and Low Latency streams, but this can be adjusted to any value between 0 to 1800 seconds.

Reconnect Window and slates

When you create the Live StreamAPI or update the Live StreamAPI, you can set the reconnect_slate_url parameter with the URL of the slate image.

Slate insertion can help output a live stream for viewers without interruptions. Below are some examples where Mux receives an imperfect stream and how Mux handles the output:

• If the input contains only audio for the relevant time, the most recent video frame is duplicated
• If the input contains only video for the relevant time, Mux will output silent audio
• If a slate is inserted and the input has no audio or video (including because the encoder was disconnected) a slate period begins where Mux will output silent audio, and duplicate the most recent video frame. After 0.5 seconds, Mux will switch to the slate image and continue to send silent audio. If the encoder is still connected, Mux will disconnect the encoder after 5 minutes. Mux will then continue inserting slates for up to the duration of the reconnect_window in seconds. Viewers may experience a maximum slate duration of up to 5 minutes over the reconnect_window duration

When Mux stops receiving the media, Mux adds the slate image as a video frame to the live stream. This event of not receiving media disconnects the encoder and starts the reconnect_window time interval. Mux stops adding the slate image when Mux starts receiving media again or the reconnect window time interval expires.

Enable slates for standard, reduced, and low latency mode live streams:

• For standard latency live streams, set the use_slate_for_standard_latency parameter to true and make sure the reconnect_window parameter value is greater than 0s. Live streams, created before the slate image functionality was available, will not automatically start using slates until this parameter is set.
• For reduced and low latency mode live streams, set the reconnect_window parameter value to greater than 0s.

Mux selects one of the following images as the default slate image depending on the live stream's video aspect ratio. The default slate image is used unless you set the reconnect_slate_url parameter. We recommended setting the slate image whose aspect ratio matches the live stream's video aspect ratio. You can modify the reconnect_slate_url parameter using the update the Live StreamAPI.

Horizontal Laptop Illustration

Vertical Laptop Illustration

Mux downloads the slate image, hosted at the URL set as reconnect_slate_url parameter value, at the start of the live stream recording. So, you must ensure the image is always downloadable from the URL. When Mux can not download the image, the default slate image (shown above) is used and the video.live_stream.warning for the live stream as well as the video.asset.warning webhook event for the asset is fired. Below is an example of the webhook event body:

{
    "type": "video.live_stream.warning", // or "video.asset.warning"
    "object": {
      "type": "live",
      "id": "CiinCsHA2EbsU00XwzherzjWAek3VmtUz8"
    },
    "id": "3a56ac3d-33da-4366-855b-f592d898409d",
    "environment": {
      "name": "Production",
      "id": "j0863n"
    },
    "data": {
      "warning": {
        "type": "custom_slate_unavailable",
        "message": "Unable to download custom reconnect slate image from URL 'http://example.com/bad_url.png' -- using black frames for slate if needed."
      },
      "stream_key": "5203dc64-074a-5914-0dfc-ce007f5db53a",
      "status": "idle",  // or "preparing"
      "id": "CiinCsHA2EbsU00XwzherzjWAek3VmtUz8",
      "active_asset_id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002"
    },
    "created_at": "2022-07-14T21:08:27.000000Z",
    "accessor_source": null,
    "accessor": null,
    "request_id": null
  }

How to handle reconnects from the Player/Client side without a slate image

When Mux is not receiving any media, the viewer experience depends on whether Mux starts receiving media before the reconnect window expires. We strongly recommend updating the Live StreamAPI to add a slate image. However, there are two possible scenarios when you do not want to add the slate image.

In scenario 1, the encoder re-connects

The ingest server will wait for the duration of the reconnect_window before it ends the live stream. While the encoder is disconnected, media is no longer being sent, so the HLS playlists are not getting new segments of video.

If the encoder reconnects before the reconnect_window expires then the HLS playlist will resume appending new video segments to the live stream.

In scenario 2, the encoder disconnects

If the encoder does not reconnect before the reconnect_window expires, the following events will occur:

1. Mux writes an EXT-X-ENDLIST tag to the HLS playlist. According to the HLS specification: EXT-X-ENDLIST: Indicates that no more media files will be added to the playlist file. This tells the player this stream is over and no more media is coming. Your player should emit an ended event, or something equivalent.
2. The live stream will transition from active back to idle
3. Mux will create a new asset. The active_asset_id while the live stream was active will be finalized. If the same live stream goes live again at a later time, then the live stream will get a new active_asset_id and a new asset will be created.