Media over QUIC¶

media.play.moq

Sapsan отдаёт live-медиа по Media over QUIC: клиент подключается к серверу, выбирает стрим и подписывается на его дорожки. Sapsan выступает издателем медиа. Входящий источник может при этом использовать другой протокол, например RTSP.

Текущая реализация использует MoQT transport draft-19. Это конкретная версия Internet-Draft; совместимость клиента нужно проверять именно с ней. Формат каталога соответствует MSF draft-01, медиа передаётся в CMAF.

Как устроена доставка¶

Для каждого активного стрима Sapsan публикует broadcast с пространством имён, равным имени стрима. Например, cam становится именем, которое клиент выбирает при подписке.

Обнаружение — подписка на пустой префикс пространства имён позволяет получить список опубликованных стримов.
Каталог — дорожка catalog содержит JSON с описанием медиа и данными инициализации.
Дорожки — видео и звук публикуются под именами вроде v1 и a1.
Объекты — части CMAF передаются по мере их появления. Граница сегмента начинает новую группу, части внутри неё становятся последовательными объектами.

Клиент, подключившийся посреди сегмента, ожидает подходящее начало группы. Установившаяся подписка получает последующие объекты по мере производства. Итоговая задержка зависит от источника, кодирования, структуры сегментов и частей, сети и буфера плеера.

Поддержаны два варианта подключения к одному UDP-слушателю:

Клиент	Транспорт
Нативный MoQT-клиент	QUIC с ALPN `moqt-19`.
Браузер	WebTransport поверх HTTP/3, ALPN `h3`; клиент использует согласованный вариант MoQT draft-19.

Этот тракт предназначен для live-выдачи видео и звука. Проигрывание DVR/VOD, приём камер по MoQ и передача субтитров им не предоставляются. Подписка MoQ не заменяет настройку источника или транскодера.

Настройка слушателя¶

В настройках стримера задайте listeners.moq. В рабочем решении конфигурация управляется через central. Для локальной проверки можно использовать следующий фрагмент серверного конфига:

listeners:
  http:
    - port: 8080
  moq:
    - bind: "127.0.0.1:4443"
      certificate: /etc/sapsan/tls/moq-cert.pem
      private_key: /etc/sapsan/tls/moq-key.pem

streams:
  - name: cam
    inputs:
      - rtsp:
          url: rtsp://camera.example/live

Замените источник и пути сертификата и ключа. bind — числовой IP-адрес и UDP-порт; порт 4443 здесь выбран для примера. Разрешение только TCP на этом порту не обеспечивает подключение QUIC.

Для первой браузерной проверки используйте источник с H.264 и AAC, поддерживаемыми выбранным браузером. Каталог описывает существующие дорожки: сам по себе MoQ не превращает неподдерживаемый браузером кодек в совместимый. При необходимости заранее настройте транскодирование.

Доступ к слушателю¶

Текущий MoQ-слушатель предоставляет доступ к опубликованным live-стримам сервера без интеграции с HTTP-авторизацией и сессиями просмотра. Проверка JWT-билета или ?token= для HLS не переносится на MoQ. TLS шифрует транспорт, но не определяет, кому разрешена подписка на конкретный стрим.

При выборе адреса слушателя учитывайте, какие клиенты могут его достичь. В приведённом примере он доступен только на локальной машине. Для удалённого стенда ограничьте сетевой доступ к UDP-порту участниками проверки.

Проверка получения медиа¶

В исходном дереве Sapsan есть утилита moq-probe. Она устанавливает MoQT-соединение, обнаруживает стрим и читает каталог. С параметром дорожки она также проверяет получение медиаобъекта.

После запуска Sapsan с активным стримом cam и видеодорожкой v1 выполните из корня исходного дерева:

MOQ_PROBE_SERVER=127.0.0.1:4443 \
MOQ_PROBE_BROADCAST=cam \
MOQ_PROBE_TRACK=v1 \
cargo run -p moq --bin moq-probe

Для сборки утилиты требуется Rust-окружение проекта. MOQ_PROBE_SERVER принимает IP и порт, без префикса https://; имя broadcast и дорожки должны соответствовать запущенному стриму.

Ожидаемый результат:

MOQT probe OK: SETUP + SUBSCRIBE_NAMESPACE + catalog + media object

Параметр MOQ_PROBE_TRACK существенен: без него успех означает проверку каталога, но не получение видеообъекта. Утилита проверяет структуру CMAF-объекта, а не декодирует изображение и звук. Эта диагностическая утилита также пропускает проверку сертификата сервера, поэтому её успех не подтверждает доверие TLS со стороны обычного клиента.

Обычный HTTPS GET или открытие адреса MoQ-слушателя как веб-страницы не выполняют подписку на медиа и не заменяют эту проверку.

Проверка воспроизведения в браузере¶

В исходном дереве есть стенд на стандартном плеере @moq/watch с зафиксированной совместимой версией клиентской библиотеки. Команды ниже выполняются из корня репозитория Sapsan.

Создайте тестовый сертификат:

bash crates/moq/tests/gen-browser-cert.sh

Скрипт создаёт crates/moq/tests/wt-cert.pem и wt-key.pem. Укажите их абсолютные пути в certificate и private_key своего слушателя. Это ECDSA-сертификат на 14 дней, подходящий для проверки через закреплённый хэш сертификата в браузерном стенде.

Запустите Sapsan с этим конфигом и совместимым источником. Например, для локального запуска из исходников:

bash CONFIG_PATH=/absolute/path/to/moq.yaml \ cargo run --no-default-features --bin sapsan

Эта команда предназначена для локального стенда. Набор дополнительных возможностей такого запуска зависит от сборки; для проверки выберите уже работающий совместимый источник.

Запустите браузерную часть:

bash crates/moq/tests/watch-sapsan/serve.sh

Нужны bun, git и openssl; при первом запуске скрипт получает зависимости. Он запускает клиентский стенд и не запускает сам Sapsan.

Откройте http://localhost:5173/sapsan.html?name=cam в браузере с поддержкой WebTransport. По умолчанию стенд подключается к https://127.0.0.1:4443. Запустите воспроизведение и включите звук нажатием, если этого требует браузер.

Критерий успешной браузерной проверки — воспроизводимые изображение и звук, а не только появление имени стрима в списке. localhost используется намеренно: WebTransport требует безопасного контекста, и обычная HTTP-страница по LAN-IP не эквивалентна такому запуску. Показатель буфера плеера также не является измерением полной задержки от камеры до экрана.