# 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\$1name:value. | 
| ; | Separates parameters in a query that contains multiple parameters. For example, parameter1\$1name:value;parameter2\$1name:minValue-maxValue. | 
| , | Separates a list of values. For example, parameter\$1name: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\$1sample\$1rate: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\$1bitrate |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=audio\$1bitrate:0-2147483647 | 
| Audio | audio\$1channels |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=audio\$1channels:1-8 | 
| Audio | audio\$1codec |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=audio\$1codec:AACL,AC-3 | 
| Audio | audio\$1language |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=audio\$1language:fr,en-US,de | 
| Audio | audio\$1sample\$1rate |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=audio\$1sample\$1rate:0-44100 | 
| Subtitle | subtitle\$1language |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=subtitle\$1language:en-US, hi | 
| Video | trickplay\$1height |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=trickplay\$1height:200-1200 | 
| Video | trickplay\$1type |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=trickplay\$1type:iframe | 
| Video | video\$1bitrate |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=video\$1bitrate:0-2147483647 | 
| Video | video\$1codec |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=video\$1codec:h264 | 
| Video | video\$1dynamic\$1range |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=video\$1dynamic\$1range:hdr10 | 
| Video | video\$1framerate |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=video\$1framerate:23.976-30 | 
| Video | video\$1height |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html)  | stream.mpd?aws.manifestfilter=video\$1height: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\$1language:dahlia | 200 | 
| Only subtitle streams are present in the stream | ?aws.manifestfilter=audio\$1sample\$1rate:0-1;video\$1bitrate=0-1 | 200 | 
| Duplicate filter parameter | ?aws.manifestfilter=audio\$1sample\$1rate:0-48000;aws.manifestfilter=audio\$1sample\$1rate:0-48000 | 400 | 
| Invalid parameter | ?aws.manifestfilter=donut\$1type:rhododendron | 400 | 
| Invalid range parameter | ?aws.manifestfilter=audio\$1sample\$1rate:300-0 | 400 | 
| Invalid range value (more than INT\$1MAX) | ?aws.manifestfilter=audio\$1sample\$1rate:0-2147483648 | 400 | 
| Malformed query string | ?aws.manifestfilter=audio\$1sample\$1rate:is:0-44100 | 400 | 
| Parameter string is greater than 1024 characters | ?aws.manifestfilter=audio\$1language:abcdef.... | 400 | 
| Query parameters on an HLS or CMAF bitrate manifest | index\$11.m3u8?aws.manifestfilter=video\$1codec:h264 | 400 | 
| Query parameters on a segment request | ...\$11.[ts\$1mp4\$1vtt..]?aws.manifestfilter=video\$1codec:h264 | 400 | 
| Repeated query parameter | ?aws.manifestfilter=audio\$1sample\$1rate:0-48000;aws.manifestfilter=video\$1bitrate: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\$1sample\$1rate:0-1;video\$1bitrate=0-1 | 400 |