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.
- 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, oreel … --out PATH/--out=PATH(también--png,--sheet,--report,--check-png) apuntando al directorio de entrega será rechazado porhooks/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 conreel deliver. - 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. - 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. Revisaresult.gate.blockers(fallos técnicos) ypending_review(requiere confirmación humana);not_coveredlista los elementos no verificados, no se puede decir "verificado". - Revisión por el usuario: revisa cada elemento de
needs_reviewuno 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 escribefinal_watch, escucha el audio y escribefinal_listen. - 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, reportaDELIVERY_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. - 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; conREEL_GATE_SCOPE=globalse aplica a todo el sistema. - Los videos producidos por scripts de renderizado propios del proyecto también deben seguir los pasos 3–6.
- 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_levelcompara la sonoridad y el pico verdadero de cada canción en colecciones y conpolicy: "trim", con la misma tolerancia que para canciones individuales. - Los errores de parámetros también generan JSON (
ARG_INVALID, código de salida 2);--helpmuestra el texto de ayuda.reel voice checkpara verificar chino (por defecto--lang zh) necesita ademáspypinyin(instalado en el mismo venv); si falta, reportaBACKEND_UNAVAILABLE;reel wordssolo necesitawhisper-cliy 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_changey los campos con clavetext/title/caption/labelentran 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 enallowcon una justificación. El vocabulario de escaneo de texto está en la seccióntextdel perfil:bannedyextra_banned(sin distinción de mayúsculas/subcadenas, si coincide falla; las palabras prohibidas del proyecto se añaden enextra_banned),banned_words(distingue mayúsculas, palabras completas comoTODO/TBD/FIXME, si coincide falla),review(placeholder,lorem ipsum, palabras completas, si coincide requiere revisión, se debe escribir un registro de revisióntext_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
- 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). - 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 - Escribe plan.json (EditPlan v1):
camera: []es estático real;zoom_toreferencia una observation para acercarse al objetivo;tracksigue una observation en múltiples puntos de tiempo;transition_outtransición. Los planos de video no deben cruzar los puntos de corte indicados porinspect. - 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. - 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,checksincluye la frecuencia de muestreo. Que todos loscheckspasen 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-runprimero 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.
- 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.mp3con TTS. reel words voice.mp3 --out words.json(whisper local, tiempos palabra por palabra).- En el plan, usa planos con
kind: "web",camera: [{"op": "follow"}],highlight: [{"text": "texto original de la página…", "sync": "voice"}],audio.wordsapunta awords.json. - 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 luegoreel render --where 5090/--where autoenviará 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%, reportaGPU_BUSY, no compite. El flock remoto garantiza que solo una tarea GPU de reel se ejecute a la vez. reel remote probeconsulta el estado;reel remote setup-visioncrea un venv independiente en remoto (torch + OWLv2).