Media Tools

Propósito

El media toolkit es la colección del lab de 9 herramientas para automatización de entretenimiento. Es una aplicación concreta del patrón de Tooling Layer a un dominio específico: búsqueda de películas/series, descubrimiento de subtítulos, detección de audio doblado, extracción de metadatos técnicos y reproducción multi-backend.

Esta página documenta el contrato de cada herramienta, el pipeline end-to-end y los patrones de composición. El formato TOOL.md por herramienta está en Tool Spec. La estructura estándar de herramienta está en Tool Structure. El esquema tools.json está en Tool Registry. El Media Lab Server está en Media Lab Server.

Inventario de herramientas

Las herramientas se dividen en cuatro layers: search, metadata, playback, dispatcher y generation. El Media Agent compone los layers en un pipeline end-to-end.

Quick reference: pipeline de media end-to-end

El flujo típico de request del Media Agent:

Una request completa corre en 3 a 7 segundos (search + selection + backend dispatch) sin transcoding; con transcoding, 1-3 minutos.

torrent-finder

Herramienta CLI. Busca fuentes públicas de torrent para una película o serie por título, año, calidad o codec.

Activación

Activar cuando:

• El usuario pide fuentes de torrent para un título específico.
• Una request de media requiere identificación de fuente.
• El Media Agent necesita un release candidato.

Inputs

Command shape

python3 -m torrent_finder search \
  --title "Snatch" \
  --year 2000 \
  --quality 2160p \
  --codec x265 \
  --limit 20

Outputs

{
  "title": "Snatch",
  "year": 2000,
  "count": 12,
  "sources": [
    {
      "name": "Snatch.2000.UHD.BluRay.2160p.x265.HDR.DV-GROUP",
      "size_bytes": 52428800000,
      "quality": "2160p",
      "codec": "x265",
      "url": "magnet:?xt=urn:btih:...",
      "seeders": 312,
      "leechers": 28,
      "uploaded_at": "2025-12-04"
    }
  ]
}

Sources y sus características

La configuración por defecto consulta tres fuentes; cada una tiene sus quirks.

La herramienta normaliza la respuesta entre fuentes para que el JSON de salida tenga una única forma.

Filtros y detección de calidad

La herramienta corre cada candidato por un filtro multi-paso:

1. Normalización de título. Strip el año, la resolución, el codec, el grupo y cualquier carácter especial.
2. Match de calidad. Compara el tag de calidad del release con la calidad pedida. Un release 1080p no pasa un filtro 4K.
3. Match de codec. Compara el tag de codec del release con el codec pedido. h265 y hevc son equivalentes.
4. Sanity check de tamaño. Un release 4K por debajo de 1 GB se rechaza como probablemente CAM/TS.
5. Umbral de seeders. Un release con 0 seeders se rechaza.

Failure modes

Configuración

Dependencies

• requests>=2.28: cliente HTTP.
• beautifulsoup4>=4.11: parsing de HTML.
• lxml>=4.9: parser de XML/HTML.
• pydantic>=2.0: validación del esquema de salida.

subtitle-finder

Herramienta CLI. Busca sitios públicos de subtítulos para una película o serie.

Activación

• El usuario pide subtítulos para un título específico.
• Una request de media requiere descubrimiento de subtítulos.

Inputs

Command shape

python3 -m subtitle_finder search \
  --title "Snatch" \
  --year 2000 \
  --language es

Outputs

{
  "title": "Snatch",
  "year": 2000,
  "language": "es",
  "count": 8,
  "subtitles": [
    {
      "source": "subscene",
      "release_name": "Snatch.2000.1080p.BluRay.x264",
      "url": "https://...",
      "rating": 9.4,
      "downloads": 24102
    }
  ]
}

Failure modes

dubbed-finder

Herramienta CLI. Detecta releases que tienen audio doblado en un idioma dado.

Activación

• El usuario pide una versión doblada de un título.
• Una request de media requiere información del idioma del audio.

Inputs

Outputs

{
  "title": "Snatch",
  "year": 2000,
  "language": "es",
  "count": 3,
  "releases": [
    {
      "release_name": "Snatch.2000.1080p.BluRay.x264.Spanish",
      "audio_languages": ["en", "es"],
      "url": "magnet:?xt=urn:btih:..."
    }
  ]
}

Cómo detecta el audio doblado

La herramienta usa dos señales:

1. Release name. Strings como Spanish, Castellano, VOSE, Dual-Audio, Multi son señales fuertes.
2. Cross-check con media-info. Cuando el usuario tiene un fichero local, media-info devuelve los idiomas de las pistas de audio; la herramienta usa eso como ground truth.

El cross-check con media-info de la herramienta es la señal más fiable; el release name es un hint.

media-info

Herramienta CLI. Extrae metadatos técnicos de vídeo a través de ffprobe o mediainfo.

Activación

• El usuario pide info técnica de un fichero de vídeo.
• Una request de media necesita resolución, codec o duración.
• El Media Agent necesita verificar que el fichero descargado matchea la calidad pedida.

Inputs

Command shape

python3 -m media_info info --path "/Volumes/Media/Snatch.2000.mkv"

Outputs (full)

{
  "path": "/Volumes/Media/Snatch.2000.mkv",
  "format": "matroska,webm",
  "duration_s": 7342.5,
  "size_bytes": 52428800000,
  "video": {
    "codec": "hevc",
    "width": 3840,
    "height": 2160,
    "fps": 23.976,
    "bitrate_kbps": 58000
  },
  "audio": [
    {
      "codec": "truehd",
      "language": "eng",
      "channels": 8,
      "bitrate_kbps": 4800
    },
    {
      "codec": "ac3",
      "language": "spa",
      "channels": 6,
      "bitrate_kbps": 640
    }
  ],
  "subtitles": [
    {"language": "eng", "format": "PGS"},
    {"language": "spa", "format": "PGS"}
  ]
}

Failure modes

media-organizer (planned)

Herramienta CLI. Organiza el media descargado en una estructura de librería basada en metadatos. Status: planned; la implementación seguirá la CLI Python tool template.

Inputs planeados:

• source: ruta al directorio fuente.
• library: ruta a la raíz de la librería.
• strategy: movie-tmdb | series-tvdb | flat.

Outputs planeados:

{
  "moved": 12,
  "skipped": 1,
  "errors": [
    {"source": "...", "reason": "..."}
  ]
}

chromecast

Herramienta CLI. Descubre dispositivos Cast en la LAN y controla la reproducción en un dispositivo seleccionado.

Activación

• El usuario quiere reproducir un cloud stream en una TV.
• El selector de backend del Media Agent escoge Chromecast para una request.

Protocolo

La herramienta usa el protocolo Cast de Google. El discovery es mDNS (_googlecast._tcp.local.). El control es HTTPS en el puerto devuelto por el registro mDNS (típicamente 8009).

Acciones

Command shape

# Discover
python3 -m chromecast discover
 
# Play
python3 -m chromecast play \
  --device "Living Room TV" \
  --url "https://example.com/stream.m3u8" \
  --content_type "application/x-mpegURL" \
  --title "Snatch"

Outputs

Para discover:

{
  "devices": [
    {"name": "Living Room TV", "host": "192.168.1.42", "port": 8009, "model": "NVIDIA Shield TV"}
  ]
}

Para play:

{
  "device": "Living Room TV",
  "status": "playing",
  "media_session_id": "abc123"
}

Failure modes

vlc

Herramienta CLI. Lanza y controla VLC local o en un host remoto sobre la interfaz RC (TCP) o HTTP.

Activación

• La fuente es un fichero local y el usuario quiere reproducirlo en un dispositivo remoto.
• La fuente es un stream de red que necesita transcoding o enviar a un dispositivo no-Cast.
• El usuario pide VLC explícitamente.
• El selector de backend del Media Agent escoge VLC para una request (p. ej., cuando se requiere transcoding).

Protocolo

VLC se controla a través de su interfaz RC (TCP) o HTTP. El puerto por defecto para RC es 4212. El puerto por defecto para HTTP es 8080. La herramienta soporta ambos.

Acciones

Command shape

# Local play
python3 -m vlc play --host localhost --source /Volumes/Media/Snatch.2000.mkv
 
# Remote play
python3 -m vlc play --host kitchen --source /Volumes/Media/Snatch.2000.mkv
 
# Transcode a HLS para clientes de bajo ancho de banda
python3 -m vlc transcode \
  --host localhost \
  --source /Volumes/Media/Snatch.2000.mkv \
  --profile hls-1080p

Outputs

Para play:

{
  "host": "localhost",
  "status": "started",
  "pid": 12345
}

Para transcode:

{
  "host": "localhost",
  "sout_url": "http://localhost:8080/stream.m3u8",
  "profile": "hls-1080p",
  "status": "started"
}

Profiles

El argumento profile es un perfil sout de VLC con nombre. Profiles built-in:

Los profiles custom se pueden añadir en la configuración.

Failure modes

Configuración

media-playback

Dispatcher de alto nivel. Selecciona el backend de playback correcto (Chromecast, VLC o direct) para una fuente y target dados, y luego invoca la herramienta apropiada. El flujo de request del Media Agent llama a esta herramienta en lugar de llamar directamente a chromecast, vlc o al direct player.

Algoritmo de selección de backend

El dispatcher usa las siguientes reglas en orden:

1. Backend explícito. Si el caller pasó backend explícitamente, usarlo.
2. Tipo de dispositivo target. Si el target es un dispositivo Cast (el nombre matchea un Cast descubierto), usar chromecast.
3. Tipo de fuente y target. Si la fuente es un fichero local y el target es un host VLC con nombre, usar vlc.
4. Tipo de fuente y transcoding. Si la fuente es un fichero local y se requiere transcoding, usar vlc.
5. La fuente es un stream de red. Si la fuente es un stream HLS/DASH y el target es un dispositivo Cast, usar chromecast.
6. Default. Si ninguno de los anteriores matchea, usar direct (lanzar el reproductor por defecto del SO).

Inputs

Outputs

{
  "backend": "chromecast",
  "device": "Living Room TV",
  "status": "playing",
  "session_id": "abc123"
}

Direct player

El direct player lanza el reproductor de media por defecto del SO:

• macOS: open <path> u open <url>.
• Linux: xdg-open <path> o xdg-open <url>.

El direct player es el backend más simple; no tiene controles ni tracking de estado.

media-lab-server

Un servidor HTTP local que genera imágenes y música. No es una herramienta CLI sino un servicio HTTP. Documentado en detalle en Media Lab Server.

Quick reference:

• Escucha en 127.0.0.1:8765.
• Expone /api/image y /api/music.
• Web UI en http://127.0.0.1:8765/.

Coordinación de herramientas

Las herramientas de media se componen en un pipeline. El Media Agent corre el pipeline.

Etapas del pipeline

1. Discovery — torrent-finder produce una lista de candidatos.
2. Selection — el usuario (o el agente, por defecto) escoge un candidato.
3. Descubrimiento de subtítulos (opcional) — subtitle-finder produce candidatos de subtítulos.
4. Descubrimiento de audio doblado (opcional) — dubbed-finder encuentra releases con el idioma pedido.
5. Metadatos (opcional) — media-info extrae info técnica del fichero local.
6. Selección de backend — media-playback escoge un backend.
7. Dispatch — media-playback invoca la herramienta de backend elegida.
8. Playback — el usuario ve/escucha.

El pipeline es la base del workflow del Media Agent.

Sequential vs parallel

Las etapas 1, 3 y 4 pueden correr en paralelo cuando los candidatos de búsqueda son independientes. Las etapas 5 y 7 deben correr secuencialmente porque dependen de una única fuente. La etapa 6 debe correr tras las etapas 1-5 porque necesita la fuente seleccionada.

Una run paralela típica:

• torrent-finder (search sources) — 5-15 s
• subtitle-finder (find subs) — 2-5 s — parallel
• dubbed-finder (find dubbed) — 2-5 s — parallel
• media-info (verify local file) — 1-2 s — solo cuando el fichero ya está descargado

Caché

Las herramientas cachean sus resultados:

• torrent-finder cachea los resultados de búsqueda en un fichero local (~/.cache/torrent-finder/) durante 1 hora.
• subtitle-finder cachea durante 1 hora.
• media-info cachea el resultado por fichero indefinidamente (el mtime del fichero es la clave de caché).

La caché reduce trabajo duplicado cuando el usuario vuelve a un mismo título.

Recovery de errores

El pipeline es resiliente: una etapa que falla no aborta el pipeline a menos que el usuario requiera su salida. Por ejemplo, si subtitle-finder falla, el usuario puede reproducir el release sin subtítulos igualmente.

El Media Agent surface el error al usuario y continúa con la siguiente etapa.

Ejemplos de entradas del registry

Las herramientas de media se registran en tools.json. Entradas reales:

{
  "version": "1.0.0",
  "tools": [
    {
      "name": "torrent-finder",
      "description": "Search torrent sources for movies and series",
      "location": "tools/torrent-finder/main.py",
      "status": "ready",
      "capabilities": ["search", "open"],
      "tags": ["media", "search", "torrent", "movies", "series"]
    },
    {
      "name": "chromecast",
      "description": "Discover and control Cast devices on the LAN",
      "location": "tools/chromecast/main.py",
      "status": "ready",
      "capabilities": ["discover", "play", "pause", "resume", "stop", "status", "volume"],
      "tags": ["media", "playback", "chromecast", "cast", "lan"]
    },
    {
      "name": "vlc",
      "description": "Spawn and control VLC locally or on a remote host",
      "location": "tools/vlc/main.py",
      "status": "ready",
      "capabilities": ["play", "enqueue", "pause", "resume", "stop", "status", "transcode", "duplicate", "quit"],
      "tags": ["media", "playback", "vlc", "local", "network", "transcode", "headless"]
    },
    {
      "name": "media-playback",
      "description": "High-level dispatcher that selects the right playback backend",
      "location": "tools/media-playback/main.py",
      "status": "ready",
      "capabilities": ["play"],
      "tags": ["media", "playback", "dispatcher"]
    }
  ]
}

Los tags los usa el skill loader para activar la herramienta correcta cuando aparece un topic relevante en una request.

Ver también

• Tooling Layer
• Tool Structure
• Tool Spec
• Tool Registry
• Media Lab Server
• Media Agent
• Media Playback