Skip to content

Скрытые субтитры (closed captions)

Закрытые субтитры (closed captions, CC) едут не отдельной дорожкой, а внутри самого видео — в служебных данных кадров (SEI для H.264 и HEVC, user data для MPEG-2, метаданные OBU для AV1). Их понимают телевизоры и приставки, но браузерный плеер такой текст показать не может: HLS и DASH ждут субтитры отдельной дорожкой.

Sapsan умеет и то, и другое: пропускать кэпшны внутри видео как есть и декодировать их в субтитровую дорожку WebVTT.

Режимы обработки

Режим задаётся полем mode в секции closed_captions стрима и управляет только выдачей — декодирование и запись в архив идут всегда:

  • passthrough (по умолчанию) — кэпшны остаются внутри видео и объявляются в манифестах как closed captions. Субтитровой дорожки в манифестах нет.
  • extract — субтитровая дорожка вместо встроенных кэпшнов: текст декодируется в WebVTT-дорожку, а из выходного видео кэпшны вырезаются и как closed captions не объявляются.
  • both — и то, и другое: кэпшны едут внутри видео и объявляются, и рядом идёт субтитровая дорожка.

Конфигурация

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

Секция services необязательна и решает две задачи:

  • имя и язык пункта меню в плеере. Без неё имя выводится из потока: язык, объявленный сервисом, иначе — адрес сервиса (CC1, SERVICE3);
  • предобъявление в режимах extract и both: перечисленный сервис получает дорожку с первого сегмента, не дожидаясь первой реплики. Это важно для плееров, которые читают список дорожек один раз при старте: сервис, заговоривший на десятой минуте, иначе появится в меню только после переоткрытия потока.

Ключ сервиса — CC1…CC4 для CEA-608 и SERVICE1…SERVICE63 для CEA-708.

Кэпшны из SDI

SDI передаёт CEA-608/708 в пакетах CDP внутри ANC. При кодировании SDI-видео в H.264 или HEVC Sapsan помещает эти кэпшны в SEI соответствующего видеокадра. Тот же сигнал может содержать телетекст.

Настройте вход SDI и кодирование видео. Режим both сохраняет встроенные кэпшны для приёмников MPEG-TS и добавляет WebVTT для браузерных плееров:

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

Поддерживаемый носитель кэпшнов SDI — CDP; CEA-608 из строки 21 без CDP не принимается. Повреждённый CDP отбрасывается целиком. DVR сохраняет SEI кэпшнов вместе с кодированными сэмплами H.264/HEVC. Дорожка носителя SDI-телетекста имеет номер t68, CC1 — t1, SERVICE1 — t5.

Что получает плеер

Каждый говорящий сервис становится отдельной текстовой дорожкой с постоянным номером: CC1…CC4 → t1…t4, SERVICE1…SERVICE63 → t5…t67. Номер закреплён за сервисом и не меняется при перезапуске стрима, поэтому ссылки на дорожку остаются рабочими.

В HLS дорожка приезжает рендишеном EXT-X-MEDIA с TYPE=SUBTITLES, в DASH — адаптационным набором contentType="text" c mimeType="text/vtt". Сегменты дорожки лежат по адресу вида:

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

Последний сегмент пути — начало окна в миллисекундах; конец окна определяет сервер по той же сетке сегментов, что и у видео. Пустое окно — это корректный пустой WebVTT-сегмент, а не ошибка: в паузе между репликами дорожка не должна рваться.

Субтитры отдаются в живом эфире, в отложенном просмотре (rewind) и в архиве. Декодированные реплики пишутся в архив всегда, независимо от режима, — поэтому включение extract действует и задним числом: субтитры появятся и на уже записанном архиве.

Ограничение режима extract на TS-выдачах

В режиме extract кэпшны вырезаются из выходного видео целиком — на всех выдачах сразу, включая MPEG-TS: push по udp/rtp/srt, .ts-сегменты HLS и tshttp. Текстовой дорожке в MPEG-TS ехать не в чем, поэтому потребитель TS-выдачи в этом режиме останется без субтитров вообще.

Если поток одновременно смотрят браузером и забирают по MPEG-TS, нужен режим both: он оставляет кэпшны внутри видео для TS-потребителя и добавляет дорожку для браузера.

Переход с Flussonic Media Server

В legacy Flussonic опция cc.extract не убирала кэпшны из видео — она включала их извлечение дополнительно к встроенным. Поэтому её прямое соответствие в Sapsan — это mode: both, а не mode: extract.

Flussonic Sapsan Поведение
опция не задана mode: passthrough кэпшны внутри видео, дорожки нет
cc.extract mode: both кэпшны внутри видео и субтитровая дорожка
— mode: extract новое строгое поведение: дорожка вместо встроенных кэпшнов

mode: extract — новое поведение, аналога в legacy Flussonic у него нет. Выбирайте его, когда встроенные кэпшны не нужны никому из потребителей: он снимает двойной пункт меню в плеере (одни и те же субтитры и как closed captions, и как дорожка) и экономит место в видеокадрах.

Проверка

Убедиться, что дорожка появилась, можно по мастер-плейлисту:

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

и по содержимому сегмента:

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

Состав обнаруженных сервисов и номер дорожки каждого видны в статистике стрима (GET /streamer/api-v4/streams/stats, секция captions).

Работу тракта показывают метрики Prometheus с префиксом stream_captions_: stream_captions_cc_pairs_total — доходят ли кэпшны до сервера вообще, stream_captions_cues_decoded_total — сколько реплик распознано, stream_captions_cues_delivered_total — сколько уложено в дорожку. Растущий stream_captions_unrecognized_payloads_total означает, что в потоке едет неизвестная нам обёртка кэпшнов; сообщите об этом в поддержку.

Для SDI различайте приём CDP и декодирование текста. Вход предоставляет следующие счётчики Prometheus:

  • stream_input_sdi_vanc_cdp_bad_identifier_total — неверный идентификатор CDP.
  • stream_input_sdi_vanc_cdp_bad_checksum_total — неверная контрольная сумма CDP.
  • stream_input_sdi_vanc_cdp_malformed_total — неверная структура, маркеры или footer.
  • stream_input_sdi_vanc_cdp_without_data_total — корректный CDP без cc_data.

stream_input_transcoder_caption_unsupported_total считает выходные качества без поддерживаемого носителя кэпшнов SDI. Для переноса кэпшнов SDI в кодированное видео выберите H.264 или HEVC.