Filtrage des manifestes

Avec le filtrage des manifestes, AWS Elemental MediaPackage produit dynamiquement des manifestes clients en fonction des paramètres que vous spécifiez dans une requête ajoutée à votre demande de lecture. Cela vous permet de restreindre l'accès des spectateurs au contenu 4K HEVC haut de gamme ou de cibler des types d'appareils et des plages de fréquences d'échantillonnage audio spécifiques, le tout à partir d'un seul point de terminaison. Auparavant, vous deviez configurer plusieurs points de terminaison pour obtenir ce comportement. MediaPackage fournit désormais un moyen rentable de produire dynamiquement différents manifestes clients sur le même point de terminaison.

Utilisation de filtres de manifeste

Lorsque vous utilisez un filtre de manifeste, le manifeste obtenu inclut uniquement les flux audio et vidéo qui correspondent aux caractéristiques spécifiées dans votre requête. Si aucun filtre manifeste n'est appliqué, tous les flux ingérés sont présents dans le flux de sortie du point de terminaison. L'exception à cette règle est la définition de filtres de flux pour le point de terminaison (débit binaire vidéo minimum, par exemple). Dans ce cas, le filtre manifeste est appliqué après le filtre de flux, ce qui pourrait fausser votre sortie, et n'est pas recommandé.

Le filtrage des manifestes peut être utilisé sur tous les types de terminaux pris en charge par MediaPackage :

• Apple HLS

• DASH ISO

• Microsoft Smooth Streaming

• CMAF

Pour utiliser le filtrage des manifestes, ajoutez des paramètres de aws.manifestfilter requête à votre demande de lecture sur. MediaPackage MediaPackage évalue la requête et diffuse un manifeste client basé sur ces paramètres de requête. Les requêtes de manifeste ne sont pas sensibles à la casse et peuvent contenir jusqu'à 1024 caractères. Si la requête est mal formée, ou si aucun flux ne correspond aux paramètres de la requête, MediaPackage renvoie un manifeste incomplet ou vide. Pour la syntaxe de la requête, consultez la section suivante.

Note

Si vous utilisez des terminaux Apple HLS ou CMAF, des conditions spéciales s'appliquent. Pour plus d'informations sur ces conditions, consultez Conditions particulières pour les manifestes HLS et CMAF.

Syntaxe de requête

Le paramètre de requête de base est aws.manifestfilter, suivi de paires nom-valeur de paramètre facultatives. Pour créer la requête, ajoutez-la ?aws.manifestfilter= à la fin de l'URL du MediaPackage point de terminaison, suivie des noms et valeurs des paramètres. Pour obtenir la liste de tous les paramètres disponibles, consultez Paramètres de requête de filtre de manifeste.

Une requête de filtre Apple HLS peut ressembler à ceci :

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

La syntaxe de requête est répertoriée dans le tableau suivant.

Composant de chaîne de requête	Description
?	Caractère restreint qui marque le début d'une requête.
aws.manifestfilter=	Requête de base, suivie de paramètres constitués de paires nom-valeur. Pour obtenir la liste de tous les paramètres disponibles, consultez Paramètres de requête de filtre de manifeste.
:	Associe le nom du paramètre à une valeur. Par exemple, parameter_name:value.
;	Sépare les paramètres d'une requête contenant plusieurs paramètres. Par exemple, parameter1_name:value;parameter2_name:minValue-maxValue.
,	Sépare une liste de valeurs. Par exemple, parameter_name:value1,value2,value3. Les valeurs séparées par des virgules dans une liste impliquent une relation OR.
-	Sert à définir la plage de valeurs minimum - maximum d'un paramètre. Par exemple, audio_sample_rate:0-44100. Lorsqu'une valeur numérique est utilisée dans une plage, elle est incluse dans la définition de la plage. Cela signifie que les flux doivent être supérieurs ou égaux à la valeur minimale et inférieurs ou égaux à la valeur maximale. Avec des plages, les valeurs minimale et maximale sont obligatoires. Les valeurs de plage prise en charge sont 0 - 2147483647.

Note

Si vous utilisez Amazon CloudFront comme CDN, vous devrez peut-être définir des configurations supplémentaires. Pour plus d'informations, consultez Configurer les comportements de cache pour tous les points de terminaison.

Paramètres de requête de filtre de manifeste

MediaPackage prend en charge les paramètres de requête suivants.

Catégorie	Name (Nom)	Description	Exemple
Audio	audio_bitrate	Débit audio en bits par seconde. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 0 - 2147483647.	stream.mpd?aws.manifestfilter=audio_bitrate:0-2147483647
Audio	audio_channels	Nombre de canaux audio. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 1 - 32767.	stream.mpd?aws.manifestfilter=audio_channels:1-8
Audio	audio_codec	Type de codec audio. Valeurs acceptées : AACL, AACH, AC-3, EC-3. Vous devez inclure - pour AC-3 et EC-3. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=audio_codec:AACL,AC-3
Audio	audio_language	Langues audio ou codes fonctionnels dérivés de la transmission de l'encodeur. Valeurs acceptées : chaînes arbitraires, telles que des codes de langue ISO-639-1 à deux ou quatre caractères. Vous devez utiliser les mêmes chaînes de langue que celles définies pour votre encodeur. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=audio_language:fr,en-US,de
Audio	audio_sample_rate	Fréquence d'échantillonnage audio en Hz. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 0 - 2147483647.	stream.mpd?aws.manifestfilter=audio_sample_rate:0-44100
Sous-titre	subtitle_language	Langage des sous-titres ou codes fonctionnels dérivés du transfert de l'encodeur. Valeurs acceptées : chaînes arbitraires, telles que des codes de langue ISO-639-1 à deux ou quatre caractères. Vous devez utiliser les mêmes chaînes de langue que celles définies pour votre encodeur. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=subtitle_language:en-US, hi
Vidéo	trickplay_height	Hauteur de l'image du trick-play en pixels. Cela s'applique à la fois au jeu i-Frame uniquement et aux trick-play basés sur des images. Note Si vous utilisez ce paramètre avec I-frame uniquement, jouez avec des astuces trickplay_height et vous video_height devriez avoir des valeurs similaires. Si les valeurs ne sont pas les mêmes, les pistes I-frame uniquement peuvent être supprimées d'un manifeste. Le trickplay_height filtre est appliqué avant le carrelage pour DASH en VOD. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 1 - 2147483647.	stream.mpd?aws.manifestfilter=trickplay_height:200-1200
Vidéo	trickplay_type	Le type de piste de trickplay. Vous pouvez filtrer sur les pistes de trickplay iframe ou image ou utiliser la valeur none pour filtrer toutes les pistes de trickplay (iframe et image). Valeurs acceptées : iframe, image, none. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=trickplay_type:iframe
Vidéo	video_bitrate	Débit vidéo en bits par seconde. Note Si vous utilisez ce paramètre, nous vous recommandons d'utiliser uniquement le paramètre de filtre video_bitrate pour définir le débit binaire vidéo. Ne définissez pas également le débit vidéo minimum et maximum via la MediaPackage console ouAWS CLI. Le filtre video_bitrate s'applique aux paramètres de débit binaire vidéo créés au point de terminaison. Si vous utilisez le paramètre et définissez le débit binaire dans la console ou l'AWS CLI, votre sortie pourrait être faussée. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 0 - 2147483647. Note Vous ne pouvez pas utiliser ce paramètre avec les streams trick-play.	stream.mpd?aws.manifestfilter=video_bitrate:0-2147483647
Vidéo	video_codec	Type de codec vidéo. Valeurs acceptées : H264, H265. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=video_codec:h264
Vidéo	video_dynamic_range	La plage dynamique de la vidéo. Valeurs acceptées : hdr10, hlg, sdr. Les valeurs ne sont pas sensibles à la casse.	stream.mpd?aws.manifestfilter=video_dynamic_range:hdr10
Vidéo	video_framerate	La plage de fréquence d'images vidéo au format NTSC. Valeurs acceptées : deux nombres à virgule flottante agrégés avec un tiret définissant une plage inclusive. Chaque nombre peut comporter jusqu'à trois valeurs fractionnelles facultatives. Par exemple, 29.97 ou 29.764. Les valeurs de plage prise en charge sont 1 - 999.999.	stream.mpd?aws.manifestfilter=video_framerate:23.976-30
Vidéo	video_height	Hauteur de la vidéo en pixels. Note Si vous utilisez ce paramètre avec I-frame uniquement, jouez avec des astuces trickplay_height et vous video_height devriez avoir des valeurs similaires. Si les valeurs ne sont pas les mêmes, les pistes I-frame uniquement peuvent être supprimées d'un manifeste. Valeurs acceptées : deux entiers définissant une plage inclusive et réunis par un tiret. Les valeurs de plage prise en charge sont 1 - 32767.	stream.mpd?aws.manifestfilter=video_height:720-1080

Exemples de filtrage de manifestes

Voici des exemples de filtrage de manifestes.

Exemple 1 : Cibler un lecteur prenant en charge le codec AVC et un taux d'échantillonnage audio de 44.1k.

L'utilisateur en train de lire du contenu sur un périphérique prenant uniquement en charge le codec AVC et un taux d'échantillonnage audio de 44.1k. Vous définissez video_codec et audio_sample_rate pour filtrer les flux qui ne correspondent pas à ces exigences.

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

Exemple 2 : restreindre le contenu HEVC 4k

Votre flux HEVC 4K est de 15 Mbit/s, et tous vos autres flux sont inférieurs à 9 Mbit/s. Pour exclure le flux 4K du jeu de flux, vous définissez un seuil de 9 000 000 bits par seconde pour filtrer le débit le plus élevé.

?aws.manifestfilter=video_bitrate:0-9000000

Exemple 3 : Inclure de la vidéo entre 23,976 et 30 images par seconde

Pour inclure uniquement de la vidéo dans une certaine plage de fréquences d'images, utilisez video_framerate. Ce paramètre accepte les nombres à virgule flottante avec jusqu'à trois valeurs décimales facultatives.

?aws.manifestfilter=video_framerate:23.976-30

Conditions particulières pour les manifestes HLS et CMAF

Si vous utilisez des manifestes HLS ou CMAF, ces conditions particulières s'appliquent.

• Pour les manifestes HLS, nous vous recommandons fortement d'utiliser des groupes de rendu audio pour éviter de supprimer les flux vidéo qui sont multiplexés avec les flux audio filtrés. Pour en savoir plus sur les groupes de rendu, consultez Les groupes de rendus font référence dans AWS Elemental MediaPackage.

• Dans les manifestes HLS et CMAF, la fréquence d'échantillonnage audio n'est pas signalée. Il n'est donc pas facile d'inspecter visuellement les manifestes originaux ou filtrés pour ce paramètre. Pour vérifier la fréquence d'échantillonnage audio, consultez la fréquence d'échantillonnage audio au niveau de l'encodeur et de la sortie.

• Dans les manifestes HLS et CMAF, l'attribut BANDWIDTH d'une variante associe la bande passante de la piste audio à la piste vidéo, qu'elle soit multiplexée ou non avec la piste vidéo, ou s'il s'agit d'une piste de rendu audio référencée par la piste vidéo. Par conséquent, vous ne pouvez pas inspecter visuellement les manifestes d'origine et filtrés pour confirmer que le video_bitrate filtre fonctionne. Pour le vérifier, consultez le débit binaire vidéo au niveau de l'encodeur et de la sortie.

• Pour les manifestes HLS et CMAF, les paramètres de requête ajoutés aux segments ou listes de lecture de débit binaire engendrent une erreur HTTP 400.

Conditions d'erreur

Les conditions d'erreur courantes sont répertoriées dans le tableau suivant.

Condition d'erreur	Exemple	Code de statut HTTP
Un paramètre de liste est introuvable et ne fait pas partie d'une liste limitée	?aws.manifestfilter=audio_language:dahlia	200
Seuls les flux des sous-titres sont présents dans le flux	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	200
Paramètre de filtre en double	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=audio_sample_rate:0-48000	400
Paramètre non valide	?aws.manifestfilter=donut_type:rhododendron	400
Paramètre de plage non valide	?aws.manifestfilter=audio_sample_rate:300-0	400
Valeur de plage non valide (supérieure à INT_MAX)	?aws.manifestfilter=audio_sample_rate:0-2147483648	400
Chaîne de requête mal formée	?aws.manifestfilter=audio_sample_rate:is:0-44100	400
La chaîne de paramètre est supérieure à 1024 caractères	?aws.manifestfilter=audio_language:abcdef....	400
Paramètres de requête sur un manifeste de débit binaire HLS ou CMAF	index_1.m3u8?aws.manifestfilter=video_codec:h264	400
Paramètres de requête sur une demande de segment	..._1.[ts|mp4|vtt..]?aws.manifestfilter=video_codec:h264	400
Paramètre de requête répétée	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=video_bitrate:0-1	400
L'application du filtre débouche sur un manifeste vide (le contenu n'a pas de flux répondant aux conditions définies dans la chaîne de requête)	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	400