Red5 Documentation

Interstitial Media Insertion

The interstitial Media Insertion feature allows a temporary switch between 2 streams, where the audio and the video of a new stream can be inserted into an existing one. There are various parameters such as duration, loop, etc. which can be set on the insert of the new stream.

There are three classes of interstitial lifecycles which can be used together.

  • Indefinite – Starts immediately and lasts until a call is made to resume.
  • Wall clock – Starts at a specific times UTC and lasts for a specific duration. Automatically resumes.
  • Stream clock – Starts at a specific time from the start of the stream and lasts for a specific duration. Automatically resumes.

If the insertion is a file, it can be looped optionally. This covers the cases where the insertion duration is longer than the file duration.

If there is an interstitial in queue, its scheduling will be checked prior to the stream resuming so that multiple inserts can be scheduled back to back.


The indefinite interstitial type happens immediately when added to the queue. When two are added to the queue at the same time, the numeric id property must loosely reflect the order, ascending. Lower id’s will be scheduled prior to higher ids of type indefinite. And indefinite types will be scheduled before both wall and stream clock types.

Media alikeness with frequent key framing is paramount to seamless interstitial behavior.

Requirements and Use cases

If a broadcaster or administrator wants to switch the stream content, such as inserting commercials or pausing the show with a video card (“we’ll be right back”), interstitials provide the mechanism. The frame packets which compose live streams can be freely interchanged if they share common encodings; as such, the inserted content must be prepared ahead of time or the source broadcasters must be configured as uniformly as possible.

Interstitial media insertion is supported on a standalone server or via Stream Manager.

The Interstitial Media Insertion feature is available with server version >= 9.1.0.

Below are a few ideas for utilizing the Interstitial Media Insertion feature. These are by no means the limit of what can be done with this feature, and we encourage you to get creative. If you have any questions as to whether your idea is a good fit for Interstitial Media Insertion or just want to discuss what’s possible, send us an email at to setup a call.

Use Case #1:

A broadcast sporting event, where the audio of the play by play continues in the background while cutting away to a display of league scores or scheduled matches. Afterwards, the game video is resumed.

Use Case #2:

An interview panel with a slot for guests. The “guest” stream is the static source (this could be a static image broadcast via OBS or perhaps the stream of a moderator who introduces each new interviewer), and various participants’ streams are temporarily inserted into the guest slot. After each guest, the moderator stream is resumed.

Use Case #3:

Use a recorded file or a live PSA as an advertisement during a broadcast. You can utilize the loop option to replay a short ad.