Guidelines
Some recommendations to best operate Content-Replacement Application
Preparing your content
Checklist for your content
- Original source content and replacement content are available from broadpeak.io. Check your firewall, and whitelist the IPs of broadpeak.io if necessary.
- The original source content and the replacement content should be synchronized to the same clock, preferably broadpeak.io's clock. More information in the Time management section.
- Check that your manifests are compliant with broadpeak.io Input Formats section. We recommend that the original source content and replacement content are encoded and prepared in the same way (mandatory for HLS).
- Define your streams as sources in broadpeak.io - original content and replacement content.
Whether you are creating new outputs from your packager for this application or using existing sources, this section will help you make sure that your original content manifest is compatible with your replacement content manifest and that your Content Replacement application can run successfully.
In broadpeak.io, you must define your original content and any replacement content as Sources before anything else.
You have the option to define Sources directly via the web application UI, or by using the API.
For more information on defining Sources, please see Concept of Sources. A Source represents only one output. It s also called an adaptation stream, or variant. You can have a single channel, but different outputs to address different user or device segmentations. Each of these outputs would be a Source in broadpeak.io. Even easier, a streaming link/url from your packager = a Source in broadpeak.io.
1. Defining your original Live stream as Source
Whether you do it through the web UI or the API, you need to create a new Source with the following attributes:
- Source Name: give it a meaningful name. It could be something like "MyChannel_HLSv4_ts" or "MyChannel_DASH_MonoPeriod"...
- Stream Type: Live
- Stream URL: your output streaming URL. It can be HTTP or HTTPS such as:
https://yourPackagerFQDN/yourOriginalStream/YourOutput/index.m3u8
You can create as many sources as there are outputs defined in your origin packager for a single channel.
2. Defining your replacement content as Source
Before defining your content replacement as Source, please see to visit the Manifest manipulation section and make sure that your replacement content is compatible with your original content source, especially if you are using HLS.
Live stream as replacement content
The same way you defined your original content as a Source, you can define new Sources for each of the replacement contents that you are planning to use in broadpeak.io, either through the web application UI or via the API.
Note
There is no differences in creating a Source for original or replacement content. At this stage, they are only source objects and do not yet have any defined role in any of the broadpeak.io applications.
- Source name: we also suggest you to give it a meaningful name so that you can recognize your replacement content as such when needed, such as "MyReplacementStream_HLSv4_ts"
- Stream type: Live
- Stream URL: your output streaming URL, such as "https://yourOriginFQDN/yourReplacementStream/YourOutput/index.m3u8
Video-on-Demand as replacement source
Video on Demand content is called Asset in broadpeak.io. Asset sources may be used as replacement content for Content Replacement and Virtual Channel applications.
Specifically they may be used as:
- Default replacement content in a Content Replacement application
- Slot-specific replacement content in a Content Replacement application
- Slot-specific replacement content in a Virtual Channel application
Image slate as replacement source
Please contact the customer success team who will help you implement this.
You can contact us directly via the chat, or email us at [email protected].
MPEG-DASH Manifests
To make sure your MPEG-DASH streams are supported by broadpeak.io, we invite you to consult the following section: Input formats - Dash It is recommended that resolutions and codecs be alike between original and replacement sources - but not mandatory. The protocol allows easily to have different AdaptationSets
and Representations
from a DASH Period to another.
HLS manifests
To make sure your HLS streams are supported by broadpeak.io, please see the Input Formats section.
In HLS, players are more sensitive to codecs or resolution change within the same stream. For this reason, manifest contextualization can be successful only if the original and the replacement content are prepared in the same way. For more information about HLS Variant matching rules, see the HLS manifest manipulation section.
3. Streams must be available from broadpeak.io
Your original content streams and your replacement content streams must always be available from broadpeak.io. If you are using a firewall, make sure that correct inbound and outbound rules are configured so that broadpeak.io can pull the resources using the port that is defined on your streaming endpoint.
- Using HTTP, please make sure that the port 80 is opened on your firewall.
Ex: http://myorigin.com/mystream/myoutput/index.m3u8 - Using HTTPS, please make sure that the port 443 is opened on your firewall.
Ex: https://myorigin.com/mystream/myoutput/index.m3u8
If you are using HTTP over custom port, you must specify in the URL the port which needs to be used when defining your content as Source in broadpeak.io. Make sure that your firewall has the correct inbound and outbound rules to allow broadpeak.io to pull the resources using the custom port.
Ex: http://myorigin.com:81/mystream/myoutput/index.m3u8
Whitelisting broadpeak.io Ips to access origin streams
If the Origins are protected via IP whitelisting, make sure you have whitelisted all the Ips listed in the Platform Access section.
Preparing your Content Delivery Network
Whether you define your Content Replacement service on broadpeak.io via the web app or the API, a streaming end-point is generated and provided to you. You need to use this end-point to configure your Content Delivery Network and deliver contextualized streams to your end-users.
We invite you to follow the steps described in the following article: Using broadpeak.io with a CDN
Ensuring players compatibility
Requirements for players are the same as the requirements to support the HLS (RFC 8216) and MPEG-DASH standards. For a more comprehensive documentation, DASH-IF Implementation Guidelines are also available.
broadpeak.io only interacts with manifests and will specifically introduce changes in the stream when inserting new or different content.
DASH multi-period period
Regardless of the input provided to broadpeak.io, if supported, the platform generates a multi-period manifest when contextualization occurs. This means that the player must be able to understand multiple time periods in a single manifest. You can find more information here.
HLS Discontinuity
According to the HLS specification document, the EXT-X-DISCONTINUITY
tag is being used to announce a change in the stream to the player, such as:
- encoding parameters
- encoding sequence
When manipulation occurs on broadpeak.io, the system introduces EXT-X-DISCONTINUITY
tags in media manifests to notify the player that a change in the stream is happening.
Support for HTTP redirect
The context management mechanism of broadpeak.io introduces an HTTP redirect (307) that allows the system to introduce specific query parameters that identify the session. See Session management for more information.
What does it mean?
The HTTP redirect is forwarded to the client, which needs to correctly interpret and query the path found in the location
header of the response. The location value is a path without FQDN, so the player needs to reuse the existing FQDN. This is pretty standard and most players support it natively. Contact us at [email protected] if you have any problem.
Preparing your scheduling system
The scheduling system is the component responsible for creating Content Replacement slots (MediaPoints) and automating the creation of Content Replacement slots on broadpeak.io to make sure that different sets of audiences watch the content they are allowed to watch.
At this stage, one might have created sources and content replacement services via the web app, and it is time to leverage the use of broadpeak.io API to create slots according to the ESNI specifications.
Generate your API key
If you have not generated your API key yet, you can do so in the Account Settings section under the API keys tab.
Make sure to save it somewhere safe as it will not be shared with you again.
Please see the API reference documentation to understand how to use the key in the calls to the platform.
Time synchronization
Content Replacement application and program scheduling are all based on timing. Inaccurate timing between the programing system and broadpeak.io can lead to unexpected behavior and can have commercial and legal impacts.
To avoid this consequence, it is best to ensure the accuracy of the synchronization between systems, so we invite you to use a time synchronization mechanism (NTP, Chrony).
You can find more information in the Time managementsection.
Scheduled events
In typical Content Replacement applications, most events are known in advance and planned several days ahead. For most of them (about 80%), the exact time of the switchover is known in advance and can be applied automatically to the planned time. In some cases, already planned slots also need to be updated. This can happen right before the initial slot start time, or even after a slot has already started. broadpeak.io gives you the tools to address these scenarios with the flexibility you need.
Your scheduling data is not always in SCTE224 format. This does not mean you cannot use our solution!
Some of our customers are using XLS, DBS or CSV files to populate their schedule and trigger our platform. In this case, the solution is to convert the original scheduling data into SCTE224.
Please contact your broadpeak.io representative to explore what options you may have there.
Code and requests samples
If you don't feel like jumping straight into coding to build the logic to manage the interoperability with your programming system with broadpeak.io, you can rely on the built-in scheduler that is provided natively with the webpapp.
We also leverage a tool powered by swagger.io available on the API reference section, that can help you send sample requests to broadpeak.io! Give it a try, it's pretty cool!
In the same section, you can find code suggestions that you can use to build your application faster. A set of the most adopted languages is available.
Updated 6 months ago