HLS¶

media.ingest.hls

Descrição¶

O Sapsan segue uma playlist HLS de terceiros em modo cliente (pull): sonda a playlist, baixa os segmentos e entrega quadros ao pipeline tal como RTSP, SRT ou MPEG-TS. É assim que entrega o stream quase todo agregador, toda CDN de terceiros e todo parceiro a quem não foi permitido abrir UDP ou SRT.

Configuração¶

Configure o stream pela API do central. Trecho de configuração:

streams:
  - name: chan1
    inputs:
    - hls:
        url: https://cdn.example.com/live/index.m3u8

Parâmetros¶

Autenticação¶

Duas formas, e elas se combinam:

• cabeçalhos — headers, por exemplo Authorization: Bearer <token>; vão com a playlist, as variantes, os segmentos init, os segmentos e as chaves do mesmo origin, e nunca seguem um redirecionamento para um origin de terceiros;
• credenciais na própria URL — autenticação Basic comum feita pelo cliente HTTP.

Os valores dos cabeçalhos nunca chegam ao log: só os nomes são impressos. O endereço da entrada é escrito inteiro nos logs e devolvido como está pela API de gerenciamento — qual parte desse endereço é o segredo, só o operador sabe, e uma máscara às cegas ou deixaria o token na query, ou cortaria justamente aquilo pelo que a entrada é reconhecida no log.

Opções de transporte¶

HTTP ou HTTPS; listas/manifestos e segmentos usam requisições independentes.

Codecs compatíveis¶

Os codecs aceitos dependem do contêiner dos segmentos. MPEG-TS e fMP4 são contêineres; HLS obtém playlists e segmentos.

Segmentos MPEG-TS:

• H.264
• HEVC / H.265
• AV1
• JPEG 2000
• MPEG-2 Video
• AAC (ADTS)
• AC-3
• E-AC-3
• MPEG Audio (Layer II / III)
• SMPTE ST 302M

MPEG-TS é o contêiner; SRT, RIST, UDP e HTTP são transportes de entrega. A lista descreve a extração de frames de MPEG-TS, não sua decodificação nem a compatibilidade do reprodutor.

AV1 requer stream_type 0x06 e o descritor de registro AV01 na PMT; cada PES deve conter um temporal unit completo. AV1 em MPEG-TS sem essa sinalização não é aceito. AAC é analisado como ADTS; reconhecer stream_type 0x11 não implica suporte a LATM. Opus pode ser identificado na PMT, mas o analisador PES atual não emite seus frames.

Segmentos fMP4:

• H.264
• HEVC / H.265
• AV1
• MPEG-2 Video
• JPEG
• AAC
• AC-3
• E-AC-3
• MPEG Audio (Layer II / III)
• Opus
• G.711 A-law / μ-law

São os codecs que a entrada extrai de fMP4, não uma lista de capacidades de decodificação. H.264 usa avc1/avc3, HEVC usa hvc1/hev1 e AV1 usa av01 com av1C. MPEG-2 Video requer mp4v com configuração MPEG-2; isso não implica suporte a MPEG-4 Visual. JPEG é uma faixa de imagens. MPEG Audio é identificado por esds ou uma sample entry MP3; mp4a por si só não significa AAC. Opus usa Opus/dOps e G.711 usa alaw/ulaw. As declarações do contêiner devem corresponder aos dados; declarar um codec no MPD não substitui um segmento de inicialização válido.

Esta entrada não aceita packed audio (ADTS independente ou ID3+AAC sem MPEG-TS/fMP4).

Comportamento em caso de erro¶

O estado da entrada e a causa da falha estão nas estatísticas do stream. Desconexão ou ausência de quadros usa os mecanismos de repetição e comutação para reserva.

Aplicação de alterações¶

Só uma mudança de url, headers ou dos ajustes HTTP (connect_timeout_ms, read_timeout_ms, max_body_bytes) reinicia a entrada: uma fonte nova tem sua própria numeração de faixas, seu próprio init e sua própria posição na playlist. Todo o resto — modo de variante, limite e política de desvio, peer_timeout_ms — é aplicado em tempo real, sem interromper a transmissão.

Contadores¶

As tabelas mostram os nomes exatos dos campos de estatísticas do protocolo, incluindo contadores de eventos e indicadores do valor atual. Campos zerados podem ser omitidos. API e Prometheus expõem projeções diferentes; uma única resposta da Admin API não contém necessariamente toda a lista. O detalhe depende da licença de contadores.

Totais comuns da entrada: bytes, frames, errors, warnings. Eles agregam dados do protocolo; não devem ser somados novamente aos contadores do protocolo.

Hls¶

Outros detalhes¶

Regra de início¶

Tudo o que já estava na playlist no momento da conexão é história. A captura começa pelo primeiro segmento que aparece depois da conexão, e numa reconexão ela se comporta igual.

Não existe de propósito ajuste de profundidade de início: caso contrário, a cada queda de conexão o stream despejaria no pipeline, em segundos, a janela acumulada, em vez de transmitir.

Escada de qualidades e desvio das renditions¶

Com variant_mode: ladder captura-se toda variante do master. A de maior BANDWIDTH passa a ser a referência, e as demais são comparadas com ela segmento a segmento, pelo número de sequência de mídia. O veredito fica exposto na estatística da entrada, campo hls_ladder:

• synced — as renditions andam juntas, comutar entre elas é seguro;
• skewed — o desvio passou do limite ou a estrutura está quebrada: a comutação dará trancos ou dessincronizará;
• unmeasurable — não há com o que comparar, nenhum par de segmentos compartilha número.

O desvio é medido de duas maneiras ao mesmo tempo. O declarado é a diferença de EXT-X-PROGRAM-DATE-TIME na marcação; o real é a diferença do tempo de mídia dos primeiros quadros. Quando os dois discordam, o doente é a marcação, não o stream, e quem conserta é o dono da fonte.

A política fallback_to_single derruba a captura para uma variante só diante de um veredito skewed — para algumas fontes é o único modo viável. O recuo dura até a entrada ser reiniciada.

Criptografia¶

São suportados AES-128 (o segmento inteiro) e SAMPLE-AES (por quadro, para H.264 e AAC). A chave é buscada pelo mesmo cliente e com os mesmos cabeçalhos que todo o resto, e fica em cache por endereço, de modo que a rotação de chaves no meio de uma playlist funciona sozinha — uma chave nova tem outro endereço.

Um servidor de chaves calado é um erro de entrada com o endereço da chave e o código de resposta; o corpo do segmento não é baixado de forma alguma, já que não haveria com o que descriptografá-lo.

CENC/DRM (Widevine, PlayReady, FairPlay) não é suportado e é rejeitado pelo nome do KEYFORMAT.

O que é suportado¶

Verificação¶

Abra http://server/streaming/v/chan1/index.m3u8 num reprodutor ou peça uma captura de tela em http://server/streaming/live-preview-jpeg/chan1.

Vá além de «os quadros estão fluindo» e olhe três coisas:

• o quanto a saída atrasa em relação à borda da playlist — sem isso, a reclamação «o stream está atrasado» é indistinguível de «a fonte está atrasada», e as duas se consertam em lugares diferentes;
• os segmentos pulados e seu detalhamento: lavados para fora da janela, cancelados em voo, declarados com EXT-X-GAP. O último não é um erro da fonte, e sim a sua declaração honesta;
• a emenda entre fragmentos vizinhos — um defeito silencioso: todos os segmentos foram baixados, sem erros de análise, mas a mídia dentro deles não se encaixa, e o arquivo guarda o buraco.

Próximos passos¶

• Reserva de fontes

• Transcodificação

• Gravação em arquivo