Communitygithub.com

reel

Muestra a un agente cómo planificar, construir o editar un 'reel' para que el resultado concreto sea un video terminado. El procedimiento avanza a través de /reel: producción de video para Claude Code, orden de trabajo: primero la dirección, luego la edición, puerta de entrega (obligatoria). Úsalo cuando una nueva tarea requiera esta tarea.

¿Qué es reel?

Reel es una habilidad especializada para agentes de IA (Claude Code) que permite la producción completa de videos, desde la planificación hasta la entrega final, utilizando ffmpeg como motor subyacente. Su enfoque principal es guiar al agente a través de un flujo de trabajo estructurado: primero la dirección (brief y storyboard), luego la edición técnica (selección de tomas, voz, corrección de color) y finalmente una puerta de entrega obligatoria con verificaciones automáticas. La habilidad requiere que el agente revise el material original, tome decisiones creativas (qué tomas mostrar, ritmo, movimientos de cámara) mientras el código se encarga de la geometría, el renderizado y las comprobaciones técnicas. Reel verifica automáticamente aspectos como la calidad del audio (mediante transcripción local con Whisper), la coherencia del brief, y asegura que no se puedan entregar videos que no cumplan con todos los requisitos de calidad. Soporta múltiples perfiles de salida (por defecto vertical 1080x1920), integración con GPU remota opcional, y herramientas adicionales como detección de ritmo musical y narración de páginas web. El agente debe seguir estrictamente el orden de trabajo documentado en SOP.md y docs/ENGINE.md, y no puede declarar una tarea como completada sin un recibo de entrega válido.

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

Preguntar en tu IA favorita

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

Documentación

/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.

  1. 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 escrituras cp/mv/ffmpeg en la carpeta de entrega.
  2. 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 (--lang por defecto es en; 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 en brief.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 say es solo para borradores internos, nunca para un video entregado.
  3. 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) y result.gate.pending_review (elementos que un revisor debe examinar).
    • No te fíes solo de ok. result.gate.not_covered lista lo que no se comprobó (por ejemplo, texto en pantalla, que no tiene OCR); nunca digas que esos elementos fueron revisados.
  4. 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 firma final_watch (al menos un fotograma por toma); escucha de principio a fin y firma final_listen (una firma de agente necesita observaciones con código de tiempo; si el usuario escuchó, registra sus palabras exactas como quote). Cuando hayas firmado ambos, entrégalo como final: el recibo dice approved_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 de reviews.json está en docs/ENGINE.md.
  5. 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_FINAL y enumera por qué. Entonces solo es posible --sample: el nombre del archivo lleva sample-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.
  6. 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.
  7. Los videos realizados por el propio script de renderizado de un proyecto (build_*.py y 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), tts o clone (estos dos también necesitan voice_id y un bloque approved escrito por reel voice check, o una aprobación humana con quote, sample y sample_sha256).
  • delivery_root debe 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) y vertical-strict (1080x1920 30 fps, -16 LUFS, estricto). Pon las diferencias del proyecto en un perfil de proyecto con extends; registra las pausas largas previstas en allow con una razón; añade palabras prohibidas (nombres de productos antiguos, texto de relleno) a text.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.

  1. Material en $P (activos, observations.json, plan.json, vistas previas, renderizados e informes de comprobación viven allí; un plan por carpeta).
  2. 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, apunta audio.voice a la pista de música (es el ancla de la línea de tiempo).
  3. 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 observe para registrarlo, o reel locate --query ... --check-png ... (OWLv2; mira la imagen de verificación antes de usar una detección).
  4. Escribe plan.json (EditPlan v1): camera: [] mantiene el fotograma fijo; zoom_to con un observation_id se acerca a un sujeto registrado; usa track cuando el sujeto se mueve en un video; transition_out para transiciones. No permitas que un plano de video cruce un corte de escena reportado por inspect. audio.voice es obligatorio y se resuelve contra src_dir.
  5. 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.
  6. Renderiza: reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local (usa --where remote solo 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 text o una imagen --png multipista), 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 con reel 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.mp3 da el tiempo por palabra. Necesita ./install.sh --web.
  • Proyectos Shotcut: reel mlt project.mlt --video-only; --dupes encuentra 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-80 solo 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 probe informa sobre el host; reel remote setup-vision instala 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.md en el repositorio): brief, storyboard y revisión.
  • docs/ENGINE.md en el repositorio: comandos, EditPlan, brief, reseñas, recibos y perfiles.

Skills relacionados