Media Playback

Purpose

This page documents the playback layer of the Media Agent. The high-level role is in Media Agent; the tools are in Media Tools; the failure modes are in Failure Catalog.

The page covers:

• The three playback backends and when to use each.
• Device discovery for each backend.
• Control protocols and how the Media Agent uses them.
• Named invocation patterns the agent supports.
• Configuration and security.

Backends at a glance

The Media Agent chooses the backend using the rules in Backend selection. The user can override the choice by specifying the backend explicitly.

Chromecast

Chromecast is the primary backend for cloud streaming sources to a TV or display that supports Cast. It is the most user-friendly option: a single command to find the device, a single command to start playback.

Device discovery

Chromecast devices are discovered on the LAN using mDNS (multicast DNS). The Media Agent runs a discovery scan when:

• The agent starts.
• The user issues an explicit "find devices" command.
• A Cast command fails with a "device not found" error.

The discovery returns a list of devices with their friendly names and IP addresses. The Media Agent caches the list for the duration of the session.

Source selection

Chromecast can play sources that the device's media player supports. Common formats include:

• HLS (HTTP Live Streaming).
• DASH (MPEG-DASH).
• MP4 (single-bitrate).
• WebM.
• Some image formats for ambient screens.

When the chosen stream source is not in a Cast-compatible format, the Media Agent falls back to:

• A different source in a Cast-compatible format.
• VLC (if the source is local or transcodable).
• A "format not supported" error.

Control protocol

Chromecast is controlled using Google's Cast protocol. The Media Agent opens a TLS connection to the device on port 8009 and sends a JSON-formatted LOAD command with the media URL, the content type, and the metadata (title, thumb).

Playback control (pause, resume, seek, volume) is sent over the same connection as additional SET and STOP commands.

Failure modes

VLC

VLC is the lab's swiss-army-knife backend. It supports local files, network streams, transcoding, multi-destination output, and headless playback. It is controlled over the network through VLC's Remote Control (RC) and HTTP interfaces.

Why VLC in the lab

VLC is included because the lab's media workflows often need something Chromecast cannot do:

• Local files. Chromecast cannot play a file that lives on the Media Agent's filesystem. VLC can.
• Network streams. VLC can ingest HTTP, HLS, RTMP, UDP, RTSP, and many other protocols. Chromecast is limited.
• Transcoding. VLC can transcode on the fly (e.g., HEVC to H.264) to play a file on a device that does not support the source codec.
• Multi-destination. VLC can send the same source to several outputs at once: video to a TV, audio to a speaker in another room.
• Headless. VLC can run without a display, streaming only audio or pushing output to a network sink.
• No vendor lock-in. VLC is open source and runs on every major platform. The lab does not depend on a single vendor's protocol.

Device discovery

VLC instances on the LAN are discovered in two ways:

1. mDNS. VLC publishes an mDNS service when running with the RC interface enabled. The Media Agent scans the LAN for _vlc-http._tcp services.
2. Static configuration. The user can add VLC hosts to the Media Agent's configuration by IP address and port. This is the documented way to add hosts that do not advertise mDNS (e.g., a Raspberry Pi on a different VLAN).

Control protocols

VLC exposes two control interfaces.

VLC Remote Control (RC)

A line-based TCP protocol on a configurable port (default 4212). The Media Agent opens a TCP connection and sends text commands. Each command returns a status line.

Common commands:

The RC interface is simple and stable. It is the documented choice for scripted control of VLC.

VLC HTTP

A JSON-based HTTP API on a configurable port (default 8080). The Media Agent uses the HTTP API for:

• Browsing the current playlist.
• Setting up stream outputs (/requests/status.xml).
• Triggering mosaic outputs.
• Querying extended status (codec, bitrate, frame rate).

The HTTP API is documented in VLC's upstream documentation. The Media Agent wraps the API in a tool that exposes only the operations the lab needs.

Invocation patterns

The Media Agent supports the following named invocation patterns. Each pattern corresponds to a real-world use case.

Local file to the default display

Play a local file on the Media Agent's own display. Used when the user wants to watch on the machine that runs the agent.

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

The dummy interface prevents the VLC GUI from opening; the output goes to the default display. --play-and-exit terminates VLC when playback finishes.

Local file to a remote VLC on the LAN

Play a local file on another machine that has VLC running with the RC interface enabled.

# On the target machine, start VLC with the RC interface:
vlc --intf rc --rc-host 0.0.0.0:4212 --rc-password secret
 
# On the Media Agent, send the command:
echo "add /shared/movies/movie.mkv" | nc 192.168.1.42 4212
echo "play" | nc 192.168.1.42 4212

The add command enqueues the file; play starts playback. The file must be reachable from the target machine (shared filesystem, NFS, or pre-staged).

Network stream to a remote VLC

Play an HTTP, HLS, or RTMP stream on a remote VLC instance.

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

Start a VLC instance that sends the same source to two outputs at once (e.g., video to a TV via Cast, audio to a speaker via VLC's stream output).

This pattern uses VLC's duplicate output chain. The configuration is stored as a named profile in the Media Agent's configuration.

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

The audio is exposed as an HTTP stream; the user's audio client connects to it.

Transcoding on the fly

Transcode the source to a different codec before sending it to a device that does not support the source's codec.

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}"

The transcoded output is exposed as an HTTP stream. The target device consumes the stream in a format it supports.

Headless / audio-only

Run VLC without a display, streaming only the audio track to a configured audio device or network 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}"

The no-video flag disables the video output. The audio is exposed as an HTTP stream.

Naming VLC hosts

A VLC host is a target device that runs VLC with a control interface enabled. The Media Agent can be configured with named hosts:

The user can refer to hosts by name in natural-language requests ("play it on the kitchen display"). The Coordinator resolves the name and forwards the request to the Media Agent.

Security

VLC's RC and HTTP interfaces have no built-in authentication beyond an optional password. The Media Agent's configuration declares the password for each host.

The Media Agent:

• Stores host passwords in the agent configuration file (not in memory).
• Uses a per-host allowlist: a host can only be controlled by requests that match its declared name.
• Logs every command sent to a host.

A request to a host that the user did not name is rejected. This prevents the Media Agent from being used to control hosts the user did not intend to control.

Failure modes

Direct player

The direct player backend is the simplest. The Media Agent spawns the system's default media player (or a configured fallback) with the source as an argument.

This backend is rarely used because VLC with localhost as the target provides the same functionality with more control. The direct player is reserved for cases where the user explicitly requests the system default.

Backend selection

The Media Agent chooses a backend using the following rules, in order:

1. Explicit user request. If the user named a backend ("play it with VLC", "send it to the Chromecast"), that backend is used.
2. Source type.
   • Local file → VLC (or direct if the user prefers).
   • Cloud stream (HLS, DASH, MP4 URL) → Chromecast if a Cast device is available; VLC otherwise.
   • Network stream (HTTP, RTMP, UDP) → VLC.
3. Target device.
   • Cast-capable display on the LAN → Chromecast.
   • Device running VLC → VLC.
   • The Media Agent's own display → direct (or VLC).
4. User preference. The user can declare a default backend in the configuration. The default is used when the rules above do not uniquely identify a backend.

The selection is recorded in the result. The user can override the selection by sending a new request with an explicit backend.

Configuration

The Media Agent's configuration is in the framework's per-agent file. The relevant fields for the playback layer:

Configuration changes require explicit user authorization.

See also

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