Проигрывание WebRTC (WHEP)¶

media.play.webrtc

Настройка¶

Настройки задаются через central. Пример конфигурации стримера:

listeners.webrtc задаёт общие UDP-порты для WHIP и WHEP. Если секция отсутствует или список пустой, ОС выбирает один свободный порт. port: 0 также включает автовыбор. Порт объявляется в ICE-кандидатах SDP; отдельный порт на сессию не выделяется. Повторное применение неизменного списка сохраняет выбранный порт. После перезапуска порт может измениться.

Параметр	Значение	Поведение
`listeners.webrtc`	Отсутствует или `[]`	Один автоматический UDP-порт
`listeners.webrtc[].port`	Обязателен в каждой записи, `0`–`65535`	`0` — автовыбор; ненулевое значение — фиксированный порт

listeners:
  webrtc:
  - port: 5005
  - port: 5006

Для фиксированных правил firewall или проброса за NAT задайте порты явно и обеспечьте доступ клиентов к ним. HTTP-прокси обслуживает согласование SDP; UDP-медиа должно доходить до самого стримера. Адрес для ICE определяется по локальной IPv4-маршрутизации; настройки публичного ICE-адреса и TURN в listeners.webrtc нет. Автовыбор порта не настраивает NAT.

URL проигрывания¶

Прямой адрес стримера:

https://streamer.example.com/streaming/whep/studio

Это адрес для WHEP-клиента, который отправляет SDP методом POST. Открытие адреса в браузерной строке выполняет GET и не запускает просмотр.

Аутентификация¶

WHEP использует общую авторизацию проигрывания. Передайте разрешённый токен в Authorization: Bearer PLAY_TOKEN или ?token=PLAY_TOKEN. Допуск проверяется при создании сессии; переданные байты учитываются в сессии просмотра. Токен публикации сам по себе не разрешает просмотр.

Транспорт¶

HTTP(S) служит для согласования SDP и управления сессией. Медиаданные передаются по UDP с ICE и DTLS-SRTP/SRTCP. В браузере используйте HTTPS; доступ к HTTP-листенеру и доступ к UDP-порту требуются независимо.

Если браузерная страница и WHIP/WHEP-адрес находятся на разных origin, добавьте на HTTPS-прокси заголовок ответа Access-Control-Expose-Headers: Location: клиенту нужен доступ к адресу созданной сессии. При размещении страницы и API на одном origin это не требуется.

Поддерживаемые кодеки¶

H.264
AV1
Opus

Видео — H.264 или AV1, аудио — Opus. При согласовании H.264 имеет приоритет; в WHEP результат зависит также от кодеков исходного стрима и возможностей плеера. Модуль WebRTC не транскодирует: другой аудиокодек заранее преобразуйте в Opus. HEVC и VP8/VP9 этим трактом не поддерживаются. WHEP требует поддерживаемую видеодорожку, аудио необязательно.

HTTP API¶

Метод и путь	Результат
`POST /streaming/whep/{stream}`	SDP offer (`application/sdp`); ответ `201 Created`, SDP answer и `Location` с адресом сессии
`GET /streaming/whep/{stream}`	`204 No Content`; не возвращает видео или страницу плеера
`OPTIONS /streaming/whep/{stream}`	CORS и допустимые типы содержимого
`DELETE /streaming/whep/session/{id}`	Закрыть сессию; ответ `204 No Content`
`PATCH /streaming/whep/session/{id}`	Для допустимого непустого SDP-фрагмента — `501 Not Implemented`

В offer передаются все ICE-кандидаты клиента: последующее добавление кандидатов через PATCH не поддерживается. Сохраните Location из ответа и используйте его для завершения сессии. Сервер отвечает recvonly для WHIP и sendonly для WHEP.

Требования и поведение¶

Поток должен быть запущен и выдавать корректный MediaInfo. Клиенту нужны доступный UDP-порт и поддерживаемые кодеки. SRTP защищает соединение, но WHEP не выдаёт контент с включённым шифрованием DRM.

Поведение при ошибках¶

Код	Причина
`400`	Некорректный SDP или несогласуемое предложение
`403`	Отказ в доступе; для WHEP также выдача зашифрованного контента
`404`	Стрим не запущен; для WHEP также нет готового описания дорожек
`415`	Неверный Content-Type; для WHEP также отсутствует поддерживаемая видеодорожка
`503`	Не удалось зарегистрировать медиамаршрут; для WHEP также временно недоступна группа зрителей

Ограничения¶

Используется первоначальный обмен offer/answer со всеми ICE-кандидатами. Trickle ICE, ICE restart, WHEP counter-offer и TCP fallback не реализованы. Изменение списка UDP-слушателей пересоздаёт транспорт: для действующих клиентов установите соединение заново. При неизменном списке работающие сокеты сохраняются.