Habilidad de Edición de Video
Resumen
Esta habilidad implementa un pipeline de 6 capas donde la IA maneja tareas de juicio (qué conservar, qué cortar, selección de momentos destacados) y FFmpeg/Remotion manejan la ejecución mecánica de forma determinista.
| Capa | Nombre | Mecanismo | Herramienta Principal |
|---|---|---|---|
| 1 | CAPTURA | Inventario de metraje fuente | Bash + Glob |
| 2 | ESTRUCTURA IA | Transcripción a EDL | Juicio del LLM |
| 3 | CORTES FFMPEG | EDL a archivos de segmento | FFmpeg (determinista) |
| 4 | COMPOSICIÓN REMOTION | Segmentos a composición TSX | Remotion + TypeScript |
| 5 | GENERACIÓN IA | Rellenar vacíos con activos generados | ElevenLabs / fal.ai (condicional) |
| 6 | PULIDO FINAL | Capa de gusto humano | Humano + NLE |
Referencias Detalladas
| Señal | Carga | Contenido |
|---|---|---|
| Comandos de shell para cada fase, comprobaciones de puerta | references/phase-commands.md | Bloques de comando completos para las Fases 1-6 |
| Recetas FFmpeg: corte, concatenación, proxy, detección | references/ffmpeg-commands.md | Extracción de marcas de tiempo, corte por lotes, normalización de audio, detección de escena/silencio |
| Andamio de composición Remotion | references/remotion-scaffold.md | Plantilla de composición TSX, comando de renderizado, patrones de reutilización |
| Pipeline de imagen a video | references/image-to-video.md | Flujo de trabajo de validación, preparación, codificación y verificación |
| Gráficos de filtro FFmpeg para visualización | references/ffmpeg-filters.md | Escalar/rellenar, showwaves, showspectrum, superposición, gráficos de filtro completos |
Instrucciones
Prevuelo (Ejecutar antes de la Fase 1)
Requisitos estrictos (BLOQUEAR si faltan): ffmpeg (todas las fases), node (Remotion / npx).
Requisitos blandos (ADVERTIR si faltan): remotion (solo requerido para la Fase 4).
which ffmpeg >/dev/null 2>&1 || { echo "ERROR: ffmpeg no encontrado. Instalar: brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "ERROR: node no encontrado. Instalar: https://nodejs.org o mediante nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "ADVERTENCIA: CLI de remotion no encontrado. Fase 4 no disponible. Instalar: npm install @remotion/cli"
Fase 1: CAPTURA
Objetivo: Inventariar todo el metraje fuente y confirmar que los archivos existen en disco antes de cualquier procesamiento.
Restricción: Los archivos fuente son de solo lectura. Todos los comandos FFmpeg escriben solo en archivos nuevos. Nunca sobrescribir el metraje fuente.
Pasos: localizar archivos fuente (find), inspeccionar cada uno con ffprobe, generar proxies para archivos >10 min (ver references/ffmpeg-commands.md -> Generación de Proxy), crear directorios de trabajo (segments/, assembled/). Bloque de comando completo: references/phase-commands.md -> Fase 1.
Puerta: Archivos fuente confirmados en disco. Lista de archivos escrita en source-inventory.txt. Proceder solo cuando la puerta pase.
Fase 2: ESTRUCTURA IA
Objetivo: Analizar el contenido y producir un EDL escrito (cuts.txt) que impulse todos los cortes posteriores.
Restricción: cuts.txt es el contrato. El archivo EDL es la única fuente de verdad para las fases posteriores. No editar manualmente los comandos FFmpeg; generarlos a partir del EDL.
Restricción: Antes de escribir el EDL manualmente, ejecutar la detección de escena/silencio de FFmpeg. La salida de la detección informa el juicio, no lo reemplaza.
Pasos: transcribir con whisper/AssemblyAI, ejecutar detección de escena/silencio, aplicar juicio (qué avanza la narrativa, qué es relleno, duración objetivo), escribir cuts.txt en formato EDL TIEMPO_INICIO,TIEMPO_FIN,ETIQUETA, revisar superposiciones y duración total. Bloque de comando completo y ejemplo de formato EDL: references/phase-commands.md -> Fase 2.
Puerta: transcript.txt existe. cuts.txt escrito en disco. Proceder solo cuando ambos archivos existan.
Fase 3: CORTES FFMPEG
Objetivo: Ejecutar el EDL de forma determinista: un corte FFmpeg por segmento en cuts.txt.
Restricción: Cortar por lotes desde el EDL usando un bucle. No crear comandos FFmpeg individuales por corte. Esto asegura reproducibilidad y capacidad de revisión como lista.
Restricción: Siempre generar concat-list.txt a partir del orden de cuts.txt, no de un glob de shell. El glob de shell (segments/*.mp4) ordena alfabéticamente, no por orden EDL.
Pasos: cortar por lotes desde el EDL con un bucle while (libx264/aac, -avoid_negative_ts make_zero), verificar segmentos, generar concat-list.txt en orden EDL, concatenar con -f concat -safe 0 -c copy. Bloque de comando completo: references/phase-commands.md -> Fase 3. Ver también references/ffmpeg-commands.md -> Corte por Lotes.
Puerta: Todos los archivos de segmento existen. assembled/rough-cut.mp4 escrito en disco. Proceder solo cuando la puerta pase.
Fase 4: COMPOSICIÓN REMOTION
Objetivo: Envolver segmentos en una composición TSX de Remotion para superposiciones, títulos o transiciones programáticas.
Cuándo usarla: Solo cuando rough-cut.mp4 requiera elementos programáticos (títulos animados, tercios inferiores, pistas de subtítulos, superposiciones de marca). Si rough-cut.mp4 es suficiente, saltar a la Fase 6.
Restricción: La Capa 4 requiere TypeScript/React. Transferir a typescript-frontend-engineer para el trabajo TSX; regresar a python-general-engineer para la Fase 5 en adelante.
Pasos: inicializar Remotion (npm create video@latest la primera vez; de lo contrario npm install @remotion/cli @remotion/player remotion), preparar composición (ver references/remotion-scaffold.md), renderizar con npx remotion render. Bloque de comando completo: references/phase-commands.md -> Fase 4.
Puerta: assembled/remotion-output.mp4 existe. Proceder solo cuando la puerta pase.
Fase 5: GENERACIÓN IA
Objetivo: Rellenar vacíos genuinos en el material fuente con activos generados, solo cuando sea necesario.
Restricción: Verificar si el metraje existente cubre el vacío antes de generar cualquier cosa. Generar solo lo que no existe.
Árbol de decisión: cortar alrededor del vacío → actualizar cuts.txt y re-ejecutar Fase 3; voz en off → ElevenLabs (autorización requerida); música → fal.ai (delegar a fal-ai-media); b-roll → fal.ai (delegar a fal-ai-media). Ayudante Python de ElevenLabs, patrón de autorización y flujo de guardado en disco: references/phase-commands.md -> Fase 5.
Puerta: Todos los activos generados requeridos guardados en el directorio assets/ antes de proceder.
Fase 6: PULIDO FINAL
Objetivo: Entregar la salida ensamblada y transferir el trabajo de capa de gusto al humano.
Restricción: La Capa 6 es territorio humano. La habilidad ensambla; el humano finaliza. Los siguientes elementos requieren juicio humano y no deben intentarse programáticamente:
- Calibración de color y coincidencia de color entre clips
- Tiempo de música y ducción de volumen
- Estilo de subtítulos, fuente, posicionamiento
- Tiempo y estilo de transiciones
- Niveles finales de mezcla de audio
Plantilla de transferencia (handoff-notes.txt con lista de fuentes, EDL, ruta de rough-cut, lista de verificación de lo que queda para humano): references/phase-commands.md -> Fase 6.
Puerta: assembled/rough-cut.mp4 (o assembled/remotion-output.mp4) existe. handoff-notes.txt escrito en disco.
Extracción de Transcripción de Video
Extraer la transcripción de un video como párrafos legibles. Preferir subtítulos del subidor; recurrir a los generados automáticamente.
# Ruta 1: subtítulos del subidor (precisos)
yt-dlp --skip-download --write-subs --sub-langs es --sub-format vtt -o '<directorio-trabajo>/%(id)s' '<URL>'
# Ruta 2: generados automáticamente (recurso cuando la ruta 1 no escribe archivo)
yt-dlp --skip-download --write-auto-subs --sub-langs es --sub-format vtt -o '<directorio-trabajo>/%(id)s' '<URL>'
# Limpiar VTT a párrafos
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <directorio-trabajo>/<id>.es.vtt
Opciones: --timestamps para marcadores [mm:ss], --keep-brackets para etiquetas de señal, -o ARCHIVO para salida a archivo. Otros idiomas: cambiar --sub-langs. Listar disponibles: yt-dlp --list-subs '<URL>'.
Manejo de Errores
| Error | Causa | Solución |
|---|---|---|
| "No such file or directory" en fuente | La ruta en cuts.txt no coincide con el nombre del archivo | Ejecutar cat source-inventory.txt. Entrecomillar rutas con espacios. |
| FFmpeg "Invalid option" o errores de codec | Códec no disponible o error de sintaxis de bandera | `ffmpeg -codecs |
| Remotion "Could not find composition" | ID de composición no coincide | Verificar src/index.ts para ID registrado. Coincidir exactamente en el comando de renderizado. |
| Segmentos concatenados en orden incorrecto | El glob de shell ordena alfabéticamente, no por EDL | Generar concat-list.txt a partir del orden de cuts.txt, no del glob. |
| ElevenLabs 401 | ELEVENLABS_API_KEY no configurada | export ELEVENLABS_API_KEY=tu_clave antes de la Fase 5. |
| Sin archivo .vtt de extracción de transcripción | El video no tiene subtítulos en el idioma solicitado | yt-dlp --list-subs '<URL>' y elegir un idioma disponible. |