Media Agent

El Media Agent es el especialista del lab para automatización de entretenimiento local. Maneja búsqueda de media, identificación de fuentes de streaming y control de playback a dispositivos locales y remotos.

Status

Implemented. Media search, source identification y playback control están operacionales a través de tres backends (catálogo de Stremio, target de dispositivo Chromecast, motor de playback VLC). La expansión (integración Plex/Radarr, addon custom de Stremio) está planeada.

Role

El Media Agent es responsable de la automatización de entretenimiento local. Dada una media request:

Busca títulos coincidentes usando tools específicas de media.
Evalúa la disponibilidad en las plataformas de streaming soportadas.
Identifica fuentes de stream.
Inicia el playback en un dispositivo conectado usando el backend más adecuado para la request (Chromecast, VLC, o un direct local player).

El Media Agent es stateless más allá de su configuración y de una sesión corta en memoria para la request actual. No escribe en memoria.

Architecture

El Media Agent tiene los siguientes componentes:

Loading diagram…

El Media Agent corre en su propio gateway process. Acepta media requests del Coordinator y devuelve playback results.

Playback backends

El Media Agent soporta tres playback backends, elegidos por request según el source type, el target device y la preferencia explícita del usuario.

Backend	Best for	Discovery	Control protocol
Chromecast	Streaming desde servicios cloud a una TV en la LAN.	mDNS / SSDP	Cast protocol
VLC	Ficheros locales, network streams, multi-destination, transcoding, headless playback.	mDNS / static config	VLC RC (TCP) + HTTP
Direct player	Ficheros locales cuando no se necesita un remote device.	local FS	process spawn

La elección la hace el Media Agent usando las rules en Media Playback. El usuario puede override la elección especificando el backend explícitamente en la request.

Chromecast

Chromecast es el backend primario cuando el usuario quiere reproducir una streaming source en una TV o display que soporte Cast. La integración se implementa a través de una tool dedicada que:

Descubre dispositivos Chromecast en la LAN usando mDNS.
Selecciona una stream source Cast-capable.
Construye y envía el Cast LOAD command.
Reporta el playback status.

Chromecast está documentado en detalle en Media Playback → Chromecast.

VLC

VLC es el swiss-army-knife playback backend del lab. Se usa cuando:

La source es un fichero local (release descargado, grabación archivada, screen capture).
La source es un network stream (HTTP, HLS, RTMP, UDP).
El target no es un Cast device sino un device que puede correr VLC (un ordenador, una Raspberry Pi, un NAS, un Android TV box, un smartphone con VLC instalado).
El usuario quiere transcoding (p. ej., reproducir un fichero HEVC en un device que solo soporta H.264).
El usuario quiere enviar audio a un audio device separado mientras el vídeo se reproduce en una TV.
El usuario quiere headless o audio-only playback.

VLC soporta múltiples simultaneous output targets a través de sus features de mosaic y stream output. El Media Agent usa esto para enviar una sola source a varios destinos a la vez (p. ej., vídeo a la TV, audio a un altavoz en otra habitación).

VLC se controla por red a través de su Remote Control interface (RC, un command protocol basado en TCP) y de su HTTP interface. El Media Agent invoca VLC a través de una tool dedicada que envuelve ambos protocolos.

VLC está documentado en detalle en Media Playback → VLC.

Direct player

El direct player backend se usa cuando la source es un fichero local y el usuario no necesita un remote device. El Media Agent lanza el media player por defecto del sistema (o un fallback configurado). Este backend se usa raramente; el caso típico es VLC con localhost como target, que ofrece la misma funcionalidad con más control.

Streaming integration

El Media Agent se integra con plataformas de streaming a través de tools dedicadas. El inventario actual es:

Platform	Role
Stremio	Streaming catalog discovery y source selection.
Chromecast	Playback targeting a un display Cast-capable en la LAN.
VLC	Local file playback, network streams, multi-destination, transcoding.
Direct	Spawn del default local player para casos simples.

Las tools se describen en Tooling Layer → Media Tools.

Request flow

Una media request fluye por el Media Agent así:

Receive. El Coordinator envía una media request con el title (y, opcionalmente, year, genre, quality, source preference, o target device).
Search. El Media Agent consulta los catálogos configurados buscando matches. Usa el title más cualquier qualifier que se le haya pasado.
Rank. El Media Agent ordena los matches por relevancia. El ranking tiene en cuenta las preferencias explícitas del usuario (si las hay) y la reputación de la source.
Source selection. El Media Agent identifica la mejor stream source para el match mejor rankeado. La selección considera quality, language, availability y source type (local file vs. cloud stream).
Backend selection. El Media Agent elige el playback backend. El default es Chromecast cuando hay un Cast device disponible; VLC cuando la source es local o cuando el usuario especifica VLC; direct cuando ninguno es adecuado.
Playback. El Media Agent construye el playback command para el backend elegido y lo envía al target.
Result. El Media Agent devuelve un resultado estructurado: el title seleccionado, la source, el target, el backend, y el playback status.

VLC invocation patterns

El Media Agent soporta los siguientes VLC invocation patterns. Cada pattern es un flow con nombre en el runtime del agent; el usuario puede dispararlo describiendo el outcome deseado en lenguaje natural.

Local file to the default display

El pattern más simple. Reproduce un fichero en la máquina que corre el Media Agent, usando su display por defecto.

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

Local file to a remote VLC on the LAN

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

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

Stream from a torrent source to Chromecast

La torrent source se descarga (o se streamea in place) y el output se alimenta a un Cast device. Este pattern usa la tool media-info para identificar streams compatibles y la tool Chromecast para enviar el LOAD command.

Stream to multiple destinations

El Media Agent arranca una instancia de VLC con múltiples output targets: vídeo a la TV (vía Cast o direct), audio a un altavoz en otra habitación (vía stream output de VLC). Este pattern es útil para fiestas o para distribuir playback entre habitaciones.

Transcoding on the fly

El Media Agent arranca una instancia de VLC que transcodea la source a un codec target (p. ej., HEVC a H.264) antes de enviarla al device. Es útil cuando el target device no soporta el codec de la source.

Headless / audio-only

El Media Agent arranca una instancia de VLC sin output de vídeo, streameando solo la audio track a un audio device configurado o a un network audio sink.

La invocation syntax completa, los targets soportados y las configuration options están documentadas en Media Playback → VLC Invocation.

Priority mode

El Media Agent opera en priority mode: una active media request tiene precedencia sobre las background tasks. El agent está diseñado para interacción de baja latency, no para batch processing.

Relationship with the Coordinator

El Coordinator delega media requests al Media Agent. El Media Agent no inicia trabajo de forma independiente — recibe tasks del Coordinator y reporta completion.

El handoff es one-way: el Coordinator envía una request, el Media Agent la ejecuta, el resultado se devuelve. El Media Agent no hace clarifying questions al usuario; el Coordinator es responsable de clarificar el intent antes de enviar la request.

Relationship with the Research Worker

El Media Agent y el Research Worker se prototiparon inicialmente en un shared runtime. La arquitectura los modela como logical agents separados porque sus responsabilidades, tools y risk profiles difieren. Ver ADR-001.

Distinciones clave:

Dimension	Media Agent	Research Worker
Primary goal	Playback automation	Structured research
Task format	Real-time request	File-based mission
Output	Initiated playback	Artifact files + report
Latency	Low (interactive)	Batch (background)
Tools	Streaming platforms, device APIs, VLC, Cast	Search adapters, transcript APIs
Lifecycle	Per-request	Per-mission

Los dos agents no comparten memoria. El Media Agent no tiene persistent memory layer; el Research Worker tiene su propia workspace memory para mission artifacts.

Configuration

El Media Agent se configura a través de la per-agent configuration del framework. La configuration declara:

Las streaming platforms a consultar.
El default target device por backend.
El host, port y password de VLC (si RC está habilitado).
El default transcoding profile.
El fallback behavior cuando el backend preferido no está disponible.

Los cambios de configuration los hace el Coordinator y requieren autorización explícita del usuario.

Failure modes

Failure	Result
Title not found in any catalog	Devolver un "no match" estructurado al Coordinator.
Stream source unavailable	Probar con la siguiente mejor source; si no queda ninguna, devolver un "no source".
Target device unreachable	Devolver un "device offline" con un hint para revisar el device.
Cast command rejected by the device	Devolver un "rejected" con el error message del device.
VLC RC connection refused	Verificar que VLC corre con RC habilitado; si no, caer a direct spawn.
VLC fails to start (missing binary)	Devolver un "backend unavailable" con el install hint.
Codec not supported by target	Cambiar a un transcoding profile; si falla, devolver un error "codec".
Playback command rejected by the device	Devolver un "rejected" con el error message del device.

Todos los failure modes se loguean. El Coordinator surface el resultado al usuario con el failure context original preservado.

Future work

Media Organizer — gestión automatizada de la media library local.
Plex/Radarr Integration Hub — conexión entre media discovery y media server local.
Stremio Addon Server — Stremio addon custom para sources curadas por el lab.
Expanded platform support — servicios de streaming y device targets adicionales.
VLC mosaic profiles — profiles multi-output preconfigurados para escenarios comunes (fiesta, multi-room, audio-only).