Media Playback

Propósito

Esta página documenta la capa de playback del Media Agent. El high-level role está en Media Agent; las tools están en Media Tools; los failure modes están en Failure Catalog.

La página cubre:

• Los tres playback backends y cuándo usar cada uno.
• Device discovery para cada backend.
• Los control protocols y cómo los usa el Media Agent.
• Los named invocation patterns que soporta el agent.
• Configuration y security.

Backends de un vistazo

El Media Agent elige el backend usando las rules en Backend selection. El usuario puede override la elección especificando el backend explícitamente.

Chromecast

Chromecast es el backend primario para cloud streaming sources en una TV o display que soporte Cast. Es la opción más user-friendly: un solo command para encontrar el device, un solo command para empezar el playback.

Device discovery

Los dispositivos Chromecast se descubren en la LAN usando mDNS (multicast DNS). El Media Agent corre un discovery scan cuando:

• El agent arranca.
• El usuario lanza un command "find devices" explícito.
• Un Cast command falla con un error "device not found".

El discovery devuelve una lista de devices con sus friendly names y direcciones IP. El Media Agent cachea la lista durante la sesión.

Source selection

Chromecast puede reproducir sources que soporte el media player del device. Los formatos comunes incluyen:

• HLS (HTTP Live Streaming).
• DASH (MPEG-DASH).
• MP4 (single-bitrate).
• WebM.
• Algunos formatos de imagen para ambient screens.

Cuando la stream source elegida no está en un formato Cast-compatible, el Media Agent cae a:

• Una source distinta en formato Cast-compatible.
• VLC (si la source es local o transcodable).
• Un error "format not supported".

Control protocol

Chromecast se controla usando el Cast protocol de Google. El Media Agent abre una conexión TLS con el device en el puerto 8009 y envía un LOAD command en formato JSON con la media URL, el content type y los metadata (title, thumb).

El playback control (pause, resume, seek, volume) se envía por la misma conexión como commands SET y STOP adicionales.

Failure modes

VLC

VLC es el swiss-army-knife backend del lab. Soporta ficheros locales, network streams, transcoding, output multi-destination, y headless playback. Se controla por red a través de las interfaces Remote Control (RC) y HTTP de VLC.

Por qué VLC en el lab

VLC está incluido porque los media workflows del lab suelen necesitar algo que Chromecast no puede hacer:

• Ficheros locales. Chromecast no puede reproducir un fichero que vive en el filesystem del Media Agent. VLC sí.
• Network streams. VLC puede ingerir HTTP, HLS, RTMP, UDP, RTSP y muchos otros protocols. Chromecast es limitado.
• Transcoding. VLC puede transcodear on the fly (p. ej., HEVC a H.264) para reproducir un fichero en un device que no soporta el codec de la source.
• Multi-destination. VLC puede enviar la misma source a varios outputs a la vez: vídeo a una TV, audio a un altavoz en otra habitación.
• Headless. VLC puede correr sin display, streameando solo audio o empujando output a un network sink.
• No vendor lock-in. VLC es open source y corre en todas las plataformas principales. El lab no depende del protocol de un único vendor.

Device discovery

Las instancias de VLC en la LAN se descubren de dos maneras:

1. mDNS. VLC publica un mDNS service cuando corre con la RC interface habilitada. El Media Agent escanea la LAN buscando servicios _vlc-http._tcp.
2. Static configuration. El usuario puede añadir hosts de VLC a la configuration del Media Agent por dirección IP y puerto. Esta es la vía documentada para añadir hosts que no anuncian mDNS (p. ej., una Raspberry Pi en otra VLAN).

Control protocols

VLC expone dos control interfaces.

VLC Remote Control (RC)

Un command protocol basado en TCP y line-based en un puerto configurable (default 4212). El Media Agent abre una conexión TCP y envía text commands. Cada command devuelve una status line.

Commands comunes:

La RC interface es simple y estable. Es la opción documentada para control scripted de VLC.

VLC HTTP

Una HTTP API basada en JSON en un puerto configurable (default 8080). El Media Agent usa la HTTP API para:

• Browse de la playlist actual.
• Setear stream outputs (/requests/status.xml).
• Disparar mosaic outputs.
• Consultar status extendido (codec, bitrate, frame rate).

La HTTP API está documentada en la upstream documentation de VLC. El Media Agent envuelve la API en una tool que expone solo las operaciones que el lab necesita.

Invocation patterns

El Media Agent soporta los siguientes named invocation patterns. Cada pattern corresponde a un caso de uso real.

Local file to the default display

Reproduce un fichero local en el display propio del Media Agent. Se usa cuando el usuario quiere ver en la máquina que corre el agent.

vlc --intf dummy --play-and-exit /path/to/movie.mkv

La dummy interface evita que se abra la GUI de VLC; el output va al display por defecto. --play-and-exit termina VLC cuando el playback termina.

Local file to a remote VLC on the LAN

Reproduce un fichero local en otra máquina que tenga VLC corriendo con la RC interface habilitada.

# En la máquina target, arranca VLC con la RC interface:
vlc --intf rc --rc-host 0.0.0.0:4212 --rc-password secret
 
# En el Media Agent, envía el command:
echo "add /shared/movies/movie.mkv" | nc 192.168.1.42 4212
echo "play" | nc 192.168.1.42 4212

El command add encola el fichero; play empieza el playback. El fichero debe ser alcanzable desde la máquina target (filesystem compartido, NFS, o pre-staged).

Network stream to a remote VLC

Reproduce un stream HTTP, HLS o RTMP en una instancia remota de VLC.

echo "add http://example.com/stream.m3u8" | nc 192.168.1.42 4212
echo "play" | nc 192.168.1.42 4212

Stream to multiple destinations

Arranca una instancia de VLC que envía la misma source a dos outputs a la vez (p. ej., vídeo a una TV vía Cast, audio a un altavoz vía stream output de VLC).

Este pattern usa la cadena de output duplicate de VLC. La configuration se guarda como named profile en la configuration del Media Agent.

vlc /path/to/movie.mkv \
  --sout "#duplicate{dst=display,dst=transcode{acodec=mp3,ab=128}:std{access=http,mux=mp3,dst=:8080/stream.mp3}}"

El audio se expone como un HTTP stream; el audio client del usuario se conecta a él.

Transcoding on the fly

Transcodea la source a un codec distinto antes de enviarla a un device que no soporta el codec de la source.

vlc /path/to/hevc-movie.mkv \
  --sout "#transcode{vcodec=h264,vfilter=transform{type=90},acodec=mp4a}:standard{access=http,mux=ts,dst=:8080/stream.ts}"

El output transcodificado se expone como un HTTP stream. El target device consume el stream en un formato que soporta.

Headless / audio-only

Corre VLC sin display, streameando solo la audio track a un audio device configurado o a un network audio sink.

vlc /path/to/album.flac \
  --intf dummy --no-video \
  --sout "#transcode{acodec=mp3,ab=192}:standard{access=http,mux=mp3,dst=:8080/audio.mp3}"

El flag no-video desactiva el output de vídeo. El audio se expone como un HTTP stream.

Naming VLC hosts

Un VLC host es un target device que corre VLC con una control interface habilitada. El Media Agent se puede configurar con named hosts:

El usuario puede referirse a los hosts por nombre en requests en lenguaje natural ("ponlo en el display de la cocina"). El Coordinator resuelve el nombre y forward la request al Media Agent.

Security

Las interfaces RC y HTTP de VLC no tienen autenticación built-in más allá de una password opcional. La configuration del Media Agent declara la password para cada host.

El Media Agent:

• Almacena las passwords de host en el agent configuration file (no en memoria).
• Usa una allowlist per-host: un host solo puede ser controlado por requests que matcheen su nombre declarado.
• Loguea cada command enviado a un host.

Una request a un host que el usuario no nombró se rechaza. Esto evita que el Media Agent se use para controlar hosts que el usuario no tenía intención de controlar.

Failure modes

Direct player

El direct player backend es el más simple. El Media Agent hace spawn del media player por defecto del sistema (o un fallback configurado) con la source como argumento.

Este backend se usa raramente porque VLC con localhost como target ofrece la misma funcionalidad con más control. El direct player se reserva para casos en los que el usuario pide explícitamente el default del sistema.

Backend selection

El Media Agent elige un backend usando las siguientes rules, en orden:

1. Explicit user request. Si el usuario nombró un backend ("ponlo con VLC", "mándalo al Chromecast"), se usa ese backend.
2. Source type.
   • Fichero local → VLC (o direct si el usuario prefiere).
   • Cloud stream (HLS, DASH, MP4 URL) → Chromecast si hay un Cast device disponible; VLC en caso contrario.
   • Network stream (HTTP, RTMP, UDP) → VLC.
3. Target device.
   • Cast-capable display en la LAN → Chromecast.
   • Device corriendo VLC → VLC.
   • Display propio del Media Agent → direct (o VLC).
4. User preference. El usuario puede declarar un default backend en la configuration. El default se usa cuando las rules de arriba no identifican un backend de forma única.

La selección se registra en el resultado. El usuario puede override la selección enviando una nueva request con un backend explícito.

Configuration

La configuration del Media Agent está en el per-agent file del framework. Los campos relevantes para la capa de playback:

Los cambios de configuration requieren autorización explícita del usuario.

See also

• Media Agent
• Tooling Layer → Media Tools
• Failure Catalog