Media over QUIC¶

media.play.moq

Sapsan entrega medios en directo por Media over QUIC: el cliente se conecta al servidor, elige un stream y se suscribe a sus pistas. Sapsan actúa como publicador de medios. La fuente de entrada puede usar otro protocolo, por ejemplo, RTSP.

La implementación actual utiliza MoQT transport draft-19. Es una versión concreta de un Internet-Draft; la compatibilidad del cliente debe comprobarse con esa versión. El formato del catálogo sigue MSF draft-01, y los medios se transmiten en CMAF.

Cómo funciona la entrega¶

Para cada stream activo, Sapsan publica un broadcast cuyo espacio de nombres coincide con el nombre del stream. Por ejemplo, cam se convierte en el nombre que el cliente elige al suscribirse.

Descubrimiento — una suscripción a un prefijo vacío del espacio de nombres permite obtener la lista de streams publicados.
Catálogo — la pista catalog contiene JSON con la descripción de los medios y los datos de inicialización.
Pistas — el vídeo y el audio se publican con nombres como v1 y a1.
Objetos — las partes CMAF se transmiten a medida que están disponibles. El límite de un segmento inicia un grupo nuevo, y sus partes se convierten en objetos consecutivos.

Un cliente que se conecta a mitad de un segmento espera un inicio de grupo adecuado. Una suscripción establecida recibe los objetos siguientes a medida que se producen. La latencia final depende de la fuente, la codificación, la estructura de segmentos y partes, la red y el búfer del reproductor.

Hay dos formas de conexión a un mismo listener UDP:

Cliente	Transporte
Cliente MoQT nativo	QUIC con ALPN `moqt-19`.
Navegador	WebTransport sobre HTTP/3, ALPN `h3`; el cliente utiliza una variante compatible de MoQT draft-19.

Esta ruta está destinada a la entrega de vídeo y audio en directo. No ofrece reproducción de DVR/VOD, captura de cámaras por MoQ ni entrega de subtítulos. La suscripción MoQ no sustituye la configuración de la fuente o del transcodificador.

Configuración del listener¶

Defina listeners.moq en los ajustes del streamer. En una instalación operativa, la configuración se gestiona mediante central. Para una comprobación local, puede usar este fragmento de configuración del 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

Sustituya la fuente y las rutas del certificado y de la clave. bind es una dirección IP numérica y un puerto UDP; el puerto 4443 se ha elegido para el ejemplo. Permitir solo TCP en ese puerto no permite establecer una conexión QUIC.

Para la primera comprobación en navegador, utilice una fuente con H.264 y AAC compatibles con el navegador elegido. El catálogo describe las pistas existentes: MoQ por sí solo no convierte un códec incompatible con el navegador en uno compatible. Si hace falta, configure previamente la transcodificación.

Acceso al listener¶

El listener MoQ actual permite acceder a los streams en directo publicados por el servidor sin integración con la autorización HTTP ni con las sesiones de reproducción. La validación de un ticket JWT o de ?token= para HLS no se aplica a MoQ. TLS cifra el transporte, pero no determina quién puede suscribirse a un stream concreto.

Al elegir la dirección del listener, tenga en cuenta qué clientes pueden alcanzarlo. En este ejemplo, solo es accesible desde la máquina local. Para un entorno de prueba remoto, limite el acceso de red al puerto UDP a los participantes de la prueba.

Verificación de la recepción de medios¶

El árbol de fuentes de Sapsan incluye la utilidad moq-probe. Establece una conexión MoQT, descubre el stream y lee el catálogo. Si se especifica una pista, también verifica la recepción de un objeto multimedia.

Después de iniciar Sapsan con el stream cam activo y la pista de vídeo v1, ejecute lo siguiente desde la raíz del árbol de fuentes:

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

Para compilar la utilidad se necesita el entorno Rust del proyecto. MOQ_PROBE_SERVER acepta una IP y un puerto, sin el prefijo https://; el nombre del broadcast y de la pista deben coincidir con el stream en ejecución.

Resultado esperado:

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

El parámetro MOQ_PROBE_TRACK es importante: sin él, un resultado correcto significa que se ha comprobado el catálogo, pero no se ha recibido un objeto de vídeo. La utilidad comprueba la estructura del objeto CMAF, sin decodificar la imagen ni el audio. Esta utilidad de diagnóstico también omite la verificación del certificado del servidor, por lo que su éxito no confirma la confianza TLS de un cliente normal.

Un HTTPS GET convencional o abrir la dirección del listener MoQ como una página web no realiza una suscripción a los medios ni sustituye esta comprobación.

Verificación de la reproducción en el navegador¶

El árbol de fuentes incluye un entorno de prueba con el reproductor estándar @moq/watch y una versión compatible fijada de la biblioteca cliente. Los siguientes comandos se ejecutan desde la raíz del repositorio Sapsan.

Cree un certificado de prueba:

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

El script crea crates/moq/tests/wt-cert.pem y wt-key.pem. Especifique sus rutas absolutas en certificate y private_key del listener. Es un certificado ECDSA de 14 días, adecuado para la comprobación mediante el hash fijado del certificado en el entorno de navegador.

Inicie Sapsan con esta configuración y una fuente compatible. Por ejemplo, para una ejecución local desde las fuentes:

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

Este comando está destinado al entorno de prueba local. Las capacidades adicionales de esta ejecución dependen de la compilación; para la comprobación, elija una fuente compatible que ya funcione.

Inicie la parte del navegador:

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

Se necesitan bun, git y openssl; en el primer arranque, el script obtiene las dependencias. Inicia el entorno de prueba cliente, no el propio Sapsan.

Abra http://localhost:5173/sapsan.html?name=cam en un navegador compatible con WebTransport. Por defecto, el entorno se conecta a https://127.0.0.1:4443. Inicie la reproducción y active el audio con un clic si el navegador lo exige.

La comprobación del navegador tiene éxito cuando se reproducen imagen y audio, no solo cuando aparece el nombre del stream en la lista. El uso de localhost es intencional: WebTransport exige un contexto seguro, y una página HTTP convencional accedida por una IP de la LAN no equivale a este entorno. El indicador del búfer del reproductor tampoco mide la latencia total desde la cámara hasta la pantalla.