Media over QUIC¶

media.play.moq

O Sapsan entrega mídia ao vivo por Media over QUIC: o cliente se conecta ao servidor, escolhe um stream e assina suas faixas. O Sapsan atua como publicador de mídia. A fonte de entrada pode usar outro protocolo, como RTSP.

A implementação atual usa o MoQT transport draft-19. Essa é uma versão específica de um Internet-Draft; a compatibilidade do cliente deve ser verificada com essa versão. O formato do catálogo segue o MSF draft-01, e a mídia é transmitida em CMAF.

Como a entrega funciona¶

Para cada stream ativo, o Sapsan publica um broadcast com namespace igual ao nome do stream. Por exemplo, cam se torna o nome que o cliente escolhe ao assinar.

• Descoberta — assinar um prefixo vazio do namespace permite obter a lista de streams publicados.
• Catálogo — a faixa catalog contém JSON com a descrição da mídia e os dados de inicialização.
• Faixas — vídeo e áudio são publicados com nomes como v1 e a1.
• Objetos — as partes CMAF são transmitidas à medida que ficam disponíveis. O limite de um segmento inicia um novo grupo, e suas partes se tornam objetos consecutivos.

Um cliente que se conecta no meio de um segmento espera um início de grupo adequado. Uma assinatura já estabelecida recebe os objetos seguintes à medida que são produzidos. A latência final depende da fonte, da codificação, da estrutura dos segmentos e das partes, da rede e do buffer do reprodutor.

Duas formas de conexão compartilham o mesmo listener UDP:

Esse caminho oferece entrega de vídeo e áudio ao vivo. Ele não oferece reprodução de DVR/VOD, captura de câmeras por MoQ nem entrega de legendas. Uma assinatura MoQ não substitui a configuração da fonte ou do transcodificador.

Configuração do listener¶

Defina listeners.moq nas configurações do streamer. Em uma instalação em operação, a configuração é gerenciada pelo central. Para uma verificação local, use o seguinte fragmento de configuração do servidor:

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

Substitua a fonte e os caminhos do certificado e da chave. bind é um endereço IP numérico e uma porta UDP; a porta 4443 foi escolhida para o exemplo. Permitir apenas TCP nessa porta não possibilita uma conexão QUIC.

Para a primeira verificação no navegador, use uma fonte com H.264 e AAC compatíveis com o navegador escolhido. O catálogo descreve as faixas existentes: o MoQ, por si só, não converte um codec incompatível com o navegador em um compatível. Se necessário, configure antecipadamente a transcodificação.

Acesso ao listener¶

O listener MoQ atual permite acesso aos streams ao vivo publicados pelo servidor sem integração com a autorização HTTP nem com as sessões de reprodução. A validação de um ticket JWT ou de ?token= para HLS não se aplica ao MoQ. O TLS criptografa o transporte, mas não determina quem pode assinar um stream específico.

Ao escolher o endereço do listener, considere quais clientes conseguem acessá-lo. No exemplo, ele fica acessível apenas na máquina local. Para um ambiente de teste remoto, restrinja o acesso de rede à porta UDP aos participantes da verificação.

Verificação do recebimento de mídia¶

A árvore de código-fonte do Sapsan inclui a ferramenta moq-probe. Ela estabelece uma conexão MoQT, descobre o stream e lê o catálogo. Quando uma faixa é especificada, também verifica o recebimento de um objeto de mídia.

Após iniciar o Sapsan com o stream cam ativo e a faixa de vídeo v1, execute o seguinte a partir da raiz da árvore de código-fonte:

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

A compilação da ferramenta exige o ambiente Rust do projeto. MOQ_PROBE_SERVER aceita IP e porta, sem o prefixo https://; o nome do broadcast e o da faixa devem corresponder ao stream em execução.

Resultado esperado:

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

O parâmetro MOQ_PROBE_TRACK é importante: sem ele, o sucesso significa que o catálogo foi verificado, mas não que um objeto de vídeo foi recebido. A ferramenta verifica a estrutura do objeto CMAF, sem decodificar a imagem e o áudio. Essa ferramenta de diagnóstico também ignora a verificação do certificado do servidor; portanto, seu sucesso não confirma a confiança TLS de um cliente comum.

Um HTTPS GET comum ou a abertura do endereço do listener MoQ como página web não faz uma assinatura da mídia nem substitui essa verificação.

Verificação da reprodução no navegador¶

A árvore de código-fonte inclui um ambiente de teste com o reprodutor padrão @moq/watch e uma versão compatível fixada da biblioteca cliente. Os comandos a seguir são executados a partir da raiz do repositório Sapsan.

1. Crie um certificado de teste:

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

O script cria crates/moq/tests/wt-cert.pem e wt-key.pem. Informe seus caminhos absolutos em certificate e private_key do listener. É um certificado ECDSA de 14 dias, adequado à verificação pelo hash fixado do certificado no ambiente de teste do navegador.

1. Inicie o Sapsan com essa configuração e uma fonte compatível. Por exemplo, para execução local a partir do código-fonte:

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

Esse comando é destinado ao ambiente de teste local. Os recursos adicionais dessa execução dependem da compilação; para a verificação, escolha uma fonte compatível que já esteja funcionando.

1. Inicie a parte do navegador:

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

São necessários bun, git e openssl; na primeira execução, o script obtém as dependências. Ele inicia o ambiente de teste cliente, não o próprio Sapsan.

1. Abra http://localhost:5173/sapsan.html?name=cam em um navegador com suporte a WebTransport. Por padrão, o ambiente se conecta a https://127.0.0.1:4443. Inicie a reprodução e ative o áudio com um clique, se o navegador exigir.

O critério de sucesso da verificação no navegador é a reprodução de imagem e áudio, não apenas o aparecimento do nome do stream na lista. O uso de localhost é intencional: o WebTransport exige um contexto seguro, e uma página HTTP comum acessada por um IP da LAN não equivale a essa execução. O indicador do buffer do reprodutor também não mede a latência total da câmera à tela.