Handling Content Replacement slots

Blackout slots can be created on broadpeak.io using SCTE-224 MediaPoints or using the broadpeak.io REST API.

SCTE-224 MediaPoints

MediaPoints in the context of Content Replacement application are (time) slot objects under the ESNI Specifications. We invite you to have a look at the API documentation to understand how to create a MediaPoint using broadpeak.io API.

A MediaPoint contains a matchTime attribute which describes the starting point of the Content Replacement slot, and a expectedDuration which reflects the duration of the slot. It can also contains Policies & Viewing policies to define specific Actions, Audiences and/or Categories, but first let's start with the simplest way to create a simple Mediapoint for your blackout service. We will assume that we already have an existing Content Replacement Service "MyContentReplacementService".

<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <action:Content>urn:scte:224:action:blackout</action:Content>
        </ViewingPolicy>
      </Policy>
    </Apply>
  </MediaPoint>
</Media>

Above is the example of an XML body sent to create a MediaPoint via the API. Having a closer look at the slot which is created: the created MediaPoint targets the Content Replacement service "MyContentReplacementService", starts on August 2021, and lasts for a period of one minute. Without specifying a replacement source, the default replacement source is used. The same applies to the Audience or Category, if not defined, the content replacement affects all Audiences for this slot.

More info about how to use MediaPoint attributes

Objects

Attribute

Value

Format

Definition

Conditions

Media

href

Valid content replacement service name

Text

Name of the Content Replacement Service where the slot will be created or updated

See "Supporting multiple formats with a single ESNI API call" below.

MediaPoint

id

Any value

As per XML specifications.
https://www.w3.org/TR/xml/#charsets

Reference ID to the MediaPoint into broadpeak.io, for a specific Content Replacement service.

Using an existing ID will update the existing slot.

MediaPoint

matchTime

Valid time value

ISO 8601 as string

Starting point of the replacement period. Shall be specified in UTC.

Can be a value in the past if the MediaPoint matchTime value + MediaPoint expectedDuration value is in the future.

MediaPoint

expectedDuration

Valid time period value

ISO_8601 duration as string

Value in time of the duration of the Content Replacement slot.

Policy & Viewing Policy

You can use Policy and Viewing Policy to define Actions, Audiences or Categories to which the Content Replacement slot created will apply. Policy and Viewing Policy Ids are not relevant when using broadpeak.io, as they are directly created at the slot creation and hence bound to the slot itself.

Actions

Using default replacement content

When creating the service, it is mandatory to specify a replacement source that would be used in case the MediaPoint does not specify the alternate source to use. This is the case in the example above, with the following viewing policy:

<ViewingPolicy id="1">
  <action:Content>urn:scte:224:action:blackout</action:Content>
</ViewingPolicy>

Specifying alternate sources in the MediaPoint

In general, Blackout slots contain a reference to the alternate source which needs to be used as blackout replacement content during the duration of the slot. This can be defined directly at the Viewing policy level as per below:

<ViewingPolicy id="1">
    <action:Content>AltSource1</action:Content>
</ViewingPolicy>

The alternate source in this example is "AltSource1" which represents the name of the Source object defined at its creation.
The following requirements apply to the alternate source:

  • It is mandatory that this Source object already exists before creating a MediaPoint with the specified alternate source.
  • It is also mandatory that this source has the same format (HLS or DASH) than the original source of the service.
<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
            <action:Content>AltSource1</action:Content>
        </ViewingPolicy>
      </Policy>
    </Apply>
  </MediaPoint>
</Media>

Audiences

It is possible to create blackout slots which targets only specific subsets of users, bound to geography, device or device capability (non exhaustive list). This can be done using Audiences with zip codes or categories.

An Audience is defined by a list of zip codes that represent the geographic area(s) to which the Content Replacement slot applies. To create a blackout slot for a specific Audience, we need to define an Audience object within the Viewing Policy.

<ViewingPolicy id="1">
  <Audience id="AudienceId" match="ANY">
    <audience:zip>12345</audience:zip>
    <audience:zip>12346</audience:zip>
    <audience:zip>12347</audience:zip>
    <audience:zip>.....</audience:zip>
  </Audience>
  <action:Content>AltSource1</action:Content>
</ViewingPolicy>

Single zip code Audience

Assuming we want to specifically have the alternate source "AltSource1" streamed the Area 51's end users, then create a slot which defines a targeted Audience "area 51" represented by the zip code 89044.

<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <<Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <Audience id="area 51" match="ANY">
            <audience:zip>89044</audience:zip>
          </Audience>
          <action:Content>AltSource1</action:Content>
        </ViewingPolicy>
      </Policy>
     </Apply>
  </MediaPoint>
</Media>

Multiple zip code audience

If we want to expand the previous example to the entire state of Nevada instead of Area 51, we need to create a slot with a targeted audience that contains more zip codes - in fact the entire list of Nevada zip codes. To keep it simple, we are only listing a few in the example below.

<Media href="MyContentReplacementervice">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <<Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <Audience id="Nevada" match="ANY">
            <audience:zip>89044</audience:zip>
            <audience:zip>89108</audience:zip>
            <audience:zip>89110</audience:zip>
            <audience:zip>89031</audience:zip>
            <audience:zip>89121</audience:zip>
            <audience:zip>.....</audience:zip>
          </Audience>
          <action:Content>AltSource1</action:Content>
        </ViewingPolicy>
      </Policy>
     </Apply>
  </MediaPoint>
</Media>

Audience defined through categories

Using Audiences with zip codes to represent one or more geographic areas is not the only option for specifying the subset of end-users to whom a blackout slot should be applied. It is also possible to create categories inside the viewing policy. If we go back to our previous example of a slot that would only target the Area 51, we could create the equivalent blackout slot with the following tags:

<ViewingPolicy id="1">
  <Audience id="area 51" match="ANY">
    <broadpeak:Category>89044</broadpeak:Category>
  </Audience>
  <action:Content>AltSource1</action:Content>
</ViewingPolicy>

Similarly, if we want to target the entire subset of users located in Nevada, we would use the following:

<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <<Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <Audience id="area 51" match="ANY">
            <broadpeak:Category>89044</broadpeak:Category>
            <broadpeak:Category>89108</broadpeak:Category>
            <broadpeak:Category>89110</broadpeak:Category>
            <broadpeak:Category>89031</broadpeak:Category>
            <broadpeak:Category>89121</broadpeak:Category>
            <broadpeak:Category>.....</broadpeak:Category>
          </Audience>
          <action:Content>AltSource1</action:Content>
        </ViewingPolicy>
      </Policy>
    </Apply>
  </MediaPoint>
</Media>

Categories can also be used for other purposes, such as targeting a specific set of devices. A good example would be a category that lists all Iphones that support HEVC.

<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <<Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <Audience id="iphonesH265">
            <broadpeak:Category>iphone7series</broadpeak:Category>
            <broadpeak:Category>iphone8series</broadpeak:Category>
            <broadpeak:Category>iphone9series</broadpeak:Category>
            <broadpeak:Category>iphone10series</broadpeak:Category>
            <broadpeak:Category>iphone11series</broadpeak:Category>
            <broadpeak:Category>iphone12series</broadpeak:Category>
            <broadpeak:Category>iphone13series</broadpeak:Category>   
          </Audience>
          <action:Content>HEVCAltSource1</action:Content>
        </ViewingPolicy>
        </Policy>
    </Apply>
  </MediaPoint>
</Media>

Supporting multiple formats with a single ESNI API call

In broadpeak.io, a source must be either HLS or DASH. A service has the same format than its original source. The default replacement source, or a slot-level replacement source, must have the same format than the service (and the original source).
In practice, it is very common to have both a HLS variant and a DASH variant of a service.
When creating a MediaPoint, the normal process is to target each variant with a specific API call.
However, the ESNI controller may not have the capability to duplicate each call.
To facilitate this, broadpeak.io supports addressing multiple services with a single API call.
When it receives a call for "MyContentReplacementService", it also tries to create MediaPoints for "MyContentReplacementService_HLS" and "MyContentReplacementService_DASH". At least one of these services must exist for the call to succeed but there can also be 2 or 3 of them.
If an alternate source is specified, it must exist with the same suffix and format than all the existing services.
For example, if the alternate source is "AltSource1":

  • If "MyContentReplacementService" exists, then "AltSource1" must exist
  • If "MyContentReplacementervice_HLS" exists, then "AltSource1_HLS" must exist
  • If "MyContentReplacementService_DASH" exists, then "AltSource1_DASH" must exist
    If any of the required alternate sources does not exist, then the platform replies with an error and does not create the MediaPoint for any of the existing services.

REST API

Please consult directly the API Reference.


Did this page help you?