Key concepts

Discover the terminology and the main features of Content replacement application

Sources : original and replacement content

A content replacement service is based on an original content, that has to be a live source you have already created. The second component of the service is a default replacement content. It can be either a live source or and VOD asset. The replacement content has to be consistent with the original content. It will be used as soon as there is a slot created but no replacement content specified for the slot.

Once the service is created, the associated output URL will display the original content. Normal, a content replacement Service relies on slot creation to be operate.

Slot creation

When creating a slot you have several elements to detail

  • Event name : this is optionnal but can help you finding the right slot if updates are needed
  • Replacement content : the alternative content that will be displayed during the slot. It has to be created in your sources yet. However, this can remain empty : then the default replacement content you've set at the service creation will be displayed during the slot.
  • Start time and duration (or end time) of the slot : when the original content will be replaced by an alternative content in the output URL stream.
  • Category : the audience that will be impacted by the slot when requesting the stream

Replacement contents

Replacement content used during a slot can be either a VOD asset or a Live source. The compatibility between the original Live source and the replacement content is important :

  • If you are using both HLS and DASH, you will have to create 2 services and 1 slot per services (see exception ESNI API article)
  • Codec constraints, bandwidth and segment sizes' matching between HLS content is mandatory, and highly recommanded for DASH content

Personalisation using categories

Personalisation (or "contextualisation") is the ability of pushing different streaming contents to different audiences, although they are requesting the same video stream. In content replacement, that can happen for instance in case you don't want to display the original content to a local audience, but you want to give access to this content to end user outside of a certain geographical area.

Here how to use categories for content replacement serivce:

  1. First, you have to create categories in They could be expressed as a single text string, for simple audience description : Mobile, web, STB for instance or Child, Teenager, Young, Adults etc. For geographical areas, you can use simple names, but you can use also ZIP codes as Subcategories : NY & 1001, 1002, 1003...
  2. Then when creating a slot, you can attached this slot to a category. If you don't, the replacement will happen for your whole audience.
  3. Finally, to fully operate personalisation, needs to be able to identify the category where the end-user requesting the stream belongs to. To do so, the client request must hold a query parameter with the value that describes the end users and make it possible to choose wether the slot applies or not to the user.

For instance, if we want to replace the live stream by a content for a child audience, then we create two categories; child and adults. If the service is already created, once we create a slot, we can choose the category "child". According to query params that are added to the stream URL, the slot will be displayed or not, as shown bellow.

ZIP codes for categories

In some cases, identifiying users from a geographical area can be more convenient using ZIP codes. In such situation, you can create a category that identifies all ZIP codes from this area. Doing that will prevent you declaring all ZIP codes as single categories. When creating a slot for this category, then broadpeak.iowill match zip codes with the slot.

For instance, if we created a slot for the category New-York, then the url**zip=1002** will be impacted by the content replacement.

For each Content Replacement service and time slot, the end-users receive the stream with either the original or replacement content. The decision is made based on the match between the zip code or “category” specified in the client request, and the policy defined in the metadata.

Metadata must be ingested prior to the events through a secured API. Base API endpoint is and more information on how to use the API can be found here API reference)

The API is an Event Scheduling and Notification Interface (ESNI) which is based upon the SCTE 224 standard (link).
It allows you to define audiences (for instance with a list of zip codes, each zip code being a 5-digit number) and time slots.

Please note that time slots can also be created through a dedicated API (see the Content Replacement slot section).

Slot vs notification timing

"Past" and "future" time points are relative to timing when the API call is received and processed by the platform.

Use casePast event (obsolete notification)In progress event (late notification)Future event (notification)
DescriptionSlot ends in the past.Slot starts in the past but ends in the future.Slot starts in the future and ends in the future.
ScenarioEvent is already finished. Slot cannot be created.Event has started but has not finished yet. Slot will be created for the remaining period of time.Event has not yet started. Slot will be created for the defined period.
API callCall is refused.Not supported yet (coming soon)Supported


Service variants

A future release will allow the ESNI Media Id to be mapped to a set of service variants. This scheme will be based upon an optional list of streaming formats, and will, for instance, enable support for any combination of formats/versions/DRMs you may have:

  • packaging format (DASH, HLS)
  • packaging format versions (HLS v3, HLS v5, etc.)
  • DRM versions (Fairplay, PlayReady, etc.)