Subtítulos ocultos¶

Los subtítulos ocultos (closed captions, CC) viajan dentro del propio vídeo y no como una pista aparte: en los datos auxiliares de cada fotograma (SEI para H.264 y HEVC, user data para MPEG-2, metadatos OBU para AV1). Los entienden los televisores y los decodificadores, pero un reproductor de navegador no puede mostrar ese texto: HLS y DASH esperan los subtítulos como una pista aparte.

Sapsan hace las dos cosas: pasa los subtítulos ocultos dentro del vídeo tal como son y los decodifica en una pista de subtítulos WebVTT.

Modos de procesamiento¶

El modo se fija con el campo mode de la sección closed_captions del stream. Controla solo la entrega — la decodificación y la grabación en el archivo ocurren siempre:

• passthrough (por defecto) — los subtítulos ocultos se quedan dentro del vídeo y se anuncian en los manifiestos como closed captions. No hay pista de subtítulos en los manifiestos.
• extract — una pista de subtítulos en lugar de los subtítulos ocultos incrustados: el texto se decodifica en una pista WebVTT, mientras que los subtítulos ocultos se recortan del vídeo de salida y no se anuncian como closed captions.
• both — ambas cosas a la vez: los subtítulos ocultos viajan dentro del vídeo y se anuncian, y junto a ellos va una pista de subtítulos.

Configuración¶

streams:
  - name: news
    inputs:
      - url: udp://239.0.0.1:1234
    closed_captions:
      mode: extract
      services:
        CC1:
          language: eng
          name: English
        SERVICE3:
          language: spa
          name: Espanol

La sección services es opcional y hace dos cosas:

• fija el nombre y el idioma de la entrada del menú del reproductor. Sin ella, el nombre se deduce del stream: el idioma anunciado por el servicio y, en su defecto, la dirección del servicio (CC1, SERVICE3);
• preanuncia el servicio en los modos extract y both: un servicio listado obtiene su pista desde el primer segmento, sin esperar al primer cue. Esto importa para los reproductores que leen la lista de pistas una sola vez al arrancar: un servicio que empieza a hablar en el minuto diez aparecería en el menú solo después de reabrir el stream.

La clave del servicio es CC1…CC4 para CEA-608 y SERVICE1…SERVICE63 para CEA-708.

Qué recibe el reproductor¶

Cada servicio que habla se convierte en su propia pista de texto con un número fijo: CC1…CC4 → t1…t4, SERVICE1…SERVICE63 → t5…t67. El número pertenece al servicio y no cambia cuando el stream se reinicia, de modo que los enlaces a una pista siguen funcionando.

En HLS la pista llega como un rendition EXT-X-MEDIA con TYPE=SUBTITLES; en DASH, como un AdaptationSet con contentType="text" y mimeType="text/vtt". Los segmentos de la pista viven en direcciones como:

/streaming/v/news/subtitles/t1/1738245600000.vtt

El último segmento de la ruta es el inicio de la ventana en milisegundos; el final de la ventana lo decide el servidor según la misma rejilla de segmentos que usa el vídeo. Una ventana vacía es un segmento WebVTT vacío válido, no un error: la pista no debe romperse durante una pausa entre cues.

Los subtítulos se sirven en vivo, en rewind y desde el archivo. Los cues decodificados se escriben siempre en el archivo independientemente del modo, así que activar extract funciona con efecto retroactivo: los subtítulos aparecen también en el archivo ya grabado.

La limitación del modo extract en las salidas TS¶

En el modo extract los subtítulos ocultos se recortan del vídeo de salida por completo — en todas las salidas a la vez, MPEG-TS incluido: push por udp/rtp/srt, segmentos .ts de HLS y tshttp. A una pista de texto no le queda dónde viajar dentro del MPEG-TS, así que en este modo un consumidor de una salida TS se queda sin subtítulos en absoluto.

Si el mismo stream se ve en un navegador y se recoge por MPEG-TS al mismo tiempo, use both: mantiene los subtítulos ocultos dentro del vídeo para el consumidor del TS y añade la pista para el navegador.

Migración desde Flussonic Media Server¶

En el Flussonic legacy la opción cc.extract no quitaba los subtítulos ocultos del vídeo — activaba la extracción además de los incrustados. Su equivalente directo en Sapsan es, por tanto, mode: both, no mode: extract.

mode: extract es un comportamiento nuevo sin equivalente en el Flussonic legacy. Elíjalo cuando ninguno de sus consumidores necesite los subtítulos ocultos incrustados: elimina la entrada duplicada del menú del reproductor (los mismos subtítulos como closed captions y como pista) y ahorra espacio en los fotogramas de vídeo.

Comprobación¶

Para confirmar que la pista ha aparecido, revise el playlist maestro:

curl -s http://localhost:8080/streaming/v/news/index.m3u8 | grep SUBTITLES

y el contenido del segmento:

curl -s http://localhost:8080/streaming/v/news/subtitles/t1/1738245600000.vtt

Los servicios detectados y el número de pista de cada uno se ven en las estadísticas del stream (GET /streaming/api/v4/streams/stats/news, la sección captions).

El trabajo del pipeline lo muestran las métricas de Prometheus con el prefijo stream_captions_: stream_captions_cc_pairs_total dice si los subtítulos ocultos llegan al servidor siquiera; stream_captions_cues_decoded_total, cuántos cues se decodificaron; stream_captions_cues_delivered_total, cuántos llegaron a la pista. Un stream_captions_unrecognized_payloads_total creciente significa que el stream lleva un wrapper de subtítulos ocultos que no conocemos; comuníquelo al soporte.