Creating Delivery Rules in Brightcove Video Cloud

In 2017 Brightcove launched Dynamic Delivery and began generating our manifests and video "just in time" at the point a player requests them, allowing us to repackage content to multiple different formats and support the widest range of devices possible.

Since then, we've increasingly been hearing from customers that they want to take advantage of this flexibility themselves and control at a fine-grained level which CDN their content is delivered over, what quality of video renditions should be available and even what order the different quality renditions should be presented in inside the video manifest. This lead to the creation of our Delivery Rules feature, which is now generally available as part of our API.

In this post, we'll look at how to use this API to solve one of the most common use-cases we see - limiting the maximum quality of video being served to certain devices.

Getting Set Up

To get started we first need a video to test with, which we've ingested as normal via Video Cloud.

Looking under the covers at the HLS manifest that's being delivered to that player, we can see it contains a number of the following lines, representing rendition manifests of different resolutions - in this case 480x270, 640x360, 960x540 and 1280x720 (below):

#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=2205500,CODECS="mp4a.40.2,avc1.4d001f",RESOLUTION=1280x720,AUDIO="audio-2",CLOSED-CAPTIONS=NONE
https://manifest.prod.boltdns.net/manifest/v1/hls/v4/aes128/5270290572001/aa7059e5-586b-4caa-ae6f-5533f223a569/a557b391-f20e-4727-9185-459411a63029/10s/rendition.m3u8

If 960x540 is the maximum resolution we want to deliver to our hypothetical device, then we should see the 1280x720 rendition disappear once our rule has been applied.

Creating Our Rule

Delivery Rules are made up of Conditions (when a rule should be invoked) and Actions (how the rule should affect the content).

Since we know that we want the rule to limit the maximum video rendition quality, let's go ahead and create the Action first with the following HTTP request:

POST /accounts/{accountID}/actions
  Content-Type: application/json
  Authorization: Bearer {access_token}

and the request body set to:

{
  "properties": {
    "max_video_resolution": "960x540"
  }
}

This will create the new Action and return us something that looks like:

{
  "id": "88b13752-3469-4e46-b4aa-49cd4f1685a6",
  "properties": {
    "max_video_resolution": "960x540"
  }
}

Manually Invoking Actions

Before we dive into conditionally applying our Action, we can manually invoke it and check it does what we want by adding its ID as a parameter to our Playback API request:

https://edge.api.brightcove.com/playback/v1/accounts/5270290572001/videos/6230434222001?config_id=88b13752-3469-4e46-b4aa-49cd4f1685a6

This will now return us the same HLS manifest as before, but with the 1280x720 rendition removed!

As well as being useful for testing, manually invoking rules in this way is a powerful technique for customers that leverage the Brightcove SDKs to build their own apps, allowing them to invoke different rules per-device, per-app or even per-user, just by passing in different Action IDs.

A common usage we see is for our customers to apply an Action to serve a basic type of content to anonymous users, while anyone who signs up has a manual Action applied to serve them richer (higher-quality video and audio, modern codecs such as HEVC, premium CDN provider) content.

Conditionally Invoking Actions

For customers that don't want or need the granularity of manually invoking Actions, we provide a set of pre-canned Conditions to control under what circumstances the Brightcove manifest generation services should apply rules. These will apply to all requests and so are a great way of targetting certain groups of users, regardless of what type of device they're viewing your videos on.

The full set of Conditions offered can be found in the API reference here.

For this tutorial, let's imagine we know that users in the UK have been struggling with buffering high resolutions because of country-wide network capacity issues and so we want to strip out the higher resolution rendition until these are resolved.

PUT /accounts/{accountID}/conditions
  Content-Type: application/json
  Authorization: Bearer {access_token}

This API call takes an array of Conditions but for now we're just creating one, by including the following body with our request:

[
  {
    "name": "Cut off high-quality renditions for the UK",
    "if": {
      "request_country": [
        "GB"
      ]
    },
    "then": [
      "88b13752-3469-4e46-b4aa-49cd4f1685a6"
    ]
  }
]

Now, if we make our standard Playback API request from within the UK (notice no config_id parameter attached this time) then we'll see the high-quality rendition stripped out!

What's Next?

Hopefully this has given you a taste of the power and flexibility of Delivery Rules. The full lists of supported Conditions and Actions can be found here and if there are any others that you'd like us to add in the future, then please reach out to Customer Support or your account rep and let us know!

If you're keen to read more about how our customers are using Delivery Rules then take a look at how Seven West Media Optimises Video Content Delivery With Brightcove’s Delivery Rules.