Media Agent

Status

Implemented. Media search, source identification, and playback control are operational across three backends (Stremio catalog, Chromecast device target, VLC playback engine). Expansion (Plex/Radarr integration, custom Stremio addon) is planned.

Role

The Media Agent is responsible for local entertainment automation. Given a media request, it:

• Searches for matching titles using media-specific tools.
• Evaluates availability across supported streaming platforms.
• Identifies stream sources.
• Initiates playback to a connected device using the most appropriate backend for the request (Chromecast, VLC, or a direct local player).

The Media Agent is stateless beyond its configuration and a short in-memory session for the current request. It does not write to memory.

Architecture

The Media Agent has the following components:

The Media Agent runs in its own gateway process. It accepts media requests from the Coordinator and returns playback results.

Playback backends

The Media Agent supports three playback backends, chosen per request based on the source type, the target device, and the user's stated preference.

The choice is made by the Media Agent using the rules in Media Playback. The user can override the choice by specifying the backend explicitly in the request.

Chromecast

Chromecast is the primary backend when the user wants to play a streaming source on a TV or display that supports Cast. The integration is implemented through a dedicated tool that:

• Discovers Chromecast devices on the LAN using mDNS.
• Selects a Cast-capable stream source.
• Constructs and sends the Cast LOAD command.
• Reports playback status.

Chromecast is documented in detail in Media Playback → Chromecast.

VLC

VLC is the lab's swiss-army-knife playback backend. It is used when:

• The source is a local file (downloaded release, archived recording, screen capture).
• The source is a network stream (HTTP, HLS, RTMP, UDP).
• The target is not a Cast device but a device that can run VLC (a computer, a Raspberry Pi, a NAS, an Android TV box, a smartphone with VLC installed).
• The user wants transcoding (e.g., to play a HEVC file on a device that only supports H.264).
• The user wants to send audio to a separate audio device while the video plays on a TV.
• The user wants headless or audio-only playback.

VLC supports multiple simultaneous output targets through its mosaic and stream output features. The Media Agent uses this to send a single source to several destinations at once (e.g., video to the TV, audio to a speaker in another room).

VLC is controlled over the network through its Remote Control interface (RC, a TCP-based command protocol) and its HTTP interface. The Media Agent invokes VLC through a dedicated tool that wraps both protocols.

VLC is documented in detail in Media Playback → VLC.

Direct player

The direct player backend is used when the source is a local file and the user does not need a remote device. The Media Agent spawns the system's default media player (or a configured fallback). This backend is rarely used; the typical case is VLC with localhost as the target, which provides the same functionality with more control.

Streaming integration

The Media Agent integrates with streaming platforms through dedicated tools. The current inventory is:

The tools are described in Tooling Layer → Media Tools.

Request flow

A media request flows through the Media Agent as follows:

1. Receive. The Coordinator sends a media request with the title (and optionally a year, genre, quality, source preference, or target device).
2. Search. The Media Agent queries the configured catalogs for matches. It uses the title plus any supplied qualifiers.
3. Rank. The Media Agent ranks the matches by relevance. The ranking takes into account the user's stated preferences (if any) and the source's reputation.
4. Source selection. The Media Agent identifies the best stream source for the top-ranked match. The selection considers quality, language, availability, and source type (local file vs. cloud stream).
5. Backend selection. The Media Agent chooses the playback backend. The default is Chromecast when a Cast device is available; VLC when the source is local or when the user specifies VLC; direct when neither is suitable.
6. Playback. The Media Agent constructs the playback command for the chosen backend and sends it to the target.
7. Result. The Media Agent returns a structured result: the selected title, the source, the target, the backend, and the playback status.

VLC invocation patterns

The Media Agent supports the following VLC invocation patterns. Each pattern is a named flow in the agent's runtime; the user can trigger any of them by describing the desired outcome in natural language.

Local file to the default display

The simplest pattern. Play a file on the machine that runs the Media Agent, using its default display.

playback: local file /path/to/movie.mkv -> display localhost

Local file to a remote VLC on the LAN

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

playback: local file /path/to/movie.mkv -> vlc-rc 192.168.1.42:4212

Stream from a torrent source to Chromecast

The torrent source is downloaded (or streamed in place) and the output is fed to a Cast device. This pattern uses the media-info tool to identify compatible streams and the Chromecast tool to send the LOAD command.

Stream to multiple destinations

The Media Agent starts a VLC instance with multiple output targets: video to the TV (via Cast or direct), audio to a speaker in another room (via VLC's stream output). This pattern is useful for parties or for distributing playback across rooms.

Transcoding on the fly

The Media Agent starts a VLC instance that transcodes the source to a target codec (e.g., HEVC to H.264) before sending it to the device. This is useful when the target device does not support the source's codec.

Headless / audio-only

The Media Agent starts a VLC instance with no video output, streaming only the audio track to a configured audio device or to a network audio sink.

The full invocation syntax, the supported targets, and the configuration options are documented in Media Playback → VLC Invocation.

Priority mode

The Media Agent operates in priority mode: an active media request takes precedence over background tasks. The agent is designed for low-latency interaction, not batch processing.

Relationship with the Coordinator

The Coordinator delegates media requests to the Media Agent. The Media Agent does not initiate work independently — it receives tasks from the Coordinator and reports completion.

The handoff is one-way: the Coordinator sends a request, the Media Agent executes it, the result is returned. The Media Agent does not ask the user clarifying questions; the Coordinator is responsible for clarifying intent before sending the request.

Relationship with the Research Worker

The Media Agent and the Research Worker were initially prototyped in a shared runtime. The architecture models them as separate logical agents because their responsibilities, tools, and risk profiles differ. See ADR-001.

Key distinctions:

The two agents do not share memory. The Media Agent has no persistent memory layer; the Research Worker has its own workspace memory for mission artifacts.

Configuration

The Media Agent is configured through the framework's per-agent configuration. The configuration declares:

• The streaming platforms to query.
• The default target device per backend.
• The VLC host, port, and password (if RC is enabled).
• The default transcoding profile.
• The fallback behavior when the preferred backend is unavailable.

Configuration changes are made by the Coordinator and require explicit user authorization.

Failure modes

All failure modes are logged. The Coordinator surfaces the result to the user with the original failure context preserved.

Future work

• Media Organizer — automated local media library management.
• Plex/Radarr Integration Hub — connection between media discovery and local media server.
• Stremio Addon Server — custom Stremio addon for lab-curated sources.
• Expanded platform support — additional streaming services and device targets.
• VLC mosaic profiles — preconfigured multi-output profiles for common scenarios (party, multi-room, audio-only).

See also

• Agents and Roles
• Coordinator
• Research Worker
• Media Playback
• Tooling Layer → Media Tools
• Failure Catalog