/reel: producción de video para Claude Code
Una herramienta en capas construida sobre ffmpeg. Tú (Claude) observas el material, decides qué mostrar y escribes un plan; el código se encarga de la geometría del encuadre, el renderizado y las comprobaciones. El tamaño de salida es configurable (por defecto vertical 1080x1920).
Los comandos y formatos de archivo están documentados en docs/ENGINE.md del repositorio de reel. Léelo antes del primer comando: cat "$(reel --root)/docs/ENGINE.md". reel <comando> --help lista todas las opciones. Cada comando imprime un objeto JSON ({"ok": true, "result": ...} o {"ok": false, "error": {"code": ..., ...}}) y sale con 1 en caso de error.
Orden de trabajo: primero la dirección, luego la edición
Para cualquier video que vaya a ver alguien que no sea el usuario, sigue SOP.md: S0 ingesta, S1 paquete de fuentes, S2 inventario de activos, S3-S4 un agente director escribe direction/BRIEF.md y un storyboard, luego edita directamente (el paso de aprobación G1 no bloquea por defecto), luego la puerta de entrega a continuación. En S7, un agente director independiente revisa el corte contra el BRIEF. Instalado como plugin, el agente se llama reel:director.
- Dale al director las rutas del material original, no tus propias conclusiones sobre él.
- Si existe un BRIEF aprobado y el propósito, la audiencia y el alcance del material no han cambiado, síguelo.
- Si el usuario dice que el video es aburrido o sin sentido, vuelve a S3 y replantea la pieza; no solo lo reedites.
Puerta de entrega (obligatoria)
Cada paso se aplica mediante código: salta uno y no puedes entregar un corte final.
- Escribe el brief primero (
$P/brief.json, plantilla a continuación) y regístralo:reel register brief.json. Idioma de entrega, final o muestra, carpeta de entrega y lo que no debe cambiar: si no puedes completar estos campos, pregunta al usuario. Una vez registrado, el enganche de Bash impide escriturascp/mv/ffmpegen la carpeta de entrega. - Audiciona la voz. No hay voz predeterminada. Elige una que se ajuste al brief, renderiza una muestra de 10-20 s y ejecuta
reel voice check sample.mp3 --script sample.txt --brief brief.json. Whisper local transcribe la muestra y la compara con el texto (--langpor defecto esen; para una locución en chino pasa--lang zh, que compara mediante pinyin sin tonos, por lo que la ortografía homófona no cuenta como error); solo una tasa de error del 10% o menos escribe la aprobación enbrief.voice.approved(by: claude, con la transcripción como evidencia). Si el usuario escuchó, registra sus palabras exactas.- STT demuestra que las palabras se leen correcta y claramente. No demuestra que la voz se adapte a la pieza: di en tu respuesta que elegiste la voz, y cambia de voz en la siguiente versión si al usuario no le gusta.
- Una voz nueva necesita una nueva comprobación. La voz de macOS
sayes solo para borradores internos, nunca para un video entregado.
- Comprueba el renderizado:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt].- Salida 1 significa que no se puede entregar. Lee
result.gate.blockers(fallos técnicos: ni siquiera una muestra se puede entregar) yresult.gate.pending_review(elementos que un revisor debe examinar). - No te fíes solo de
ok.result.gate.not_coveredlista lo que no se comprobó (por ejemplo, texto en pantalla, que no tiene OCR); nunca digas que esos elementos fueron revisados.
- Salida 1 significa que no se puede entregar. Lee
- Revisa. Examina cada elemento
needs_review(reel scrub, capturas de fotogramas) y escribe un registro de revisión por elemento con observaciones con código de tiempo. Mira el corte completo tú mismo y firmafinal_watch(al menos un fotograma por toma); escucha de principio a fin y firmafinal_listen(una firma de agente necesita observaciones con código de tiempo; si el usuario escuchó, registra sus palabras exactas comoquote). Cuando hayas firmado ambos, entrégalo como final: el recibo diceapproved_by: agent, y tu respuesta dice "corte final, revisado por Claude, aún no visto por ti". Los comentarios del usuario se convierten en la siguiente versión. El formato dereviews.jsonestá endocs/ENGINE.md. - Entrega:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json.- Si no se cumplen las condiciones finales, falla con
DELIVERY_NOT_FINALy enumera por qué. Entonces solo es posible--sample: el nombre del archivo llevasample-pending-review, y debes llamarlo muestra cuando se lo digas al usuario. - Un número de versión se puede entregar una vez; las versiones antiguas nunca se eliminan ni sobrescriben. Solo cuando el usuario pida explícitamente eliminar versiones antiguas:
reel register brief.json --remove, eliminar, luego registrar de nuevo.
- Si no se cumplen las condiciones finales, falla con
- Decir "listo" requiere un recibo con
status: final(reel receipt <receipt.json>lo vuelve a verificar). De lo contrario, indica el estado real: "no terminado", "muestra pendiente de revisión", "voz no auditada". El enganche Stop bloquea una declaración de finalización que no tenga un recibo correspondiente. - Los videos realizados por el propio script de renderizado de un proyecto (
build_*.pyy similares), o compuestos en otra herramienta y exportados, también pasan por los pasos 3-6.
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(sin voz),recorded(una grabación real),ttsoclone(estos dos también necesitanvoice_idy un bloqueapprovedescrito porreel voice check, o una aprobación humana conquote,sampleysample_sha256).delivery_rootdebe ser una ruta absoluta existente (o comenzar con~). No puede ser la carpeta de inicio, Escritorio, Documentos, Descargas, la raíz de iCloud Drive, la carpeta del proyecto ni un padre de esta.- Una versión silenciosa usa un perfil de proyecto:
{"extends": "default", "audio": "silent"}. - Perfiles:
default(umbrales generales de inicio) yvertical-strict(1080x1920 30 fps, -16 LUFS, estricto). Pon las diferencias del proyecto en un perfil de proyecto conextends; registra las pausas largas previstas enallowcon una razón; añade palabras prohibidas (nombres de productos antiguos, texto de relleno) atext.extra_banned.
Al inicio de cada llamada a Bash
Cada llamada a Bash inicia un shell nuevo, por lo que debes comenzar cada llamada con:
REEL_PROJECT=spring-promo # nombre de este proyecto
command -v reel >/dev/null || { echo "reel no está en PATH (habilita el plugin, o ejecuta ./install.sh --link)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg no encontrado" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
Todas las salidas viven en $P, nunca en una carpeta temporal; las rutas relativas a continuación son relativas a $P.
Haciendo el corte
Tú tomas las decisiones (qué tomas, qué sujeto, movimientos de cámara, ritmo); la percepción, geometría, renderizado y comprobaciones las hace el código. La sintaxis completa de los comandos está en docs/ENGINE.md.
- Material en
$P(activos,observations.json,plan.json, vistas previas, renderizados e informes de comprobación viven allí; un plan por carpeta). - Guión y voz. Escribe el guión de la locución, elige una voz que se ajuste al brief y pasa la audición (paso 2 de la puerta). Produce
voice.mp3(o.wav) y, si quieres subtítulos,voice.vtt. Para trabajos publicados, prefiere una grabación real o una voz cuya licencia cubra el uso; para una pieza solo de música, apuntaaudio.voicea la pista de música (es el ancla de la línea de tiempo). - Mira y elige objetivos:
reel inspect(lista cada archivo) →reel frame(Lee la imagen con la cuadrícula 0-1 y lee la caja del sujeto) →reel observepara registrarlo, oreel locate --query ... --check-png ...(OWLv2; mira la imagen de verificación antes de usar una detección). - Escribe
plan.json(EditPlan v1):camera: []mantiene el fotograma fijo;zoom_tocon unobservation_idse acerca a un sujeto registrado; usatrackcuando el sujeto se mueve en un video;transition_outpara transiciones. No permitas que un plano de video cruce un corte de escena reportado porinspect.audio.voicees obligatorio y se resuelve contrasrc_dir. - Valida y previsualiza:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png, luego lee la hoja de contactos para juzgar el movimiento de cámara. - Renderiza:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(usa--where remotesolo si el usuario configuró una GPU remota y lo pidió). Pasar las comprobaciones de renderizado solo significa que el archivo no está roto; continúa con los pasos 3-6 de la puerta.
Otros puntos de entrada, cada uno con una sección en docs/ENGINE.md:
- Inspeccionar y cambiar la línea de tiempo:
reel timeline(--format texto una imagen--pngmultipista),reel scrub(fotogramas alrededor de cada corte),reel edit/undo/history,reel preview --range(vista previa de baja resolución con sonido). - Cortar al ritmo:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat; luego verifica cada corte conreel timeline --png --beats. Necesita./install.sh --beats. - Narrar una página web con resaltados: un plano con
kind: "web"; las posiciones del texto provienen del DOM (sin OCR), por lo que una oración resaltada debe coincidir exactamente con el texto de la página;reel words voice.mp3da el tiempo por palabra. Necesita./install.sh --web. - Proyectos Shotcut:
reel mlt project.mlt --video-only;--dupesencuentra metraje fuente usado dos veces.
Disponible: ensamblaje de planos, acercamientos de subpíxel a una caja de sujeto, seguimiento de un sujeto en movimiento, transiciones xfade, subtítulos incrustados, música de fondo, gradación y LUTs, tomas web, búsqueda de sujeto OWLv2, comprobaciones técnicas, entrega con puerta. No incorporado: transiciones suavizadas, interpolación de fotogramas, clonación de voz.
GPU remota (opcional)
Las partes --where remote se aplican mediante código.
- Úsala solo cuando el usuario haya configurado
REEL_REMOTE(un destino ssh) y lo pida; de lo contrario, renderiza con--where local. - El uso de VRAM está limitado al 80% por defecto. Cuando un trabajo necesita más, la herramienta devuelve
NEED_USER_APPROVAL: informa al usuario primero, y añade--allow-over-80solo con su consentimiento. Una utilización de GPU del 50% o más significa que alguien más la está usando; no la tomes. - Un trabajo de GPU de reel a la vez (bloqueo de archivo remoto). No cambies los límites de energía. Nunca reinicies ni apagues el host.
reel remote probeinforma sobre el host;reel remote setup-visioninstala un venv separado con torch y los pesos de OWLv2 en el host remoto.
Archivos complementarios
SOP.md: flujo de trabajo primero-dirección, roles, pasos y condiciones de salida.- El agente
director(agents/director.mden el repositorio): brief, storyboard y revisión. docs/ENGINE.mden el repositorio: comandos, EditPlan, brief, reseñas, recibos y perfiles.