Filters

When delivering your content to customers (Live Streaming 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 offers Dynamic Manifests based on pre-defined filters.

Filters are server-side rules that allow your customers to do things like:

• Play back only a section of a video (instead of playing the whole video). For example:
  • Reduce the manifest to show a sub-clip of a live event ("sub-clip filtering"), or
  • Trim the start of a video ("trimming a video").
• Deliver only the specified renditions and/or specified language tracks that are supported by the device that is used to play back the content ("rendition filtering").
• Adjust Presentation Window (DVR) in order to provide a limited length of the DVR window in the player ("adjusting presentation window").

Media Services enables you to create Account filters and Asset filters for your content. In addition, you can associate your pre-created filters with a Streaming Locator.

Filter types

There are two types of filters:

• Account Filters (global) - can be applied to any asset in the Azure Media Services account, have a lifetime of the account.
• Asset Filters (local) - can only be applied to an asset with which the filter was associated upon creation, have a lifetime of the asset.

Account Filters and Asset Filters types have exactly the same properties for defining/describing the filter. Except when creating the Asset Filter, you need to specify the asset name with which you want to associate the filter.

Depending on your scenario, you decide what type of a filter is more suitable (Asset Filter or Account Filter). Account Filters are suitable for device profiles (rendition filtering) where Asset Filters could be used to trim a specific asset.

You use the following properties to describe the filters.

presentationTimeRange

Use this property with Asset Filters. It isn't recommended to set the property with Account Filters.

Tracks

You specify a list of filter track property conditions (FilterTrackPropertyConditions) based on which the tracks of your stream (Live Streaming or Video on Demand) should be included into dynamically created manifest. The filters are combined using a logical AND and OR operation.

Filter track property conditions describe track types, values (described in the following table), and operations (Equal, NotEqual).

Example

The following example defines a Live Streaming filter:

{
  "properties": {
    "presentationTimeRange": {
      "startTimestamp": 0,
      "endTimestamp": 170000000,
      "presentationWindowDuration": 9223372036854776000,
      "liveBackoffDuration": 0,
      "timescale": 10000000,
      "forceEndTimestamp": false
    },
    "firstQuality": {
      "bitrate": 128000
    },
    "tracks": [
      {
        "trackSelections": [
          {
            "property": "Type",
            "operation": "Equal",
            "value": "Audio"
          },
          {
            "property": "Language",
            "operation": "NotEqual",
            "value": "en"
          },
          {
            "property": "FourCC",
            "operation": "NotEqual",
            "value": "EC-3"
          }
        ]
      },
      {
        "trackSelections": [
          {
            "property": "Type",
            "operation": "Equal",
            "value": "Video"
          },
          {
            "property": "Bitrate",
            "operation": "Equal",
            "value": "3000000-5000000"
          }
        ]
      }
    ]
  }
}

Filter your HLS or DASH manifests on creation of Streaming Locator

Media Services allows you to create a Streaming Locator that is pre-filtered by passing in a collection of filters in the filter property on the streaming locator entity. This allows you to pre-filter all manifests on the streaming locator. The original manifest is no longer available through this streaming locator, and only the filtered response will be accessible to clients requesting the URLs for DASH or HLS from the filtered streaming locator. This is helpful in situations where you want to only publish a portion of an asset, and prevent users from gaining access to the full original manifest for the asset by manipulating the query string of the HLS or DASH manifest URL.

You can specify a list of asset or account filters on your Streaming Locator. The Dynamic Packager 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 the Streaming Locator.

Updating filters

Filters and streaming locators can be updated on the fly, but keep in mind that it can take up to 10 seconds for any updates to update on the front-end web servers, and there can be issues if you are updating the same Streaming Locator that has been published and used in production already.

It isn't recommended to update the definition of filters associated with an actively published Streaming Locator. Streaming servers can have internal caches that may result in stale cached data to be returned.

If the filter definition needs to be changed consider creating a new filter and adding it to the Streaming Locator URL or publishing a uniquely new Streaming Locator that references the updated filter directly.