清单筛选

通过清单筛选，AWS Elemental MediaPackage 可根据您在追加到播放请求的查询中指定的参数动态生成客户端清单。这使您能够从一个端点执行某些操作，比如限制观看者对优质 4K HEVC 内容的访问，或定位特定设备类型和音频采样率范围。以前，您必须配置多个端点才能完成此行为。 MediaPackage 现在提供了一种经济实惠的方式，可以在同一个端点上动态生成不同的客户端清单。

使用清单筛选条件

使用清单筛选条件时，生成的清单仅包括与您在查询中指定的特征匹配的音频流和视频流。如果未使用清单筛选条件，则所有接收的流都会出现在终端节点输出流中。例外情况是，如果您已为终端节点设置流筛选条件，例如最小视频比特率。在这种情况下，清单筛选条件会在流筛选条件之后应用，这可能会使输出偏斜，因而不建议使用。

清单筛选可用于以下支持的所有终端节点类型 MediaPackage：

• Apple HLS

• DASH-ISO

• Microsoft Smooth Streaming

• CMAF

要使用清单筛选，请将aws.manifestfilter查询参数附加到您的播放请求中。 MediaPackage MediaPackage 评估查询，并根据这些查询参数提供客户端清单。清单查询不 区分大小写，长度最多为 1024 个字符。如果查询格式不正确，或者它没有与查询参数匹配的流，则 MediaPackage 返回不完整的清单或空清单。有关查询语法，请参阅以下部分。

注意

如果使用 Apple HLS 或 CMAF 端点，则需要满足特殊条件。有关这些条件的信息，请参阅HLS 和 CMAF 清单的特殊条件。

查询语法

基本查询参数为 aws.manifestfilter，后跟可选参数名称和值对。要构造查询，请在 MediaPackage 端点 URL 的末尾附加?aws.manifestfilter=参数名称和值。有关所有可用参数的列表，请参阅清单筛选条件查询参数。

Apple HLS 筛选条件查询可能如下所示：

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

下表列出了查询语法。

查询字符串组件	描述
?	标记查询开始的受限字符。
aws.manifestfilter=	基本查询，后跟由名称和值对构造的参数。有关所有可用参数的列表，请参阅清单筛选条件查询参数。
:	用于将参数名称与值关联。例如，parameter_name:value。
;	在包含多个参数的查询中分隔参数。例如，parameter1_name:value;parameter2_name:minValue-maxValue。
,	分隔值的列表。例如，parameter_name:value1,value2,value3。列表中以逗号分隔的值表示存在 OR 关系。
-	用于定义参数的最小值-最大值范围。例如，audio_sample_rate:0-44100。当数值用在范围中时，数值将包含在范围定义中。这意味着流必须大于或等于最小值，并且小于或等于最大值。对于范围，最小值和最大值是必需的。支持的范围值为 0 - 2147483647。

注意

如果您使用 Amazon CloudFront 作为 CDN，则可能需要设置其他配置。有关更多信息，请参阅为所有终端节点配置缓存行为。

清单筛选条件查询参数

MediaPackage 支持以下查询参数。

类别	名称	描述	示例
音频	audio_bitrate	音频比特率（单位：比特/秒）。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 0 - 2147483647。	stream.mpd?aws.manifestfilter=audio_bitrate:0-2147483647
音频	audio_channels	音频通道数。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 1 - 32767。	stream.mpd?aws.manifestfilter=audio_channels:1-8
音频	audio_codec	音频编解码器类型。 可接受的值：AACL、AACH、AC-3 和 EC-3。对于 AC-3 和 EC-3，您必须包括 -。 值不 区分大小写。	stream.mpd?aws.manifestfilter=audio_codec:AACL,AC-3
音频	audio_language	从编码器直通 (passthrough) 派生的音频语言或功能代码。 可接受的值：任意字符串，如两字符或四字符 ISO-639-1 语言代码。您必须使用为编码器设置的相同语言字符串。 值不 区分大小写。	stream.mpd?aws.manifestfilter=audio_language:fr,en-US,de
音频	audio_sample_rate	音频采样率（单位：Hz）。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 0 - 2147483647。	stream.mpd?aws.manifestfilter=audio_sample_rate:0-44100
子标题	subtitle_language	从编码器传递派生的字幕语言或功能代码。 可接受的值：任意字符串，如两字符或四字符 ISO-639-1 语言代码。您必须使用为编码器设置的相同语言字符串。 值不 区分大小写。	stream.mpd?aws.manifestfilter=subtitle_language:en-US, hi
视频	trickplay_height	trick-play 映像的高度（单位：像素）。适用于仅限 I-frame 和基于映像的 trick-play。 注意 如果将此参数与仅限 I-frame 一起使用，trickplay_height 和 video_height 应具有相似的值。如果值不同，则可能会从清单中删除仅限 I-frame 轨道。 在 VOD 上为 DASH 平铺之前应用trickplay_height过滤器。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 1 - 2147483647。	stream.mpd?aws.manifestfilter=trickplay_height:200-1200
视频	trickplay_type	trickplay 轨道类型。您可以对 iframe 或映像 trickplay 轨道进行筛选，也可以使用值 none 筛选掉所有 trickplay 轨道（iframe 和映像）。 可接受的值：iframe、image 和 none。 值不 区分大小写。	stream.mpd?aws.manifestfilter=trickplay_type:iframe
视频	video_bitrate	视频比特率（单位：比特/秒）。 注意 如果您使用此参数，我们建议您仅使用 video_bitrate 筛选条件参数来设置视频比特率。也不要通过 MediaPackage 主机设置视频比特率的最小和最大值，或者AWS CLI。video_bitrate 筛选条件应用于在终端节点上创建的视频比特率设置。如果您使用此参数并在控制台或 AWS CLI 中设置比特率，则输出可能会偏斜。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 0 - 2147483647。 注意 您不能将此参数用于 trick-play 流。	stream.mpd?aws.manifestfilter=video_bitrate:0-2147483647
视频	video_codec	视频编解码器类型。 可接受的值： H264、H265。 值不 区分大小写。	stream.mpd?aws.manifestfilter=video_codec:h264
视频	video_dynamic_range	视频动态范围。 可接受的值：hdr10、hlg 和 sdr。 值不 区分大小写。	stream.mpd?aws.manifestfilter=video_dynamic_range:hdr10
视频	video_framerate	NTSC 格式的视频帧速率范围。 可接受的值：用短划线连接的两个浮点数，用于定义包含的范围（含两端的值）。每个浮点数最多可以有三个可选的小数值。例如，29.97 或 29.764。支持的范围值为 1 - 999.999。	stream.mpd?aws.manifestfilter=video_framerate:23.976-30
视频	video_height	视频的高度，以像素为单位。 注意 如果将此参数与仅限 I-frame 一起使用，trickplay_height 和 video_height 应具有相似的值。如果值不同，则可能会从清单中删除仅限 I-frame 轨道。 可接受的值：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 1 - 32767。	stream.mpd?aws.manifestfilter=video_height:720-1080

清单筛选示例

这些是清单筛选示例。

例 1：确定目标为支持 AVC 和 44.1k 音频采样率的播放器

查看器正在仅支持 AVC 和 44.1k 音频采样率的设备上播放内容。您可以设置 video_codec 和 audio_sample_rate 以筛选掉不符合这些要求的流。

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

例 2：限制 4K HEVC 内容

您的 4K HEVC 流是 15 Mbps，所有其他流都小于 9 Mbps。要从流集中排除 4K 流，您可以将阈值设置为每秒 9,000,000 位，以筛选掉更高的比特率。

?aws.manifestfilter=video_bitrate:0-9000000

例 3：包括帧速率在每秒 23.976 到 30 之间的视频

要只包含特定帧速率范围内的视频，请使用 video_framerate。此参数接受最多具有三个可选小数值的浮点数。

?aws.manifestfilter=video_framerate:23.976-30

HLS 和 CMAF 清单的特殊条件

如果您使用的是 HLS 或 CMAF 清单，则这些特殊条件适用。

• 对于 HLS 清单，我们强烈建议您使用音频渲染组，以避免删除与筛选掉的音频流进行多路复用的视频流。有关副本组的更多信息，请参阅AWS Elemental MediaPackage 中的副本组参考。

• 在 HLS 和 CMAF 清单中，不会发出音频采样率信号，因此不容易直观地检查此设置的原始清单或筛选后的清单。要验证音频采样率，请检查编码器级别和输出级别的音频采样率。

• 在 HLS 和 CMAF 清单中，变体的 BANDWIDTH 属性将音频轨道的带宽与视频轨道相关联，无论它是与视频轨道多路复用，还是它为由视频轨道引用的音频轨道。因此，您无法直观地检查原始清单和筛选的清单来确认 video_bitrate 筛选条件是否正常工作。要验证筛选条件，请检查编码器级别和输出级别的视频比特率。

• 对于 HLS 和 CMAF 清单，附加到比特率播放列表或分段的请求参数会导致 HTTP 400 错误。

错误条件

下表列出了常见错误条件。

错误条件	示例	HTTP 状态代码
列表参数未找到且不是约束列表的一部分	?aws.manifestfilter=audio_language:dahlia	200
流中只存在字幕流	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	200
重复的筛选条件参数	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=audio_sample_rate:0-48000	400
参数无效	?aws.manifestfilter=donut_type:rhododendron	400
范围参数无效	?aws.manifestfilter=audio_sample_rate:300-0	400
范围值无效（大于 INT_MAX）	?aws.manifestfilter=audio_sample_rate:0-2147483648	400
查询字符串格式错误	?aws.manifestfilter=audio_sample_rate:is:0-44100	400
参数字符串大于 1024 个字符	?aws.manifestfilter=audio_language:abcdef....	400
HLS 或 CMAF 比特率清单上的查询参数	index_1.m3u8?aws.manifestfilter=video_codec:h264	400
分段请求上的查询参数	..._1.[ts|mp4|vtt..]?aws.manifestfilter=video_codec:h264	400
重复的查询参数	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=video_bitrate:0-1	400
应用筛选条件会导致空清单（内容中没有可满足查询字符串中所定义的条件的流）	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	400