Filtragem de manifestos

Com a filtragem de manifestos, o AWS Elemental MediaPackage produz dinamicamente manifestos de clientes com base em parâmetros especificados em uma consulta associada à sua solicitação de reprodução. Isso permite que você execute ações como restringir o acesso do visualizador a conteúdo HEVC 4K premium ou direcionar tipos específicos de dispositivos e intervalos de taxa de amostragem de áudio, tudo diretamente de um único endpoint. Anteriormente, você precisaria configurar vários endpoints para realizar esse comportamento. MediaPackage agora fornece uma maneira econômica de produzir dinamicamente diferentes manifestos de clientes no mesmo endpoint.

Trabalhar com filtros de manifesto

Ao usar um filtro de manifesto, o manifesto resultante inclui apenas os fluxos de áudio e vídeo correspondentes às características especificadas na consulta. Se nenhum filtro de manifesto for usado, todos os fluxos ingeridos estarão presentes no fluxo de saída do endpoint. A exceção a isso é se você tiver definido filtros de fluxo para o endpoint, como taxa mínima de bits de vídeo. Nesse caso, o filtro de manifesto será aplicado após o filtro de fluxo, o que poderá distorcer a saída, portanto, não é recomendado.

A filtragem de manifestos pode ser usada em todos os tipos de endpoints compatíveis com: MediaPackage

• Apple HLS

• DASH-ISO

• Microsoft Smooth Streaming

• CMAF

Para usar a filtragem de manifesto, anexe parâmetros de aws.manifestfilter consulta à sua solicitação de reprodução para. MediaPackage MediaPackage avalia a consulta e exibe um manifesto do cliente com base nesses parâmetros de consulta. As consultas de manifesto não diferenciam maiúsculas de minúsculas e podem ter até 1024 caracteres. Se a consulta estiver malformada, ou se não houver fluxos que correspondam aos parâmetros de consulta, o MediaPackage retornará um manifesto incompleto ou vazio. Para sintaxe de consulta, consulte a seção a seguir.

nota

Se você estiver usando endpoints Apple HLS ou CMAF, haverá condições especiais aplicáveis. Para obter informações sobre essas condições, consulte Condições especiais para manifestos HLS e CMAF.

Sintaxe de consulta

O parâmetro de consulta base é aws.manifestfilter, que é seguido por pares de nome de parâmetro e valor opcionais. Para criar a consulta, anexe ?aws.manifestfilter= ao final do URL do MediaPackage endpoint, seguido pelos nomes e valores dos parâmetros. Para obter uma lista de todos os parâmetros disponíveis, consulte Parâmetros de consulta de filtro de manifesto.

Uma consulta de filtro Apple HLS pode ser semelhante a esta:

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

A sintaxe da consulta está listada na tabela a seguir.

Componente da string da consulta	Descrição
?	Um caractere restrito que marca o início de uma consulta.
aws.manifestfilter=	A consulta base, que é seguida por parâmetros criados de pares de nome e valor. Para obter uma lista de todos os parâmetros disponíveis, consulte Parâmetros de consulta de filtro de manifesto.
:	Usado para associar o nome do parâmetro a um valor. Por exemplo, parameter_name:value.
;	Separa parâmetros em uma consulta que contém vários parâmetros. Por exemplo, parameter1_name:value;parameter2_name:minValue-maxValue.
,	Separa uma lista de valores. Por exemplo, parameter_name:value1,value2,value3. Valores separados por vírgulas em uma lista implicam um relacionamento OR.
-	Usado para definir um intervalo de valor mínimo - máximo de um parâmetro. Por exemplo, audio_sample_rate:0-44100. Quando um valor numérico é usado em um intervalo, ele é incluído na definição do intervalo. Isso significa que os fluxos devem ser maiores ou iguais ao valor mínimo e menores ou iguais ao valor máximo. Com intervalos, os valores mínimo e máximo são obrigatórios. Os valores de intervalo compatíveis são 0 - 2147483647.

nota

Se você usa a Amazon CloudFront como sua CDN, talvez seja necessário definir configurações adicionais. Para obter mais informações, consulte Configurar o comportamento do cache para todos os endpoints.

Parâmetros de consulta de filtro de manifesto

MediaPackage suporta os seguintes parâmetros de consulta.

Categoria	Nome	Descrição	Exemplo
Áudio	audio_bitrate	A taxa de bits de áudio em bits por segundo. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 0 - 2147483647.	stream.mpd?aws.manifestfilter=audio_bitrate:0-2147483647
Áudio	audio_channels	O número de canais de áudio. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 1 - 32767.	stream.mpd?aws.manifestfilter=audio_channels:1-8
Áudio	audio_codec	O tipo de codec de áudio. Valores aceitos: AACL, AACH, AC-3 e EC-3. É necessário incluir o - para AC-3 e EC-3. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=audio_codec:AACL,AC-3
Áudio	audio_language	Linguagens de áudio ou códigos funcionais derivados da passagem do codificador. Valores aceitos: strings arbitrárias, como códigos de linguagem ISO-639-1 de dois ou quatro caracteres. É necessário usar as mesmas strings de linguagem definidas para o codificador. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=audio_language:fr,en-US,de
Áudio	audio_sample_rate	A taxa de amostragem de áudio em Hz. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 0 - 2147483647.	stream.mpd?aws.manifestfilter=audio_sample_rate:0-44100
Legenda	subtitle_language	A linguagem da legenda ou códigos funcionais derivados da passagem do codificador. Valores aceitos: strings arbitrárias, como códigos de linguagem ISO-639-1 de dois ou quatro caracteres. É necessário usar as mesmas strings de linguagem definidas para o codificador. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=subtitle_language:en-US, hi
Vídeo	trickplay_height	A altura da imagem do trick-play em pixels. Isso se aplica ao trick-play somente I-frame e baseado em imagem. nota Se você estiver usando esse parâmetro com trick-play somente I-frame, trickplay_height e video_height devem ter valores semelhantes. Se os valores não forem os mesmos, as faixas somente I-frame poderão ser removidas de um manifesto. O trickplay_height filtro é aplicado antes de colocar o DASH no VOD. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 1 - 2147483647.	stream.mpd?aws.manifestfilter=trickplay_height:200-1200
Vídeo	trickplay_type	O tipo de faixa de trickplay. Você pode filtrar por faixas de trickplay de iframe ou imagem, ou usar o valor none para filtrar todas as faixas de trickplay (tanto iframe quanto imagem). Valores aceitos: iframe, image e none. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=trickplay_type:iframe
Vídeo	video_bitrate	A taxa de bits de vídeo em bits por segundo. nota Se você estiver usando esse parâmetro, recomendamos usar apenas o parâmetro de filtro video_bitrate para definir a taxa de bits de vídeo. Também não defina a taxa de bits mínima e máxima de vídeo por meio do MediaPackage console ouAWS CLI. O filtro video_bitrate se aplica às configurações de taxa de bits de vídeo criadas no endpoint. Se você usar o parâmetro e definir a taxa de bits no console ou na AWS CLI, sua saída poderá ser distorcida. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 0 - 2147483647. nota Não é possível usar esse parâmetro com fluxos de trick-play.	stream.mpd?aws.manifestfilter=video_bitrate:0-2147483647
Vídeo	video_codec	O tipo de codec de vídeo. Valores aceitos: H264, H265. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=video_codec:h264
Vídeo	video_dynamic_range	O intervalo dinâmico de vídeo. Valores aceitos: hdr10, hlg e sdr. Os valores não diferenciam maiúsculas de minúsculas.	stream.mpd?aws.manifestfilter=video_dynamic_range:hdr10
Vídeo	video_framerate	O intervalo da taxa de quadros de vídeo no formato NTSC. Valores aceitos: dois números de ponto flutuante agregados com um traço que definem um intervalo inclusivo. Cada número pode ter até três valores fracionários opcionais. Por exemplo, o 29.97 ou o 29.764. Os valores de intervalo compatíveis são 1 - 999.999.	stream.mpd?aws.manifestfilter=video_framerate:23.976-30
Vídeo	video_height	A altura do vídeo em pixels. nota Se você estiver usando esse parâmetro com trick-play somente I-frame, trickplay_height e video_height devem ter valores semelhantes. Se os valores não forem os mesmos, as faixas somente I-frame poderão ser removidas de um manifesto. Valores aceitos: dois valores inteiros agregados com um traço que definem um intervalo inclusivo. Os valores de intervalo compatíveis são 1 - 32767.	stream.mpd?aws.manifestfilter=video_height:720-1080

Exemplos de filtragem de manifestos

Veja a seguir exemplos de filtragem de manifestos.

exemplo 1: Selecionar um player que ofereça suporte a AVC e uma taxa de amostragem de áudio de 44,1 k

O visualizador está reproduzindo conteúdo em um dispositivo que só oferece suporte a AVC e a uma taxa de amostragem de áudio de 44,1 k. Defina o video_codec e o audio_sample_rate para filtrar fluxos que não atendam a esses requisitos.

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

exemplo 2: Restringir o conteúdo HEVC 4K

Seu fluxo HEVC 4K é de 15 Mbps, e todos os seus outros fluxos têm menos de 9 Mbps. Para excluir o fluxo 4K do conjunto de fluxos, defina um limite de 9.000.000 bits por segundo para filtrar a taxa de bits mais alta.

?aws.manifestfilter=video_bitrate:0-9000000

exemplo 3: Incluir um vídeo entre 23.976 e 30 quadros por segundo

Para incluir somente um vídeo dentro de um determinado intervalo de taxa de quadros, use video_framerate. Este parâmetro aceita números de ponto flutuante com até três valores decimais opcionais.

?aws.manifestfilter=video_framerate:23.976-30

Condições especiais para manifestos HLS e CMAF

Se você estiver usando manifestos HLS ou CMAF, estas condições especiais serão aplicáveis.

• Para manifestos HLS, é altamente recomendável utilizar grupos de versões de áudio para evitar a remoção dos fluxos de vídeo que são multiplexados com os fluxos de áudio filtrados. Para obter mais informações sobre grupos de versões, consulte Referência de grupos de versões no AWS Elemental MediaPackage.

• Em manifestos HLS e CMAF, a taxa de amostragem de áudio não é sinalizada, portanto, não é fácil verificar visualmente os manifestos originais ou filtrados para essa configuração. Para verificar a taxa de amostragem de áudio, verifique a taxa de amostragem de áudio no nível do codificador e no nível de saída.

• Em manifestos HLS e CMAF, o atributo BANDWIDTH de uma variante associa a largura de banda da faixa de áudio à faixa de vídeo, seja ela multiplexada com a faixa de vídeo ou uma faixa de versões de áudio referenciada pela faixa de vídeo. Portanto, não é possível inspecionar visualmente os manifestos originais e filtrados para confirmar se o filtro video_bitrate funcionou. Para verificar o filtro, verifique a taxa de bits do vídeo nos níveis do codificador e da saída.

• Para manifestos HLS e CMAF, os parâmetros de solicitação acrescentados a listas de reprodução ou segmentos de taxa de bits resultam em um erro HTTP 400.

Condições de erro

As condições de erro comuns estão listadas na tabela a seguir.

Condição de erro	Exemplo	Código de status HTTP
Um parâmetro de lista não é encontrado e não faz parte de uma lista restrita	?aws.manifestfilter=audio_language:dahlia	200
Somente transmissões de legendas estão presentes no fluxo	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	200
Parâmetro de filtro duplicado	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=audio_sample_rate:0-48000	400
Parâmetro inválido	?aws.manifestfilter=donut_type:rhododendron	400
Parâmetro de intervalo inválido	?aws.manifestfilter=audio_sample_rate:300-0	400
Valor de intervalo inválido (mais de INT_MAX)	?aws.manifestfilter=audio_sample_rate:0-2147483648	400
String de consulta malformada	?aws.manifestfilter=audio_sample_rate:is:0-44100	400
A string de parâmetro tem mais de 1024 caracteres	?aws.manifestfilter=audio_language:abcdef....	400
Parâmetros de consulta em um manifesto de taxa de bits HLS ou CMAF	index_1.m3u8?aws.manifestfilter=video_codec:h264	400
Parâmetros de consulta em uma solicitação de segmento	..._1.[ts|mp4|vtt..]?aws.manifestfilter=video_codec:h264	400
Parâmetro de consulta repetida	?aws.manifestfilter=audio_sample_rate:0-48000;aws.manifestfilter=video_bitrate:0-1	400
A aplicação do filtro resulta em um manifesto vazio (o conteúdo não tem fluxos que atendam às condições definidas na string de consulta)	?aws.manifestfilter=audio_sample_rate:0-1;video_bitrate=0-1	400