Skip to content

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.

Subtítulos desde SDI

SDI transporta CEA-608/708 en paquetes CDP dentro de ANC. Al codificar vídeo SDI en H.264 o HEVC, Sapsan inserta los subtítulos en el SEI del fotograma correspondiente. La misma señal también puede transportar teletexto.

Configure la entrada SDI y la codificación de vídeo. El modo both conserva los subtítulos integrados para receptores MPEG-TS y añade WebVTT para reproductores de navegador:

streams:
  - name: studio
    inputs:
      - sdi:
          device: /dev/v4l/by-path/pci-0000:5e:00.0-video-index0
    transcoder:
      output:
        - source: {best_quality: video}
          codec: {set: h264}
          bitrate: 2800000
        - source: {best_quality: audio}
          codec: {set: aac}
          bitrate: 128000
    closed_captions:
      mode: both

CDP es el portador de subtítulos SDI admitido; no se admite CEA-608 de la línea 21 sin CDP. Los paquetes CDP dañados se descartan por completo. DVR conserva el SEI de subtítulos junto con las muestras H.264/HEVC codificadas. El portador de teletexto SDI usa la pista t68, junto con CC1 en t1 y SERVICE1 en t5.

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.

Flussonic Sapsan Comportamiento
opción no definida mode: passthrough subtítulos ocultos dentro del vídeo, sin pista
cc.extract mode: both subtítulos ocultos dentro del vídeo y una pista de subtítulos
— mode: extract comportamiento estricto nuevo: una pista en lugar de los subtítulos ocultos incrustados

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 /streamer/api-v4/streams/stats, 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.

En SDI, distinga la recepción de CDP de la decodificación del texto. La entrada proporciona estos contadores Prometheus:

  • stream_input_sdi_vanc_cdp_bad_identifier_total — identificador CDP no válido.
  • stream_input_sdi_vanc_cdp_bad_checksum_total — suma de comprobación CDP no válida.
  • stream_input_sdi_vanc_cdp_malformed_total — estructura, marcadores o footer no válidos.
  • stream_input_sdi_vanc_cdp_without_data_total — CDP válido sin cc_data.

stream_input_transcoder_caption_unsupported_total cuenta las calidades de salida sin un portador de subtítulos SDI compatible. Seleccione H.264 o HEVC para transportar los subtítulos SDI en el vídeo codificado.