Playback filters

A filter publishes a shaped version of an asset without creating a new one. Use a filter when the manifest should expose only part of the content, only certain tracks, or a different startup quality. Filters shape the manifest at playback time; they do not reprocess content. The asset holds the full media, the filter describes the subset, and the streaming locator applies the filter when it publishes.

Choosing the filter scope

There are two scopes, and the choice is about reuse.

Both use the same MediaFilterProperties body, which supports three controls: presentationTimeRange to clip a time window, tracks to select tracks, and firstQuality to set the startup bitrate.

Clip a time window

This asset filter exposes only the section from 10 to 70 seconds. With timescale set to 1, the timestamps are in seconds.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/assetFilters/highlights" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "presentationTimeRange": {
        "timescale": 1,
        "startTimestamp": 10,
        "endTimestamp": 70
      }
    }
  }'

timescale is the number of units per second. It defaults to 10000000 (100-nanosecond units), so set it to 1 when you want to work in whole seconds. The same block also supports the live-only fields presentationWindowDuration (the rewind window) and liveBackoffDuration (the delay from the live edge).

Select tracks

This account filter includes audio tracks that are not English, and video tracks between 3 and 5 megabits per second.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/accountFilters/non-english-mid-bitrate" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "tracks": [
        {
          "trackSelections": [
            { "property": "Type", "operation": "Equal", "value": "audio" },
            { "property": "Language", "operation": "NotEqual", "value": "en" }
          ]
        },
        {
          "trackSelections": [
            { "property": "Type", "operation": "Equal", "value": "video" },
            { "property": "Bitrate", "operation": "Equal", "value": "3000000-5000000" }
          ]
        }
      ]
    }
  }'

The selectable properties are Type (video, audio, text), Name, Language (an RFC 5646 tag such as en or en-US), FourCC (a codec such as avc1 or mp4a), and Bitrate (a single value or a range like 3000000-5000000). Values are case-insensitive, and each property uses an operation of Equal or NotEqual.

The nesting controls the logic, and it is easy to misread:

• Conditions inside one trackSelections array are combined with AND.
• Entries in the top-level tracks array are combined with OR.

So the filter above means "(audio AND not English) OR (video AND 3-5 Mbps)".

Set the startup quality

Add firstQuality to start HLS playback near a target bitrate. The closest available rung in the ladder is used if the exact bitrate is absent.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/accountFilters/high-start-quality" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "firstQuality": { "bitrate": 5000000 }
    }
  }'

Apply the filter

A filter does nothing until a streaming locator references it by name in the filters list. The list accepts both asset and account filters.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/streamingLocators/highlights-locator" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "assetName": "source-video",
      "streamingPolicyName": "Predefined_ClearStreamingOnly",
      "filters": ["highlights"]
    }
  }'

What goes wrong

• The filter has no effect. A filter only applies when a locator lists it in filters. Creating the filter alone changes nothing.
• Time values look wrong. Without timescale: 1, timestamps are in 100-nanosecond units by default. Set timescale to match the unit you intend.
• A delete is rejected. A filter cannot be deleted while an active streaming locator still references it. Remove it from the locator first.

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/assetFilters/highlights" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

What comes next

• Streaming and publishing: apply filters at publication time.
• Assets: use an asset filter when the rule belongs to one asset.