Voidscape — Enseñando a agentes IA a ver video
Un agente de codificación con IA puede leer imágenes y PDFs — no video. Voidscape descompone cualquier video en frames más transcripción, y cotiza todo el trabajo antes de gastar un centavo o un token.
Resumen
Voidscape es una skill open-source (MIT) de Claude Code / Codex que da a agentes IA comprensión genuina de video: apúntala a un archivo local o URL (YouTube, Loom, Vimeo…) y extrae frames para la pista visual y transcripción para la pista de audio — las dos cosas que un agente puede consumir realmente. Su feature definitoria es la puerta de costo: un pipeline probe → estimate → run que cotiza todo el trabajo (dólares de transcripción y costo de tokens del agente) por adelantado, usa transcripción local gratuita por defecto con faster-whisper, y solo toca backends cloud de pago tras aprobación explícita. El motor es un CLI Python de 1,300 líneas construido sobre la stdlib, con un protocolo opcional legible por máquina (`manifest`, `--envelope`, códigos de salida determinísticos) añadido para agentes que lo llaman. La landing page pública está en vivo en https://rikepilb.github.io/void-scape/.
El problema
Los agentes fingen comprensión de video leyendo títulos y comentarios. Ver de verdad cuesta dinero real — los frames dominan el gasto en tokens del agente, y la transcripción cloud factura por minuto — así una implementación naive sorprende a usuarios con la factura después. El problema de diseño fue hacer la comprensión de video real y pre-aprobada: nunca gastar antes de mostrar el precio, y nunca dejar que el audio salga de la máquina sin consentimiento explícito.
Preguntas abordadas
- 01
¿Cuál es el camino más barato y honesto a una transcripción — y qué tan seguido es gratis?
- 02
¿Puede una skill servir múltiples harnesses de agente (Claude Code, Codex, Gemini CLI, Copilot CLI) desde una sola instalación?
- 03
¿La skill supera mediblemente a un agente improvisando con ffmpeg por su cuenta?
- 04
¿Qué pasa cuando un agente de codificación extiende el mismo codebase meses después — el diseño original resiste una revisión adversarial real?
Metodología
Probe → Estimate → Run, con puerta de costo
probe inspecciona la entrada (duración, resolución, audio, subtítulos existentes); estimate computa el costo completo — dólares de transcripción por backend y gasto proyectado de tokens del agente por conteo de frames — antes de cualquier trabajo; run solo ejecuta tras aprobación del usuario (o umbral cero dólares). Nueve paths de transcripción ordenados más barato-y-privado primero: subtítulos sidecar, captions de URL, faster-whisper y trx local (todos gratis) antes de Groq, OpenAI, OpenRouter y Gemini.
Un motor solo stdlib
Los paths de API de pago usan requests multipart hechos a mano sobre urllib — sin SDKs — así los paths gratuitos nunca pagan costo de import y una dependencia opcional faltante nunca puede romper probe o estimate. 110 casos pytest en 17 archivos fijan chunking, deduplicación, estimación de costo, extracción de frames y hardening (incluyendo un fix anchor contra spoofing de dominios parecidos y una suite de tests a nivel subprocess para el contrato del CLI de agente).
Diseño de skill driven por evals
La skill se benchmarkó con un loop de eval contra baseline sin skill: con la skill cargada, el agente pasó 14 de 15 assertions (93.3%) en escenarios de resumen visual, comprensión de audio y puerta de costo, versus 66.7% baseline. Un script de instalación la conecta a cuatro harnesses: Claude Code, Codex, Gemini CLI y Copilot CLI.
Build Week: protocolos de agente, revisión adversarial, seguridad honesta
Extendida para OpenAI Build Week 2026 con Codex + GPT-5.6: tiers de transcripción local adaptativos, contabilidad de costo nativa GPT-5.6 por patches de 32×32, y un protocolo CLI opcional orientado a agentes (`manifest`, `--envelope`/`--compact`, una taxonomía determinística de códigos de salida con metadata de reintentabilidad). Una revisión de código adversarial contra la nueva puerta de costo/consentimiento reveló 9 hallazgos; los 6 defectos reales se corrigieron con tests de regresión antes de lanzar — incluyendo uno detectado solo al correr de verdad los comandos documentados, no por unit tests. Un escáner de seguridad estático marcó el flujo de datos intencional env-key-a-API-cloud como CRITICAL; en vez de ocultarlo, el hallazgo se divulga y explica en un `SECURITY.md` que el propio reporte del escáner verifica.
Resultados clave
Hallazgos clave
La transparencia de costo es una feature UX para agentes: mostrar el precio antes del trabajo convierte "la IA me subió la factura" en un sí/no informado.
El orden local-first (captions → Whisper on-device → APIs de pago) hace del path gratuito el default — la mayoría de videos nunca cuestan un centavo leer.
Los evals superan las vibes para diseño de skills: un gap medido 93.3%-vs-66.7% es lo que separa "la skill ayuda" de esperar que lo haga.
La revisión adversarial más correr de verdad los comandos documentados detectó una regresión real que los unit tests pasaron por alto: un fix en otra parte del mismo diff cambió silenciosamente lo que demostraba el propio ejemplo de prueba-de-privacidad del README.
Conclusión
Voidscape es la pieza open-source más completa de este portfolio: licencia MIT con docs de contribución, plantillas de issues, GIF demo, una landing page en vivo en GitHub Pages (https://rikepilb.github.io/void-scape/), 60+ commits de iteración real, y una mejora de eval medida. También es honesto sobre escala — el set de eval es pequeño e itera — pero la forma es lo que se parece a tooling de agente en producción: cotizado, testeado, local-first, multi-harness, y revisado como software real en vez de lanzado por vibes. Enviado a OpenAI Build Week 2026 (track Developer Tools).
Galería
