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.

• Terminal window

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

Add a filter name to the streaming locator’s filters list to apply it to playback through that locator. 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"]
    }
  }'

You can also request named filters in the manifest URL with filter=, using a semicolon-separated list of asset or account filter names. For example, filter=highlights applies the named filter to that playback request. See Streaming locators for the complete manifest URL syntax.

What goes wrong

• The filter has no effect. Confirm that the locator lists it in filters or that the manifest URL requests it with filter=. Creating a filter alone does not apply it to playback.

• 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.