Handling Content Replacement slots

Blackout slots can be created on broadpeak.io using SCTE-224 MediaPoints.

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

Policy & Viewing Policy

When creating a slot in SCTE224 ESNI API, you can use Policy and Viewing Policy to:

• define Actions to choose the replacement content to apply during the slot. It can be a default content or a content specific to the slot;
• define Audiences (with Zip codes 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 in broadpeak.io.
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>

The above Audience will match end-user requests that include the "zip=89044" query parameter.

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>

The above Audience will match end-user requests that include "zip=89044" or any other zip value in its query parameter.

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 use Audiences directly 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="area51" match="ANY" />
  <action:Content>AltSource1</action:Content>
</ViewingPolicy>

The above Audience will match end-user requests that include the "category=area51" query parameter.

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. To target this Audience, the end-user requests will need to include the "category=iphonesH265" query parameter.

<Media href="MyContentReplacementService">
  <MediaPoint id="MyMediaPoint" matchTime="2021-08-18T16:00:00Z" expectedDuration="PT0H1M">
    <<Apply>
      <Policy id="1">
        <ViewingPolicy id="1">
          <Audience id="iphonesH265" />
          <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.