Communitygithub.com

notque/vexjoy-agent

Pipeline de edición de video: cortar metraje, ensamblar clips mediante FFmpeg y Remotion.

¿Qué es vexjoy-agent?

Esta habilidad implementa un pipeline de 6 capas para la edición de video, 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. Es útil para desarrolladores y agentes de IA que necesitan automatizar flujos de trabajo de edición de video complejos, desde la captura de metraje hasta la composición y generación de activos. Soporta plataformas como FFmpeg, Remotion, ElevenLabs y fal.ai, y el pipeline incluye fases de captura, estructuración con IA, cortes con FFmpeg, composición con Remotion, generación de activos y pulido final. El flujo de trabajo se basa en un archivo EDL (`cuts.txt`) que actúa como contrato entre fases, garantizando reproducibilidad y revisión.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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.

CapaNombreMecanismoHerramienta Principal
1CAPTURAInventario de metraje fuenteBash + Glob
2ESTRUCTURA IATranscripción a EDLJuicio del LLM
3CORTES FFMPEGEDL a archivos de segmentoFFmpeg (determinista)
4COMPOSICIÓN REMOTIONSegmentos a composición TSXRemotion + TypeScript
5GENERACIÓN IARellenar vacíos con activos generadosElevenLabs / fal.ai (condicional)
6PULIDO FINALCapa de gusto humanoHumano + NLE

Referencias Detalladas

SeñalCargaContenido
Comandos de shell para cada fase, comprobaciones de puertareferences/phase-commands.mdBloques de comando completos para las Fases 1-6
Recetas FFmpeg: corte, concatenación, proxy, detecciónreferences/ffmpeg-commands.mdExtracción de marcas de tiempo, corte por lotes, normalización de audio, detección de escena/silencio
Andamio de composición Remotionreferences/remotion-scaffold.mdPlantilla de composición TSX, comando de renderizado, patrones de reutilización
Pipeline de imagen a videoreferences/image-to-video.mdFlujo de trabajo de validación, preparación, codificación y verificación
Gráficos de filtro FFmpeg para visualizaciónreferences/ffmpeg-filters.mdEscalar/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

ErrorCausaSolución
"No such file or directory" en fuenteLa ruta en cuts.txt no coincide con el nombre del archivoEjecutar cat source-inventory.txt. Entrecomillar rutas con espacios.
FFmpeg "Invalid option" o errores de codecCódec no disponible o error de sintaxis de bandera`ffmpeg -codecs
Remotion "Could not find composition"ID de composición no coincideVerificar src/index.ts para ID registrado. Coincidir exactamente en el comando de renderizado.
Segmentos concatenados en orden incorrectoEl glob de shell ordena alfabéticamente, no por EDLGenerar concat-list.txt a partir del orden de cuts.txt, no del glob.
ElevenLabs 401ELEVENLABS_API_KEY no configuradaexport ELEVENLABS_API_KEY=tu_clave antes de la Fase 5.
Sin archivo .vtt de extracción de transcripciónEl video no tiene subtítulos en el idioma solicitadoyt-dlp --list-subs '<URL>' y elegir un idioma disponible.

Skills relacionados