Communitygithub.com

reel

Herramienta de creación y edición de videos para agentes AI: promocionales, locuciones, videos musicales/letras, fotos + música + voz, recortes de material, primeros planos con zoom, y páginas web con resaltado sincronizado. La entrega debe pasar por reel check → reel deliver y producir un recibo final.

¿Qué es reel?

reel es una herramienta profesional de edición de video diseñada específicamente para que agentes de IA (como Claude Code, Cursor, Codex, etc.) puedan crear y editar videos de alta calidad de manera autónoma. Basada en ffmpeg, permite trabajar con diversos tipos de contenido: videos promocionales, locuciones, videos musicales con letras sincronizadas, presentaciones de fotos con música y voz, edición de material bruto, primeros planos con efecto zoom, y páginas web con resaltado de texto sincronizado con la voz. La herramienta impone un riguroso proceso de entrega: primero se debe escribir un brief y registrarlo, luego se hace una vista previa de audio, se revisa el video final (reel check), se realiza una revisión por parte del usuario (reel scrub, final_watch, final_listen), y finalmente se entrega mediante reel deliver, generando un recibo digital que confirma la finalización. El agente no puede declarar la tarea como 'completada' hasta no obtener ese recibo. Soporta múltiples perfiles de salida (vertical para redes sociales, horizontal, perfiles personalizados), verificación de texto prohibido, sincronización de latidos musicales, y renderizado remoto en GPU si está configurado.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/agent-reel/tree/HEAD/skill

Preguntar en tu IA favorita

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

Documentación

reel — Herramienta de creación/edición de video para agentes

Herramienta en capas basada en ffmpeg: el agente revisa el material, define objetivos y escribe un plan; el código se encarga de la geometría del encuadre, el renderizado y la verificación. La relación de aspecto es configurable (por defecto vertical 1080×1920). Los comandos y detalles de formato están en el README del motor y en docs/engine.zh.md; léelos antes de empezar.

Compuerta de entrega (obligatorio)

Las reglas que nadie ejecuta no existen. Cada paso tiene código que las hace cumplir: si no se sigue el proceso, no se puede entregar el video final.

  1. Escribe un brief antes de empezar ($P/brief.json) y regístralo: reel register brief.json. Especifica idioma de entrega, si es final o muestra, directorio de entrega, qué no se puede cambiar; si no lo sabes, pregúntale al usuario. Después del registro, usar cp/mv/ffmpeg directamente en Bash para escribir en el directorio de entrega, o reel … --out PATH / --out=PATH (también --png, --sheet, --report, --check-png) apuntando al directorio de entrega será rechazado por hooks/guard_delivery.py. Este guardia solo analiza el texto del comando, hace lo que puede: los comodines, llaves, sustitución de comandos, escritura dentro de scripts y escritura remota pueden no ser bloqueados; no lo tomes como un permiso, la entrega solo se hace con reel deliver.
  2. Prueba de sonido primero: no hay sonido fijo por defecto. Primero entrega una muestra de 10–20 segundos para que la persona la escuche. Una vez aprobada, escribe la cita original, la ruta de la muestra y su sha256 en brief.voice.approved; si se cambia la voz, hay que repetir la prueba.
  3. Revisión después de producir: reel check video_final.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|proyecto.json]. Si el código de salida es 1, no se puede entregar. Revisa result.gate.blockers (fallos técnicos) y pending_review (requiere confirmación humana); not_covered lista los elementos no verificados, no se puede decir "verificado".
  4. Revisión por el usuario: revisa cada elemento de needs_review uno por uno (reel scrub / extracción de fotogramas), escribe un registro de revisión con código de tiempo para cada elemento; mira el video completo y escribe final_watch, escucha el audio y escribe final_listen.
  5. Entrega: reel deliver video_final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json. Si no se cumplen las condiciones de video final, reporta DELIVERY_NOT_FINAL, solo se permite --sample, el nombre del archivo debe incluir "muestra_pendiente". No se puede volver a entregar con la misma versión; las versiones anteriores no se eliminan ni sobrescriben.
  6. Condición para decir "completado": haber obtenido un recibo con status: final (reel receipt <recibo> para verificar). De lo contrario, di honestamente "incompleto / muestra pendiente de revisión / pendiente de prueba de sonido". hooks/deliver_gate.py (Stop hook) bloqueará cualquier declaración de "completado" sin recibo; el recibo debe corresponder a la obra específica que se menciona (cuando se nombre la obra y la versión, coincidirá por nombre de obra y versión). Este hook solo controla proyectos registrados y turnos donde se haya invocado reel por defecto; con REEL_GATE_SCOPE=global se aplica a todo el sistema.
  7. Los videos producidos por scripts de renderizado propios del proyecto también deben seguir los pasos 3–6.
  8. MV: añade --contract mv.json. La verificación de letras lee la capa de letras declarada en el contrato (durante cada frase cantada la capa tiene texto; antes de cantar no tiene texto), no lee los píxeles del video final, por lo que no se puede afirmar "las letras en pantalla han sido verificadas". song_level compara la sonoridad y el pico verdadero de cada canción en colecciones y con policy: "trim", con la misma tolerancia que para canciones individuales.
  9. Los errores de parámetros también generan JSON (ARG_INVALID, código de salida 2); --help muestra el texto de ayuda. reel voice check para verificar chino (por defecto --lang zh) necesita además pypinyin (instalado en el mismo venv); si falta, reporta BACKEND_UNAVAILABLE; reel words solo necesita whisper-cli y el modelo.

Ejemplo de brief.json (para MV añadir "kind": "mv"):

{"version": "reel.brief.v1", "name": "promoción_matrícula", "language": "zh-CN", "deliverable": "final",
 "delivery_root": "~/Deliveries/<proyecto>", "must_not_change": ["créditos_finales"],
 "voice": {"mode": "tts", "voice_id": "zh-CN-XiaoxiaoNeural",
           "approved": {"voice_id": "zh-CN-XiaoxiaoNeural", "by": "user", "quote": "Esta voz está bien",
                        "sample": "voice_sample.mp3", "sample_sha256": "<resultado_de_shasum -a 256>"}},
 "profile": "default"}
  • Del brief, solo name, must_not_change y los campos con clave text / title / caption / label entran en el escaneo de texto; language, delivery_root, voice.* no se escanean.
  • Si no hay locución, escribe "voice": {"mode": "none"}; si es grabación real, escribe "recorded". Para versiones sin sonido, usa un perfil de proyecto: {"extends": "default", "audio": "silent"}.
  • Perfiles: default (umbrales genéricos), social-vertical (plataformas verticales: 1080×1920 30fps, -16 LUFS); las diferencias del proyecto se escriben en un perfil de proyecto (extends), las pausas prolongadas intencionadas se registran en allow con una justificación. El vocabulario de escaneo de texto está en la sección text del perfil: banned y extra_banned (sin distinción de mayúsculas/subcadenas, si coincide falla; las palabras prohibidas del proyecto se añaden en extra_banned), banned_words (distingue mayúsculas, palabras completas como TODO / TBD / FIXME, si coincide falla), review (placeholder, lorem ipsum, palabras completas, si coincide requiere revisión, se debe escribir un registro de revisión text_scan).

Al inicio de cada bloque de Bash

Cada invocación de Bash del agente es un shell nuevo, las funciones no se conservan, por lo que reel es un script en PATH (bin/reel), no una función. Selecciona el intérprete en el orden: REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3. Si hay problemas de entorno, ejecuta primero reel doctor (lista dependencias necesarias y opcionales y cómo solucionarlas; si faltan las necesarias, sale con código 1):

command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<proyecto>"; mkdir -p "$P/preview" && cd "$P"   # Los archivos generados van al directorio del proyecto, no a /tmp

Flujo de trabajo estándar

  1. Prepara el material en el directorio del proyecto $P (material, observations.json, plan.json, vistas previas, video final; un directorio un plan, .reel-history/ guarda las revisiones).
  2. Revisa el material, define objetivos:
    reel inspect material/a.jpg material/b.mp4
    reel frame material/a.jpg --out "$P/preview/a_grid.png"          # Lee la imagen con cuadrícula 0–1, lee el cuadro objetivo
    reel observe --obs observations.json --src material --asset a.jpg --bbox x0,y0,x1,y1 --label "objetivo"
    reel locate  --obs observations.json --src material --asset b.mp4 --t 2 --query "vaso rojo" --check-png "$P/preview/chk.png"  # OWLv2, necesita torch
    
  3. Escribe plan.json (EditPlan v1): camera: [] es estático real; zoom_to referencia una observation para acercarse al objetivo; track sigue una observation en múltiples puntos de tiempo; transition_out transición. Los planos de video no deben cruzar los puntos de corte indicados por inspect.
  4. Validación + vista previa: reel validate plan.json; reel compile plan.json; reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png", revisa el mosaico para confirmar el movimiento de cámara.
  5. Producción: reel render plan.json --out "$P/video_final.mp4" --sheet "$P/preview/final.png" --where mac. El audio del video final es fijo AAC 48 kHz, checks incluye la frecuencia de muestreo. Que todos los checks pasen solo indica que el renderizado no se ha dañado; luego continúa con los pasos 3–6 de la compuerta de entrega.

Línea de tiempo y sincronización con el ritmo

  • Ver: reel timeline plan.json --format text; reel timeline plan.json --png tl.png [--beats beats.json]; reel scrub plan.json --cuts --render video_final.mp4 --out directorio.
  • Modificar: reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}' (se escribe después de cada paso de validación); reel undo plan.json --to r2; reel history plan.json.
  • Sincronizar con el ritmo: reel beats musica.mp3 --out beats.json → reel snap plan.json --beats beats.json --mode downbeat (--dry-run primero para ver un informe).

Páginas web: navegación, seguimiento y resaltado sincronizado

Cuando el material es una página web, no se hace OCR: la posición del texto se lee directamente del DOM, los planos y los resaltados los dibuja el navegador fotograma a fotograma.

  1. Escribe la locución basada en el texto original de la página (las frases a resaltar deben coincidir exactamente con la página), genera voice.mp3 con TTS.
  2. reel words voice.mp3 --out words.json (whisper local, tiempos palabra por palabra).
  3. En el plan, usa planos con kind: "web", camera: [{"op": "follow"}], highlight: [{"text": "texto original de la página…", "sync": "voice"}], audio.words apunta a words.json.
  4. Si reporta TEXT_NOT_FOUND = la página no contiene ese texto original; TEXT_NOT_IN_VOICE = la locución no coincide.

GPU remota (opcional)

  • Configura REEL_REMOTE=user@gpu-host (se pueden separar varios con espacios) y luego reel render --where 5090 / --where auto enviará el renderizado a un host NVIDIA remoto (NVENC + libass), y los archivos generados se descargarán para una segunda verificación local. Si no está configurado, solo se usa la máquina local.
  • VRAM por defecto ≤80%, si se supera reporta NEED_USER_APPROVAL, primero informa al usuario; solo después de la aprobación se añade --allow-over-80. Si el uso de GPU es ≥50%, reporta GPU_BUSY, no compite. El flock remoto garantiza que solo una tarea GPU de reel se ejecute a la vez.
  • reel remote probe consulta el estado; reel remote setup-vision crea un venv independiente en remoto (torch + OWLv2).

Skills relacionados