claude-video-es

Da a Claude la capacidad de ver cualquier vídeo. En castellano.

Pegas una URL (YouTube, Loom, TikTok, X, Vimeo, Instagram… cualquier cosa que soporte yt-dlp) o una ruta local. Claude descarga el vídeo, extrae frames a un ritmo auto-escalado, saca la transcripción con timestamps (subtítulos nativos primero, Whisper como fallback) y responde a tu pregunta como alguien que lo hubiera visto.

/watch https://youtu.be/dQw4w9WgXcQ que pasa en el segundo 30?

Versión castellana del proyecto claude-video de Bradley Bonanno. Misma funcionalidad, documentación traducida y mensajes de la skill en castellano. MIT License — ver CREDITS.md.

---

Por qué existe

Claude lee páginas web, ejecuta scripts, navega repos. Lo que no puede hacer de fábrica es ver un vídeo. Pegas un link de YouTube y solo puede adivinar por el título o tirar de una transcripción que se pierde el 90% de lo que sale en pantalla.

Con /watch pegas una URL o una ruta local, haces tu pregunta, y Claude:

1. Descarga el vídeo
2. Extrae frames a fps auto-escalado
3. Saca transcripción con timestamps (subtítulos gratis cuando los hay, Whisper como fallback)
4. Lee cada frame como imagen

Cuando responde, ya vio los frames y escuchó el audio.

Para qué la usa la gente

Analizar el contenido de otros. /watch https://youtu.be/<video-viral> que hook usaron al abrir? Claude mira los primeros frames, lee la apertura de la transcripción y desglosa la estructura. Lo mismo para creatividades de ads, lanzamientos de competencia, intros de podcast, cualquier cosa donde el cómo importa tanto como el qué.

Diagnosticar un bug a partir de un vídeo. Alguien te manda una grabación de pantalla de algo roto. /watch bug.mov que esta fallando? Claude ve la grabación, encuentra el frame donde aparece el problema, describe lo que hay en pantalla y muchas veces detecta la causa sin que abras el archivo.

Resumir un vídeo. /watch https://youtu.be/<video-largo> resume esto. Saca estructura, momentos clave, lo que se dijo y lo que se mostró. Más rápido que verlo a 2x.

Cómo funciona

1. Pegas un vídeo y una pregunta. URL (lo que soporte yt-dlp) o ruta local (.mp4, .mov, .mkv, .webm).
2. yt-dlp lo descarga. Para URLs, en un directorio de trabajo temporal. Para archivos locales, no descarga — solo los inspecciona.
3. ffmpeg extrae frames a fps auto-escalado. El presupuesto de frames es consciente de la duración: ≤30s saca ~30 frames, 30-60s ~40, 1-3min ~60, 3-10min ~80, más largo 100 espaciados. Topes duros: 2 fps, 100 frames. JPEGs a 512px de ancho por defecto — sube con --resolution 1024 si Claude necesita leer texto en pantalla.
4. La transcripción viene de uno de dos sitios. Primero: yt-dlp saca subtítulos nativos (manuales o auto-generados) del propio sitio. Gratis e instantáneo. Fallback: extrae un audio mono 16 kHz y lo manda a Whisper — whisper-large-v3 de Groq (preferido — más barato y rápido) o whisper-1 de OpenAI.
5. Frames + transcripción se le pasan a Claude. El script imprime las rutas de cada frame con marcadores t=MM:SS y la transcripción con timestamps. Claude Reads cada frame en paralelo — los JPEGs se renderizan directamente como imágenes en su contexto.
6. Claude responde basándose en lo que está realmente en pantalla y en el audio. No "según la descripción" ni "según el título". Vio los frames. Escuchó la transcripción. Responde como alguien que vio el vídeo.
7. Limpieza. El script imprime el directorio de trabajo al final. Si no vas a hacer follow-ups, Claude lo borra.

Presupuesto de frames — por qué importa

El coste en tokens lo dominan los frames. Cada frame es una imagen; los tokens de imagen suben rápido. La lógica auto-fps existe para que no quemes tu contexto en un escaneo disperso de un vídeo de 30 minutos que se habría respondido mejor con una ventana enfocada de 30 segundos.

Duración	Presupuesto por defecto	Qué obtienes
≤30 s	~30 frames	Denso — prácticamente cada momento clave
30 s - 1 min	~40 frames	Aún denso
1 - 3 min	~60 frames	Cómodo
3 - 10 min	~80 frames	Disperso pero usable
> 10 min	100 frames	Aviso "sparse scan" — re-ejecuta enfocado

Cuando le des un momento concreto ("sobre el 2:30", "los últimos 30 segundos", "del 0:45 al 1:00"), pasa --start / --end. El modo enfocado tiene presupuestos más densos por segundo, capado a 2 fps. Mucho más útil que un barrido disperso del vídeo entero.

Instalación

Entorno	Instalación
Claude Code	/plugin marketplace add victorperez22/claude-video-es luego /plugin install watch@claude-video-es
claude.ai (web)	Descarga watch.skill → Settings → Capabilities → Skills → +
Codex	git clone https://github.com/victorperez22/claude-video-es.git ~/.codex/skills/watch
Manual / dev	git clone https://github.com/victorperez22/claude-video-es.git ~/.claude/skills/watch

Claude Code

/plugin marketplace add victorperez22/claude-video-es
/plugin install watch@claude-video-es

Actualiza con /plugin update watch@claude-video-es.

claude.ai (web)

1. Descarga watch.skill de la última release.
2. Ve a Settings → Capabilities → Skills.
3. Haz click en + y suelta el archivo.

Activa "Code execution and file creation" en Capabilities primero — la skill llama a ffmpeg y yt-dlp, así que sin eso no arranca.

Codex

git clone https://github.com/victorperez22/claude-video-es.git ~/.codex/skills/watch

Manual (developer)

git clone https://github.com/victorperez22/claude-video-es.git ~/.claude/skills/watch

Primer arranque

En la primera llamada a /watch, la skill ejecuta scripts/setup.py --check. Si ffmpeg o yt-dlp no están en tu PATH, o si no hay clave de Whisper configurada, te guía:

• macOS — auto-ejecuta brew install ffmpeg yt-dlp.
• Linux — imprime los comandos exactos de apt / dnf / pipx.
• Windows — imprime los comandos de winget / pip.
• API key — crea ~/.config/watch/.env (modo 0600) con placeholders comentados para GROQ_API_KEY (preferida) y OPENAI_API_KEY.

Tras el setup, el preflight es silencioso y /watch simplemente funciona. El check es un lookup de <100ms, así que no ralentiza las siguientes ejecuciones.

Trae tus claves

Los subtítulos cubren la mayoría de vídeos públicos gratis. El fallback de Whisper solo se activa cuando el vídeo realmente no tiene pista de subtítulos — típicamente archivos locales, TikToks, algunos Vimeos y subidas de YouTube ocasionales sin subtítulos.

Capacidad	Lo que necesitas	Coste
Descarga + subtítulos nativos	yt-dlp + ffmpeg	Gratis
Whisper fallback (preferido)	Groq API key — whisper-large-v3	Barato, rápido
Whisper fallback (alternativo)	OpenAI API key — whisper-1	Precio estándar
Desactivar Whisper del todo	--no-whisper	Gratis, solo frames si no hay subs

Uso

/watch https://youtu.be/dQw4w9WgXcQ que pasa en el segundo 30?
/watch https://www.tiktok.com/@user/video/123 resume esto
/watch ~/Movies/screen-recording.mp4 cuando se rompe la UI?
/watch https://vimeo.com/123 que herramientas menciona?

Enfocado en una sección concreta — presupuesto de frames más denso, menor coste de tokens:

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60
/watch "$URL" --start 1:12:00            # desde 1h12m hasta el final

Otros parámetros (se pasan a scripts/watch.py):

• --max-frames N — baja el límite de frames para un presupuesto de tokens más ajustado.
• --resolution W — sube el ancho del frame a 1024 px cuando Claude necesita leer texto en pantalla (slides, terminales, código).
• --fps F — fuerza un fps concreto (siempre capado a 2 fps).
• --whisper groq|openai — fuerza un backend Whisper concreto.
• --no-whisper — desactiva la transcripción del todo; solo frames.
• --out-dir DIR — guarda los archivos de trabajo en una ubicación concreta (por defecto: tmp auto-generado).

Límites

• Mejor precisión: por debajo de 10 minutos. A partir de ahí el script imprime un aviso "sparse scan" — re-ejecuta enfocado en la parte que te interesa con --start/--end.
• Topes duros: 2 fps, 100 frames. El número de frames domina el coste en tokens; el script lo fuerza incluso cuando el cálculo de auto-fps daría más.
• Límite de subida de Whisper: 25 MB. A mono 16 kHz son unos 50 minutos de audio. Vídeos más largos necesitan subtítulos o --start/--end a una ventana menor.
• Sin plataformas privadas. La skill no inicia sesión en nada. Solo URLs públicas y archivos locales. Si yt-dlp no llega sin auth, /watch tampoco.

Estructura

.
├── SKILL.md                 # contrato de la skill — cargado por las tres surfaces
├── scripts/
│   ├── watch.py             # punto de entrada — orquesta descarga → frames → transcripción
│   ├── download.py          # wrapper de yt-dlp
│   ├── frames.py            # extracción ffmpeg + lógica auto-fps
│   ├── transcribe.py        # parseo VTT + dedupe + orquestación Whisper
│   ├── whisper.py           # clientes Groq / OpenAI (stdlib puro)
│   ├── setup.py             # preflight + instalador
│   └── build-skill.sh       # build dist/watch.skill para subir a claude.ai
├── hooks/                   # SessionStart status hook (solo Claude Code)
├── .claude-plugin/          # plugin.json + marketplace.json (Claude Code)
├── .codex-plugin/           # packaging Codex
└── .github/workflows/       # release.yml — auto-build de watch.skill al pushear tag

Desarrollo

# Build del bundle para subir a claude.ai:
bash scripts/build-skill.sh      # → dist/watch.skill

Releases: tag vX.Y.Z, push del tag. El workflow construye dist/watch.skill y lo adjunta al release de GitHub.

Ver CHANGELOG.md para el historial de versiones.

Open source

MIT license. Construido sobre yt-dlp, ffmpeg, y la herramienta multimodal Read de Claude. Transcripción Whisper vía Groq o OpenAI.

Versión castellana mantenida por Victor Pérez — proyecto original bradautomates/claude-video de Bradley Bonanno.

---

github.com/victorperez22/claude-video-es · LICENSE · CREDITS