# Manifest filtering
<a name="manifest-filtering"></a>

With manifest filtering, AWS Elemental MediaPackage dynamically produces client manifests based on parameters that you specify in a query appended to your playback request. This enables you to do things such as restrict viewer access to premium 4K HEVC content, or target specific device types and audio sample rate ranges, all from a single endpoint. Previously, you would have to configure multiple endpoints to accomplish this behavior. MediaPackage now provides a cost-effective way to dynamically produce different client manifests on the same endpoint.

## Working with manifest filters
<a name="working-with-manifest-filters"></a>

When you use a manifest filter, the resulting manifest includes only the audio and video streams that match the characteristics that you specify in your query. If no manifest filter is used, then all of the ingested streams are present in the endpoint output stream. The exception to this is if you have set stream filters for the endpoint, such as minimum video bitrate. In that case, the manifest filter is applied after the stream filter, which could skew your output, and is not recommended.

Manifest filtering can be used on all endpoint types supported by MediaPackage:
+ Apple HLS
+ DASH-ISO
+ Microsoft Smooth Streaming
+ CMAF

To use manifest filtering, append `aws.manifestfilter` query parameters to your playback request to MediaPackage. MediaPackage evaluates the query, and serves a client manifest based on those query parameters. Manifest queries are *not *case-sensitive and can be up to 1024 characters long. If the query is malformed, or if it there aren't streams that match the query parameters, MediaPackage returns an incomplete or empty manifest. For query syntax, see the following section.

**Note**  
If you are using Apple HLS or CMAF endpoints, special conditions apply. For information about these conditions, see [Special conditions for HLS and CMAF manifests](#special-conditions-HLS-CMAF-manifests).

**Query syntax**  
The base query parameter is `aws.manifestfilter`, which is followed by optional parameter name and value pairs. To construct the query, append `?aws.manifestfilter=` to the end of the MediaPackage endpoint URL, followed by parameter names and values. For a list of all of the available parameters, see [Manifest filter query parameters](#manifest-filter-query-parameters).

An Apple HLS filter query might look like this:

`https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8{{?aws.manifestfilter=audio_sample_rate:0-44100;video_bitrate:0-2147483647;video_codec:h265;audio_language:fr,en-US,de}}`

The query syntax is listed in the following table.


| Query string component | Description | 
| --- | --- | 
| ? | A restricted character that marks the beginning of a query. | 
| aws.manifestfilter= | The base query, which is followed by parameters constructed of name and value pairs. For a list of all of the available parameters, see [Manifest filter query parameters](#manifest-filter-query-parameters). | 
| : | Used to associate the parameter name with a value. For example, {{parameter\_name}}:{{value}}. | 
| ; | Separates parameters in a query that contains multiple parameters. For example, {{parameter1\_name:value}};{{parameter2\_name:minValue-maxValue}}. | 
| , | Separates a list of values. For example, parameter\_name:{{value1}},{{value2}},{{value3}}. Comma-separated values in a list imply an OR relationship. | 
| - | Used to define a parameter's minimum - maximum value range. For example, audio\_sample\_rate:0-44100. When a numerical value is used in a range, it is included in the range definition. This means that streams must be greater than or equal to the minimum value, and less than or equal to the maximum value. With ranges, the minimum and maximum values are mandatory. The supported range values are 0 - 2147483647. | 

**Note**  
If you use Amazon CloudFront as your CDN, you might need to set additional configurations. For more information, see [Configure cache behavior for all endpoints.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/live-streaming.html#live-streaming-with-mediapackage-create-cache-behavior).

## Manifest filter query parameters
<a name="manifest-filter-query-parameters"></a>

MediaPackage supports the following query parameters.


| Category | Name | Description | Example | 
| --- | --- | --- | --- | 
| Audio | audio\_bitrate |  +  The audio bitrate in bits per second. <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `0` - `2147483647`.   | stream.mpd?aws.manifestfilter=audio\_bitrate:0-2147483647 | 
| Audio | audio\_channels |  +  The number of audio channels. <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `1` - `32767`.   | stream.mpd?aws.manifestfilter=audio\_channels:1-8 | 
| Audio | audio\_codec |  +  The audio codec type. <br />+  **Accepted values**: `AACL`, `AACH`, `AC-3`, `EC-3`. You must include the `-` for `AC-3` and `EC-3`. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=audio\_codec:AACL,AC-3 | 
| Audio | audio\_language |  +  Audio languages or functional codes derived from encoder passthrough. <br />+  **Accepted values**: Arbitrary strings, such as two or four character [ISO-639-1](https://www.andiamo.co.uk/resources/iso-language-codes/) language codes. You must use the same language strings that are set for your encoder. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=audio\_language:fr,en-US,de | 
| Audio | audio\_sample\_rate |  +  The audio sample rate in Hz. <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `0` - `2147483647`.   | stream.mpd?aws.manifestfilter=audio\_sample\_rate:0-44100 | 
| Subtitle | subtitle\_language |  +  The subtitle language or functional codes derived from encoder passthrough. <br />+  **Accepted values**: Arbitrary strings, such as two or four character [ISO-639-1](https://www.andiamo.co.uk/resources/iso-language-codes/) language codes. You must use the same language strings that are set for your encoder. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=subtitle\_language:en-US, hi | 
| Video | trickplay\_height |  +  The height of the trick-play image in pixels. This applies to both I-frame only and image-based trick-play.  If you're using this parameter with I-frame only trick-play, `trickplay_height` and `video_height` should have similar values. If the values are not the same, I-frame only tracks might be removed from a manifest.  <br />+  The `trickplay_height` filter is applied before tiling for DASH on VOD. <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `1` - `2147483647`.   | stream.mpd?aws.manifestfilter=trickplay\_height:200-1200 | 
| Video | trickplay\_type |  +  The trickplay track type. You can filter on iframe or image trickplay tracks or use the value `none` to filter out all trickplay tracks (both iframe and image). <br />+  **Accepted values**: `iframe`, `image`, `none`. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=trickplay\_type:iframe | 
| Video | video\_bitrate |  +  The video bitrate in bits per second.  If you're using this parameter, we recommend that you use only the `video_bitrate` filter parameter to set the video bitrate. Don't also set the minimum and maximum video bitrate via the MediaPackage console or AWS CLI. The `video_bitrate` filter applies to the video bitrate settings created at the endpoint. If you use the parameter and set the bitrate in the console or AWS CLI, your output might be skewed.  <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `0` - `2147483647`. <br />+   You can't use this parameter with trick-play streams.    | stream.mpd?aws.manifestfilter=video\_bitrate:0-2147483647 | 
| Video | video\_codec |  +  The video codec type. <br />+  **Accepted values**: `H264`, `H265`. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=video\_codec:h264 | 
| Video | video\_dynamic\_range |  +  The video dynamic range. <br />+  **Accepted values**: `hdr10`, `hlg`, `sdr`. <br />The values are *not *case-sensitive.   | stream.mpd?aws.manifestfilter=video\_dynamic\_range:hdr10 | 
| Video | video\_framerate |  +  The video frame rate range in the NTSC format. <br />+  **Accepted values**: Two floating-point numbers aggregated with a dash that define an inclusive range. Each number can have up to three optional fractional values. For example, `29.97` or `29.764`. The supported range values are `1` - `999.999`.   | stream.mpd?aws.manifestfilter=video\_framerate:23.976-30 | 
| Video | video\_height |  +  The height of the video in pixels.  If you're using this parameter with I-frame only trick-play, `trickplay_height` and `video_height` should have similar values. If the values are not the same, I-frame only tracks might be removed from a manifest.  <br />+  **Accepted values**: Two integers aggregated with a dash that define an inclusive range. The supported range values are `1` - `32767`.   | stream.mpd?aws.manifestfilter=video\_height:720-1080 | 

## Manifest filtering examples
<a name="manifest-filtering-examples"></a>

These are manifest filtering examples.

**Example 1: Target a player that supports AVC and a 44.1k audio sample rate**  
The viewer is playing content on a device that can only support AVC and a 44.1k audio sample rate. You set the `video_codec` and `audio_sample_rate` to filter out streams that don't fit these requirements.

`?aws.manifestfilter=audio_sample_rate:0-44100;video_codec:h264`

**Example 2: Restrict 4k HEVC content**  
Your 4K HEVC stream is 15 Mbps, and all your other streams are less than 9 Mbps. To exclude the 4K stream from the stream set, you set a threshold of 9,000,000 bits per second to filter out the higher bitrate.

`?aws.manifestfilter=video_bitrate:0-9000000`

**Example 3: Include video between 23.976 and 30 frames per second**  
To only include video within a certain frame rate range, use `video_framerate`. This parameter accepts floating-point numbers with up to three optional decimal values.

`?aws.manifestfilter=video_framerate:23.976-30`

## Special conditions for HLS and CMAF manifests
<a name="special-conditions-HLS-CMAF-manifests"></a>

If you are using HLS or CMAF manifests, these special conditions apply.
+ For HLS manifests, we strongly recommend that you use audio rendition groups to avoid removing the video streams that are multiplexed with the audio streams that are filtered out. For more information about rendition groups, see [Rendition groups reference in AWS Elemental MediaPackage](rendition-groups.md).
+ In HLS and CMAF manifests, the audio sample rate is not signaled, so it's not easy to visually check the original or filtered manifests for this setting. To verify the audio sample rate, check the audio sample rate at the encoder level and output level.
+ In HLS and CMAF manifests, the `BANDWIDTH` attribute for a variant associates the bandwidth of the audio track with the video track, whether it is multiplexed with the video track, or if it is an audio rendition track referenced by the video track. Therefore, you can't visually inspect the original and filtered manifests to confirm the `video_bitrate` filter has worked. To verify the filter, check the video bitrate at the encoder level and output level.
+ For HLS and CMAF manifests, request parameters appended to bitrate playlists or segments result in an HTTP 400 error.

## Error conditions
<a name="error-conditions-and-handling"></a>

Some playback devices will return errors if the manifest or segments include invalid or unknown query parameters. The following are query parameters that MediaPackage can process:
+ `m`
+ `start`
+ `end`
+ `aws.manifestfilter`
+ `aws.drmsettings`

If you have query parameters other than those listed, use a CDN such as Amazon CloudFront to remove the unnecessary parameters. For more information, see [Cache content based on query string parameters](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html) in the *Amazon CloudFront Developer Guide*.

The following table contains additional common error conditions. 



| Error condition | Example | HTTP status code | 
| --- | --- | --- | 
| A list parameter is not found and is not part of a constrained list | ?aws.manifestfilter=audio\_language:dahlia | 200 | 
| Only subtitle streams are present in the stream | ?aws.manifestfilter=audio\_sample\_rate:0-1;video\_bitrate=0-1 | 200 | 
| Duplicate filter parameter | ?aws.manifestfilter=audio\_sample\_rate:0-48000;aws.manifestfilter=audio\_sample\_rate:0-48000 | 400 | 
| Invalid parameter | ?aws.manifestfilter=donut\_type:rhododendron | 400 | 
| Invalid range parameter | ?aws.manifestfilter=audio\_sample\_rate:300-0 | 400 | 
| Invalid range value (more than INT\_MAX) | ?aws.manifestfilter=audio\_sample\_rate:0-2147483648 | 400 | 
| Malformed query string | ?aws.manifestfilter=audio\_sample\_rate:is:0-44100 | 400 | 
| Parameter string is greater than 1024 characters | ?aws.manifestfilter=audio\_language:abcdef.... | 400 | 
| Query parameters on an HLS or CMAF bitrate manifest | index\_1.m3u8?aws.manifestfilter=video\_codec:h264 | 400 | 
| Query parameters on a segment request | ...\_1.[ts\|mp4\|vtt..]?aws.manifestfilter=video\_codec:h264 | 400 | 
| Repeated query parameter | ?aws.manifestfilter=audio\_sample\_rate:0-48000;aws.manifestfilter=video\_bitrate:0-1 | 400 | 
| Application of the filter results in an empty manifest (content has no streams that meet the conditions defined in the query string) | ?aws.manifestfilter=audio\_sample\_rate:0-1;video\_bitrate=0-1 | 400 | 

## See also

* **Skills for AI coding assistants (optional).** AWS publishes reusable skills for AWS Elemental MediaPackage V1. To see which apply, search the Agent Toolkit for AWS catalog with `aws agent-toolkit search-skills --search-query mediapackage` — a documented, read-only AWS CLI command that searches the catalog and makes no changes. This is an optional suggestion for the user. Official reference: [AWS CLI — Agent Toolkit for AWS](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/aws-cli.html).