In Using broadpeak.io with a CDN we explain the reasons why you need to use a CDN in front of your broadpeak.io services in order to deliver your manipulated streams in the most optimal and efficient way.

In this playbook, we'll look at an example and illustrate how to configure it with the Akamai Adaptive Media Delivery product, for a Content Replacement application.

Prerequisites

You need to be familiar with how to configure a broadpeak.io Content Replacement service first. You'll find other playbooks in the "Getting Started" section of our documentation, as well as in the present "Playbooks" section.

For expediency, the examples in this playbook will use the same sources as those Getting Started articles.

Specifically, we'll use https://origin.broadpeak.io/bpk-tv/bpkiofficial/hlsv3/index.m3u8 (one of our default samples) as the source, from which - in this case - a Content Replacement service has been created, the URL of which would look like https://stream.broadpeak.io/a3eb043e7bf775ded159a8940be5e720/bpk-tv/bpkiofficial/hlsv3/index.m3u8.

You also need to ensure that your Akamai account has access to the Adaptive Media Delivery product. Talk to your Akamai account manager to enable it.

Rules

The primary aspect of configuration for the CDN relates to routing. In an ABR stream, there are one or multiple manifests or playlists, and multiple media segments that the player will request in order to render the stream. The player connects to a single CDN, which needs to know where to send those requests. So it needs to be given a set of rules to follow. Those rules will be somewhat dependent on the type of service you are implementing.

For a Content Replacement service, you will need:

• Rules that define how to direct manifest requests to broadpeak.io
• Rules that define how to direct segment calls for the base live stream to its origin (ie. the server that stores that original packaged content)
• One or more rules to direct segment calls for the replacement assets to their respective origins.

Step 1 - Property

The first thing you need to do is to set up a Property in the Akamai CDN solution.

• Go to CDN > Properties in the Control Center sidebar
• Click the + New Property button, and choose Adaptive Media Delivery in the next screen.

You will be presented with a wizard to configure that product.

• Set the Property name to anything that is easily identifiable later, such as the target hostname. Select the latest Rule Format.

You now land on the screen in which you can configure the property.

🚧

Minimum functional configuration

There are dozens of settings that can be defined with Akamai CDN. It's not the role of this playbook to explain them all. We'll concentrate on the minimum set to successfully define a working example with the samples that we provide for tests.

Some of the settings (in particular caching rules, TTL, TLS version, etc.) may also need adjusting based on your own Origin servers and typical CDN configuration needs.

Note also that the example concentrates on browser-based streaming into common web video players. Other players may require additional and specific settings.

If something isn't behaving as expected, don't hesitate to contact our Support staff at [email protected].

For this playbook, we will make use of the fact that Akamai offers a pre-configured akamaized.net domain name, removing the need to configure a hostname.

• In the Property Version Information panel, select "Shared Cert" under Security Options. It's the easiest way to ensure we can use HTTPS for delivery of the content in this playbook
• In the Property Hostnames panel, click the + Hostnames button and select Add Shared Certificate Hostname

• In the popup that appears, set Edge Hostname to a hostname of your choice.
  • For Segmented Media Mode, choose Live or VOD depending on what you want to deliver. Here we're looking at Live Pre-Roll, so we will choose Live

We are now ready to configure the routing rules.

Step 2 - Default Rule

The Default Rule defines the behavior that applies to all requests, unless any other rule applies - which we will configure later. It could be seen as the fallback. We will use it to configure to deliver the content segments

• Scroll until you see the Property Configuration Settings panel.

• Select the Default Rule in the left hand sidebar, and look at the Behaviors panel.

• Under Origin Server set Origin Type to "Your Origin", and then

  • Set Origin Server Hostname to the hostname of the origin that contains your live content. In this playbook it is origin.broadpeak.io
  • Set the Forward Host Header to "Origin Hostname"
  
  

• Under Content Provider Code, you need to choose a CP code (which is used in the Akamai realm to identify usage, reporting and billing segments). Click Create new... if you don't have one yet, or need a separate one.

• Under Segment Media Deliver Mode, choose the same mode as configured in the property ("LIVE" in this case)

• Under Content Characteristics, ensure that HLS and DASH are enabled. You can switch off HDS and Smooth

• All other settings can be left at their default for this playbook. Check the Akamai configuration if you want to know more about them.

We now need to also configure caching. We want all those content segments to be cached in the Akamai network, for efficient delivery

• At the bottom of the Property Configuration Settings panel, click + Behavior, and select Standard property behavior
• In the popup, find or type Caching in the left-hand panel and click Insert Behavior

• Here the actual configuration will depend on your content origin. Under Caching option, we will just have a bare-bones setting that forces cache of that content for one day.

📘

Note that In a production system, it's likely that your origin will define the behavior already, and you will therefore want to choose "Honor origin Cache-Control and Expires".

That should do it. Press Save.

At this stage, you may want to activate this first version, just to validate that you have the basics right.

Deploy your property

Scroll back to the top of the page and select the Activate tab.

Akamai allows you (and strongly recommends) to deploy your property onto a Staging Network. Doing so will make it available on a small network of edge servers. It is also faster to deploy. To test it is however a bit more complex, as you likely will need to spoof hostnames on your local machines. It is beyond the scope of this document to explain it, and there is a lot of documentation on the Akamai site.

In this playbook, we will just deploy to the production network directly.

• Click Activate v1 on Production

• In the popup screen, after checking whether any of the Warning messages apply to your test, click Activate v1 on Production again.
• You will now have to wait a few minutes for the deployment to be done. The screen will provide you with visual progress and confirmation, and you should also receive an email.

When deployment is done, you should be able to play back the stream through your chosen hostname, in our case https://bpkio-cs-akamai-playbook-test.akamaized.net/bpk-tv/bpkiofficial/hlsv3/index.m3u8. Use any of your standard web players to perform that test.

Step 3 - Manifests

So far all we've really done is to create a way to distribute and cache the live stream through the Akamai Network. We now need to define how to redirect calls for manifests and send them to broadpeak.io.

• If needed, go back to your property and choose Edit New Version, to create a v2 version on top of the work done so far.
• In the Property Configuration Settings click + Rules in the left sidebar. Choose a blank rule and name it "Manifests".

• Back in the main screen, in the Criteria panel, you define when the rule applies. We want Akamai to follow it when it comes to delivering HLS and DASH manifests. In most cases, that can be determined based on file extensions

• Under Behaviors > Origin Server, set Origin Server Hostname to stream.broadpeak.io and Forward Host Header to "Origin Hostname"

• When it comes to caching we want to ensure that no caching is done for those manipulated manifests. Add a Caching behavior and set the Caching option to "No store"

📘

Enabling SmartLib

If you are using (or planning to use) SmartLib SDK on the client side, you need to also add a behavior at this point, which exposes the Location header so that the SDK can make use of it in its control logic

• Press Save

Step 4 - Alternate Content

So far so good, but now we want to handle the alternate content.

When you configure a broadpeak.io service, you'll want to involve other content too. In particular, when working with Content Replacement and/or Virtual Channel services, you will normally want to stitch in content (specifically media segments) that comes from other places, usually different origins.

If that content comes from the same origin (as is the case in our Getting Started examples for Virtual Channel and Content Replacement services), then there's nothing left to do. Your service should be operational.

Often though, the content that is substituted into the live stream will come from different domains. Extending your property configuration to cover those is an extension of the work done so far:

• add a new Rule with a Criteria that uniquely identifies segments for the substituted content.
• and configure the rule's Behavior to route those requests to the appropriate origin

You'll do that based on the (partial) path to that content. So you need to be able to define a path pattern that uniquely identifies content coming from those alternate origins.

For example, let's imagine that we have VOD assets that sit on an alternate origin, which we want stitched in the stream. Here is one: https://bpkiosamples.s3-eu-west-1.amazonaws.com/AVOD/TOS-original-24fps-1080p/conditioned/stream.m3u8.

By adding it to a slot in the service, the stream output might look like the following:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-TARGETDURATION:8
#EXT-X-PROGRAM-DATE-TIME:2023-10-03T20:14:17.821796+00:00
#EXTINF:4, no desc
live-audio=126470-video=1600215-424091019.ts?bpkio_serviceid=a3eb043e7bf775ded159a8940be5e720&bpkio_sessionid=10c0b51d66-005aea96-dc0b-40d4-8004-090bc0949313
#EXTINF:4, no desc
live-audio=126470-video=1600215-424091020.ts?bpkio_serviceid=a3eb043e7bf775ded159a8940be5e720&bpkio_sessionid=10c0b51d66-005aea96-dc0b-40d4-8004-090bc0949313
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-10-03T20:14:43.000000+00:00
#EXTINF:8,
../../../AVOD/TOS-original-24fps-1080p/conditioned/video/1600000/ts/segment_0.ts?bpkio_serviceid=a3eb043e7bf775ded159a8940be5e720&bpkio_sessionid=10c0b51d66-005aea96-dc0b-40d4-8004-090bc0949313
#EXTINF:8,
../../../AVOD/TOS-original-24fps-1080p/conditioned/video/1600000/ts/segment_1.ts?bpkio_serviceid=a3eb043e7bf775ded159a8940be5e720&bpkio_sessionid=10c0b51d66-005aea96-dc0b-40d4-8004-090bc0949313

This means that requests for media segments of the alternate content are sent to https://[your-hostname.akamaized.net]/AVOD/...

Assuming that all those replacement assets are under the same root folder AVOD, the path pattern /AVOD/* will provide a clean way to differentiate those segments from the original stream segments, and we can create a new behaviour in the distribution accordingly.

Caching rules will typically be similar to those for the default origin.

If you have multiple origins from which content will be sourced from, you repeat those steps, and create a behaviour with an appropriate path pattern.

Other optional rules

Depending on your application, there may be other redirection rules that you need to apply. Some of the common ones are:

 HLS Subtitles

If your content is in HLS and has WebVTT subtitles, but the alternate content (replacement content, or ads) does not, broadpeak.io will insert references to an empty VTT file (/empty.webvtt).

You need to add this one to your distribution as well:

• Criteria: If Path matches one of /empty.webvtt
• Origin Server: stream.broadpeak.io
• Caching options: "Cache"

 Final Step

For an initial configuration, this ought to do it.

It is now time to activate this new version of the property. After that, you should be able to stream your content, simply by replacing the stream.broadpeak.io part in your service URL with the Akamai AMD hostname you selected.

You can even test this in the WebApp, in the preview page for your service.