HLS¶

media.ingest.hls

Descripción¶

Sapsan sigue una playlist HLS ajena en modo cliente (pull): sondea la playlist, descarga los segmentos y entrega fotogramas al pipeline igual que RTSP, SRT o MPEG-TS. Así entrega el stream casi todo agregador, toda CDN ajena y todo socio al que no le han permitido abrir UDP o SRT.

Configuración¶

Configure el stream mediante la API de central. Fragmento de configuración:

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

Parámetros¶

Autenticación¶

Dos formas, y se pueden combinar:

• cabeceras — headers, por ejemplo Authorization: Bearer <token>; van con la playlist, las variantes, los segmentos init, los segmentos y las claves del mismo origin, y nunca siguen una redirección a un origin ajeno;
• credenciales en la propia URL — autenticación Basic corriente hecha por el cliente HTTP.

Los valores de las cabeceras jamás llegan al log: solo se imprimen sus nombres. La dirección de la entrada se escribe entera en los logs y la API de gestión la devuelve tal cual: qué parte de esa dirección es el secreto lo sabe solo el operador, y enmascarar a ciegas o dejaría el token en la query o recortaría justo aquello por lo que la entrada se reconoce en el log.

Opciones de transporte¶

HTTP o HTTPS; listas/manifiestos y segmentos usan solicitudes independientes.

Códecs admitidos¶

Los códecs admitidos dependen del contenedor de los segmentos. MPEG-TS y fMP4 son contenedores; HLS obtiene playlists y 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 es el contenedor; SRT, RIST, UDP y HTTP son transportes de entrega. La lista describe la extracción de frames de MPEG-TS, no su decodificación ni la compatibilidad del reproductor.

AV1 requiere stream_type 0x06 y el descriptor de registro AV01 en la PMT; cada PES debe contener un temporal unit completo. No se admite AV1 en MPEG-TS sin esta señalización. AAC se analiza como ADTS; reconocer stream_type 0x11 no implica compatibilidad con LATM. Opus se puede identificar en la PMT, pero el analizador PES actual no emite sus 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

Son los códecs que la entrada extrae de fMP4, no una lista de capacidades de decodificación. H.264 usa avc1/avc3, HEVC usa hvc1/hev1 y AV1 usa av01 con av1C. MPEG-2 Video requiere mp4v con configuración MPEG-2; esto no implica compatibilidad con MPEG-4 Visual. JPEG es una pista de imágenes. MPEG Audio se identifica mediante esds o una sample entry MP3; mp4a por sí sola no significa AAC. Opus usa Opus/dOps y G.711 usa alaw/ulaw. Las declaraciones del contenedor deben coincidir con los datos; declarar un códec en el MPD no sustituye un segmento de inicialización válido.

Esta entrada no acepta packed audio (ADTS independiente o ID3+AAC sin MPEG-TS/fMP4).

Comportamiento ante errores¶

El estado de la entrada y la causa del fallo están en las estadísticas del stream. Ante desconexión o ausencia de fotogramas se aplican los mecanismos de reintento y conmutación a reserva.

Aplicación de cambios¶

Solo un cambio de url, headers o de los ajustes HTTP (connect_timeout_ms, read_timeout_ms, max_body_bytes) reinicia la entrada: una fuente nueva tiene su propia numeración de pistas, su propio init y su propia posición en la playlist. Todo lo demás — modo de variante, umbral y política de desfase, peer_timeout_ms — se aplica en caliente, sin interrumpir la emisión.

Contadores¶

Las tablas indican los nombres exactos de los campos de estadísticas del protocolo, incluidos contadores de eventos e indicadores del valor actual. Los campos nulos pueden omitirse. API y Prometheus exponen proyecciones distintas; un único resultado de Admin API no incluye necesariamente toda la lista. El detalle depende de la licencia de contadores.

Totales comunes de entrada: bytes, frames, errors, warnings. Agregan datos del protocolo; no deben sumarse otra vez a los contadores del protocolo.

Hls¶

Otros detalles¶

Regla de inicio¶

Todo lo que ya había en la playlist en el momento de conectar es historia. La captura empieza con el primer segmento que aparece después de la conexión, y en una reconexión se comporta igual.

No existe a propósito un ajuste de profundidad de inicio: de lo contrario, cada caída de conexión haría que el stream vaciase por el pipeline, en segundos, la ventana acumulada, en lugar de emitir.

Escalera de calidades y desfase de representaciones¶

Con variant_mode: ladder se capturan todas las variantes del master. La de mayor BANDWIDTH pasa a ser la referencia, y las demás se comparan con ella segmento a segmento, por número de secuencia de media. El veredicto queda expuesto en la estadística de la entrada, campo hls_ladder:

• synced — las representaciones van juntas, conmutar entre ellas es seguro;
• skewed — el desfase superó el umbral o la estructura está rota: la conmutación dará tirones o desincronizará;
• unmeasurable — no hay con qué comparar, ningún par de segmentos comparte número.

El desfase se mide de dos maneras a la vez. El declarado es la diferencia de EXT-X-PROGRAM-DATE-TIME en el marcado; el real es la diferencia del tiempo de media de los primeros fotogramas. Si los dos no coinciden, lo enfermo es el marcado y no el stream, y quien lo arregla es el dueño de la fuente.

La política fallback_to_single baja la captura a una sola variante ante un veredicto skewed — para algunas fuentes es el único modo viable. El retroceso dura hasta que la entrada se reinicia.

Cifrado¶

Se admiten AES-128 (el segmento entero) y SAMPLE-AES (por fotograma, para H.264 y AAC). La clave la recoge el mismo cliente y con las mismas cabeceras que todo lo demás, y se guarda en caché por dirección, de modo que la rotación de claves en medio de una playlist funciona sola: una clave nueva tiene otra dirección.

Un servidor de claves que calla es un error de entrada con la dirección de la clave y el código de respuesta; el cuerpo del segmento no se descarga en absoluto, pues no habría con qué descifrarlo.

CENC/DRM (Widevine, PlayReady, FairPlay) no está admitido y se rechaza por el nombre de KEYFORMAT.

Qué se admite¶

Comprobación¶

Abra http://server/streaming/v/chan1/index.m3u8 en un reproductor o pida una captura en http://server/streaming/live-preview-jpeg/chan1.

Más allá de «ya fluyen fotogramas», mire tres cosas:

• cuánto se retrasa la salida respecto al borde de la playlist — sin eso, la queja «el stream va con retraso» es indistinguible de «la fuente va con retraso», y las dos se arreglan en sitios distintos;
• los segmentos saltados y su desglose: lavados fuera de la ventana, cancelados en vuelo, declarados con EXT-X-GAP. Lo último no es un error de la fuente, sino su declaración honesta;
• la costura entre fragmentos vecinos — un defecto silencioso: todos los segmentos se descargaron, sin errores de análisis, y sin embargo el medio de dentro no se une, y el archivo conserva el agujero.

Qué sigue¶

• Reserva de fuentes

• Transcodificación

• Grabación en archivo