# Manifest filtering from AWS Elemental MediaPackage Manifest filtering With manifest filtering, AWS Elemental MediaPackage dynamically produces client manifests based on filter parameters that you specify. 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. With manifest filtering, the resulting manifest from MediaPackage includes only the audio and video streams that match the characteristics that you specify in your filters. 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 origin endpoint types supported by MediaPackage. To use manifest filtering, you can do one of the following: + Apply filters to all manifests that originate from an endpoint: Set the filters on the origin endpoint through the MediaPackage console or API. For console instructions, see [Creating an origin endpoint](endpoints-create.md). + Apply filters dynamically across requests: Ensure that downstream video players include the appropriate query parameters in their manifest requests. For information about using query parameters, see [Manifest filtering query parameters](manifest-filter-query-parameters.md). **Note** When configuring Manifest filters as part of the Filter Configuration for your endpoint, be aware that using corresponding query parameters in the manifest's endpoint URL can lead to issues. Specifically, if you include a Manifest filter in your Filter Configuration and then attempt to use matching query parameters in the endpoint URL, you will encounter a `404` HTTP error code. For example, if your Filter Configuration includes a Manifest filter with an `audio_sample_rate` key set to `44100`, and you subsequently make an HTTP request to `https:///?aws.manifestfilter=audio_sample_rate:44100` this will result in a `404` error. The Filter Configuration applies universally to all egress requests for your endpoint, and duplicating these settings in the URL query can lead to conflicts and errors. For more information about Manifest filters, see [Manifest filtering from AWS Elemental MediaPackage](#manifest-filtering). The following topics describe how manifest filtering works with MediaPackage. **Topics** + [Manifest filtering query parameters](manifest-filter-query-parameters.md) + [Special conditions for TS and CMAF manifests](special-conditions-TS-CMAF-manifests.md) + [Manifest filtering examples](manifest-filtering-examples.md) + [Manifest filtering error conditions](error-conditions-and-handling.md) # Manifest filtering query parameters in AWS Elemental MediaPackage Manifest filtering query parameters To use manifest filtering query parameters, append `aws.manifestfilter` to your playback request to MediaPackage. MediaPackage evaluates the query, and serves a client manifest based on those query parameters. The following sections describe how to configure manifest filtering query parameters. **Note** If you are using TS or CMAF origin endpoints, special conditions apply. For information about these conditions, see [Special conditions for TS and CMAF manifests in MediaPackage](special-conditions-TS-CMAF-manifests.md). ## Query parameter formatting Use the following guidelines when constructing query parameters: + Queries are not case sensitive. + Queries can be up to 1,024 characters. + Reserved characters in the queries must be URL encoded as indicated in the [URI: General Syntax](https://datatracker.ietf.org/doc/html/rfc3986) standard. **Important** At a minimum, if your query includes multiple parameters, the following characters in the query must be URL encoded. If they're not, MediaPackage processes just the first query parameter in the string. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/manifest-filter-query-parameters.html) 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. ## 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 filtering query parameters in AWS Elemental MediaPackage](#manifest-filter-query-parameters). **Example HLS filter query** The following example query includes filters for audio sample rate, video bitrate, video codec, and audio language. Note that the reserved characters use URL-encoded values. `https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8?aws.manifestfilter=audio_sample_rate%3A0-44100%3Bvideo_bitrate%3A0-2147483647%3Bvideo_codec%3Ah265%3Baudio_language%3Afr%2Cen-US%2Cde` The query syntax is described in the following table. **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). | 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 filtering query parameters in AWS Elemental MediaPackage](#manifest-filter-query-parameters). | | : | Used to associate the parameter name with a value. For example, parameter\$1name:value. When using multiple query parameters, this character must be URL encoded (%3A). | | ; | Separates parameters in a query that contains multiple parameters. For example, parameter1\$1name:value;parameter2\$1name:minValue-maxValue. When used in a list of parameters for the same query, implies an AND operation.When using multiple query parameters, this character must be URL encoded (%3B). | | , | Separates a list of values. For example, parameter\$1name:value1,value2,value3. Comma-separated values in a list imply an OR relationship.When using multiple query parameters, this character must be URL encoded (%2C). | | - | 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. | ## Query value formats Added formatting for query parameters Added information about how manifest filtering query parameters can be formatted to include multiple queries. The following query parameters support expanded value formats: + `audio_bitrate` + `audio_channels` + `audio_sample_rate` + `trickplay_height` + `video_bitrate` + `video_framerate` + `video_height` For all of these parameters, you can format your values as single values or ranges, one or more ranges, or a combination of both. **Individual values and ranges** Filter manifests by single values or ranges. **Syntax** + Individual single values: `aws.manifestfilter=parameter:value` + Individual range: `aws.manifestfilter=parameter:min1-max1` **Example individual value** The following example filters for videos with a bitrate of 8000000 bps. ``` stream.mpd?aws.manifestfilter=video_bitrate:8000000 ``` When you filter for a single `video_framerate` value, MediaPackage uses an approximate equals comparison with an epsilon tolerance of 0.0005. MediaPackage uses this tolerance because the query allows only up to three decimal places, and there could be a small difference in accuracy between the stored framerates and the specified framerate. For example, if your filter is `video_framerate:30.000`, MediaPackage matches framerates in the range of 29.9995 to 30.0005. **Multiple values and ranges** Filter manifests by multiple single values or multiple ranges. **Syntax** + Multiple single values: `aws.manifestfilter=parameter:value,value` + Multiple ranges: `aws.manifestfilter=parameter:min1-max1,min2-max2` **Example multiple ranges** The following example filters for videos that are either 240p-360p OR 720p-1080p. It uses URL encoding for reserved characters. ``` stream.mpd?aws.manifestfilter=video_height%3A240-360%2C720-1080 ``` **Combination** Filter manifests by a combination of ranges and values. **Syntax** + Multiple ranges and single values: `aws.manifestfilter=parameter:min1-max1,min2-max2,value1,value2` **Example multiple ranges and values** The following example filters for videos that are either 240p-360p, 720p-1080p, 1440p, OR 2160p. It uses URL encoding for reserved characters. ``` stream.mpd?aws.manifestfilter=video_height%3A240-360%2C720-1080%2C1440%2C2160 ``` ## Query parameters MediaPackage supports the following query parameters. You can set one or more filters. For example, to restrict all manifests from this endpoint to 0 to 44000 Hz audio sample rate, 0 to 2147483647 video bitrate, H265 video codec, and French and English languages, enter the following key and value pairs on the origin endpoint: **Filter key** `audio_sample_rate` \$1 **Filter value**: `0-44100` **Filter key** `video_bitrate` \$1 **Filter value**: `0-2147483647` **Filter key** `video_codec` \$1 **Filter value**: `H265` **Filter key** `audio_language` \$1 **Filter value**: `fr,en-US` | Category | Name | Description | Example | | --- | --- | --- | --- | | Audio | audio\$1bitrate | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.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/userguide/manifest-filter-query-parameters.html) | stream.mpd?aws.manifestfilter=video\$1height:720-1080 | | DRM | aws.drmsettings | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/manifest-filter-query-parameters.html) | stream.m3u8?aws.drmsettings=exclude\$1session\$1keys | # Special conditions for TS and CMAF manifests in MediaPackage Special conditions for TS and CMAF manifests If you are using TS or CMAF manifests for MediaPackage, these special conditions apply. + For TS 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 [AWS Elemental MediaPackage rendition groups reference](rendition-groups.md). + In TS 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 TS 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 TS and CMAF manifests, request parameters appended to bitrate playlists or segments result in an HTTP 400 error. # Manifest filtering examples in AWS Elemental MediaPackage Manifest filtering examples These are MediaPackage manifest filtering examples. **Example 1: Include only videos with specific heights** You want to include only videos with heights that the most popular playback devices support. You set the `video_height` to filter out video streams that don't meet one of these height requirements: 240p through 360p, 720p through 1080p, 1440, or 2160p. `?aws.manifestfilter=video_height%3A240-360%2C720-1080%2C1440%2C2160` **Example 2: 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%3A0-44100%3Bvideo_codec%3Ah264` **Example 3: 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 4: 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` # AWS Elemental MediaPackage manifest filtering error conditions Manifest filtering error conditions Common error conditions for manifest filtering with MediaPackage are listed in the following table. **** | 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 TS 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 |