Creating filters with Media Services REST API

media services logo v3


When delivering your content to customers (streaming Live events or Video on Demand) your client might need more flexibility than what's described in the default asset's manifest file. Azure Media Services enables you to define account filters and asset filters for your content.

For detailed description of this feature and scenarios where it is used, see Dynamic Manifests and Filters.

This topic shows how to define a filter for a Video on Demand asset and use REST APIs to create Account Filters and Asset Filters.

Note

Make sure to review presentationTimeRange.

Prerequisites

To complete the steps described in this topic, you have to:

Define a filter

The following is the Request body example that defines the track selection conditions that are added to the manifest. This filter includes any audio tracks that are EC-3 and any video tracks that have bitrate in the 0-1000000 range.

{
    "properties": {
        "tracks": [
          {
                "trackSelections": [
                    {
                        "property": "Type",
                        "value": "Audio",
                        "operation": "Equal"
                    },
                    {
                        "property": "FourCC",
                        "value": "EC-3",
                        "operation": "Equal"
                    }
                ]
            },
            {
                "trackSelections": [
                    {
                        "property": "Type",
                        "value": "Video",
                        "operation": "Equal"
                    },
                    {
                        "property": "Bitrate",
                        "value": "0-1000000",
                        "operation": "Equal"
                    }
                ]
            }
        ]
     }
}

Create account filters

In the Postman's collection that you downloaded, select Account Filters->Create or update an Account Filter.

The PUT HTTP request method is similar to:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaServices/{accountName}/accountFilters/{filterName}?api-version=2018-07-01

Select the Body tab and paste the json code you defined earlier.

Select Send.

The filter has been created.

For more information, see Create or update. Also, see JSON examples for filters.

Create asset filters

In the "Media Services v3" Postman collection that you downloaded, select Assets->Create or update Asset Filter.

The PUT HTTP request method is similar to:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaServices/{accountName}/assets/{assetName}/assetFilters/{filterName}?api-version=2018-07-01

Select the Body tab and paste the json code you defined earlier.

Select Send.

The asset filter has been created.

For details on how to create or update asset filters, see Create or update. Also, see JSON examples for filters.

Associate filters with Streaming Locator

You can specify a list of asset or account filters, which would apply to your Streaming Locator. The Dynamic Packager (Streaming Endpoint) applies this list of filters together with those your client specifies in the URL. This combination generates a Dynamic Manifest, which is based on filters in the URL + filters you specify on Streaming Locator. We recommend that you use this feature if you want to apply filters but do not want to expose the filter names in the URL.

To create and associate filters with a Streaming Locator using REST, use the Streaming Locators - Create API and specify properties.filters in the Request Body.

Stream using filters

Once you define filters, your clients could use them in the streaming URL. Filters could be applied to adaptive bitrate streaming protocols: Apple HTTP Live Streaming (HLS), MPEG-DASH, and Smooth Streaming.

The following table shows some examples of URLs with filters:

Protocol Example
HLS https://amsv3account-usw22.streaming.media.azure.net/fecebb23-46f6-490d-8b70-203e86b0df58/bigbuckbunny.ism/manifest(format=m3u8-aapl,filter=myAccountFilter)
MPEG DASH https://amsv3account-usw22.streaming.media.azure.net/fecebb23-46f6-490d-8b70-203e86b0df58/bigbuckbunny.ism/manifest(format=mpd-time-csf,filter=myAssetFilter)
Smooth Streaming https://amsv3account-usw22.streaming.media.azure.net/fecebb23-46f6-490d-8b70-203e86b0df58/bigbuckbunny.ism/manifest(filter=myAssetFilter)

Next steps

Stream videos