Reprodução WebRTC (WHEP)¶

media.play.webrtc

Configuração¶

Defina estas opções pelo central. Exemplo de config do streamer:

listeners.webrtc define portas UDP compartilhadas por WHIP e WHEP. Se estiver ausente ou vazio, o sistema operacional seleciona uma porta livre. port: 0 também ativa a seleção automática. Os candidatos ICE do SDP anunciam a porta atribuída; não existe uma porta exclusiva por sessão. Reaplicar a mesma lista mantém a porta. Uma reinicialização pode alterá-la.

Parâmetro	Valor	Comportamento
`listeners.webrtc`	Ausente ou `[]`	Uma porta UDP automática
`listeners.webrtc[].port`	Obrigatório por entrada, `0`–`65535`	`0` seleciona a porta automaticamente; outro valor a fixa

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

Para regras fixas de firewall ou encaminhamento atrás de NAT, configure portas explícitas e permita o acesso dos clientes. O proxy HTTP trata o SDP; a mídia UDP deve chegar ao próprio streamer. O endereço ICE vem do roteamento IPv4 local; listeners.webrtc não tem ajuste de endereço ICE público nem TURN. A seleção automática de porta não configura NAT.

URL de reprodução¶

URL direta do streamer:

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

Esta URL é para um cliente WHEP que envia SDP por POST. Abri-la na barra do navegador executa GET e não inicia a reprodução.

Autenticação¶

WHEP usa a autorização de reprodução. Envie um token permitido em Authorization: Bearer PLAY_TOKEN ou ?token=PLAY_TOKEN. O acesso é verificado ao criar a sessão; os bytes são contabilizados nela. Um token de publicação não concede acesso de reprodução por si só.

Transporte¶

HTTP(S) trata o SDP e o controle da sessão. A mídia usa UDP com ICE e DTLS-SRTP/SRTCP. Use HTTPS no navegador; acesso HTTP e acesso à porta UDP são requisitos independentes.

Se a página do navegador e o endpoint WHIP/WHEP usam origens diferentes, adicione no proxy HTTPS o cabeçalho de resposta Access-Control-Expose-Headers: Location para o cliente ler a URL da sessão. Isso não é necessário quando a página e a API compartilham a origem.

Codecs compatíveis¶

H.264
AV1
Opus

O vídeo usa H.264 ou AV1; o áudio, Opus. H.264 tem preferência na negociação; WHEP também depende dos codecs da origem e do reprodutor. WebRTC não transcodifica: converta outros codecs de áudio para Opus antes. HEVC e VP8/VP9 não são suportados neste processamento. WHEP exige uma faixa de vídeo compatível; o áudio é opcional.

API HTTP¶

Método e caminho	Resultado
`POST /streaming/whep/{stream}`	Oferta SDP (`application/sdp`); retorna `201 Created`, resposta SDP e URL da sessão em `Location`
`GET /streaming/whep/{stream}`	`204 No Content`; não retorna vídeo nem página de reprodutor
`OPTIONS /streaming/whep/{stream}`	CORS e tipos de conteúdo aceitos
`DELETE /streaming/whep/session/{id}`	Encerra a sessão; retorna `204 No Content`
`PATCH /streaming/whep/session/{id}`	Um fragmento SDP válido não vazio recebe `501 Not Implemented`

A oferta deve incluir todos os candidatos ICE do cliente; adicioná-los depois por PATCH não é suportado. Guarde Location para encerrar a sessão. O servidor responde recvonly para WHIP e sendonly para WHEP.

Requisitos e comportamento¶

O stream deve estar ativo e fornecer MediaInfo válido. O cliente precisa de porta UDP acessível e codecs compatíveis. SRTP protege a conexão, mas WHEP não entrega conteúdo com criptografia DRM ativada.

Tratamento de erros¶

Código	Causa
`400`	SDP inválido ou oferta que não pode ser negociada
`403`	Acesso negado; WHEP também recusa conteúdo criptografado
`404`	O stream não está ativo; WHEP também exige informações de faixas disponíveis
`415`	Content-Type incorreto; WHEP também exige vídeo compatível
`503`	Falha ao registrar a rota de mídia; um grupo WHEP também pode estar temporariamente indisponível

Limitações¶

A oferta e a resposta iniciais incluem todos os candidatos ICE. Trickle ICE, reinício ICE, contraoferta WHEP e alternativa TCP não estão implementados. Alterar a lista de portas UDP recria o transporte: reconecte os clientes. Uma lista inalterada mantém os sockets.