video-animado-personalizado: orquestador
SKILL_DIR = la carpeta que contiene este archivo. Eres el orquestador: mantienes la intención del usuario, delegas cada etapa a un subagente especializado y ejecutas tú mismo la puerta de revisión. Nunca incluyas un estilo en el núcleo; cada valor de estilo proviene del style_bible.json del usuario.
| indicador | significado |
|---|---|
--script | script.txt / script.md (las palabras realmente habladas) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json (cualquier forma; se normaliza automáticamente) |
--bgm | archivo de música opcional (si no, biblioteca de recursos, o drone modal procedural) |
--aspect | 16:9 (1920×1080, predeterminado) o 9:16 (1080×1920) |
--subtitles | true / false |
--out | .mp4 de salida (su carpeta es WORK a menos que se especifique --workdir) |
Pipeline (todo impulsado por scripts/build_video.py): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (por toma → clip, eliminar cuadros) → concat + mux → QA frames → auto-clean → review gate.
Agentes y enrutamiento
| etapa | subagente | modelo · esfuerzo | trabajo |
|---|---|---|---|
| 1 ingesta | cav-ingest | haiku · bajo | verificación en tiempo de ejecución, --stage analyze, escribe WORK/director_brief.json |
| 2 dirección | cav-director | sonnet · medio | storyboard.json (7 reglas de director); actualizaciones solo de tomas |
| 3 dibujo | cav-artist (cav-artist-fast en modo rápido/económico) | opus · alto (sonnet · alto) | scene_drawers.js (6 reglas de arte) + verificación de vista previa; correcciones específicas |
| 4 construcción | cav-builder | haiku · bajo | completo / --only / --apply-review / --ship, telemetría de audio |
| 5 QA | cav-qa-critic | sonnet · medio | inspecciona WORK/qa/, devuelve `STATUS: PASS |
Usa el modo rápido solo si el usuario lo solicitó (rápido/económico/barato/borrador). Nunca degrades silenciosamente al artista.
Reglas de orquestación
- Subagentes de un solo disparo y sin estado. Los cachés de indicaciones caducan después de ~5 minutos y la puerta de revisión del usuario puede durar mucho más, así que nunca mantengas un subagente activo después de una puerta y nunca envíes
SendMessagea uno finalizado. Genera un subagente nuevo por tarea con rutas absolutas explícitas y un resumen estructurado conciso (abajo). Ejecuta trabajo independiente en un solo mensaje. - Formato de resumen (cada delegación):
SKILL_DIR,WORK, los valores exactos de--script/--audio/--style/--aspect/--subtitles/--bgm/--out, la tarea, los archivos de entrada a leer, los archivos a escribir y la forma de la respuesta que necesitas. - Mantén tu propio contexto pequeño: lee resúmenes de subagentes, no archivos sin procesar. Nunca leas
Readaudio_timeline.json(grandes arreglos por cuadro). UsaWORK/director_brief.json. - Si un tipo de subagente
cav-*aún no está disponible en esta sesión (los agentes registrados a mitad de sesión pueden no aparecer hasta un reinicio), mantén el enrutamiento del modelo: llama aAgent(subagent_type="general-purpose", model=<m>)conmodel=haikuparacav-ingest/cav-builder,sonnetparacav-director/cav-artist-fast/cav-qa-critic,opusparacav-artist, e indícale que primero lea$SKILL_DIR/agents/<agent-name>.mdy lo siga como sus instrucciones, luego dale el resumen habitual. - Asegúrate de que el usuario haya proporcionado el guion, la voz en off y la biblia de estilo; pregunta (
AskUserQuestion) solo por lo que falte.
Fase 0 · Registrar subagentes y entorno de ejecución
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(Portátil en macOS y Linux. build_video.py también los mantiene sincronizados en cada ejecución; la línea anterior lo garantiza en el primer turno). El entorno de ejecución privado ($SKILL_DIR/.runtime/: venv, modelo Whisper, navegador, ffmpeg si es necesario) se inicializa mediante cav-ingest a través de build_video.py --check (1–3 min una vez, se necesita internet; nunca toca otros entornos). Decide WORK (dirname(--out)) y haz mkdir -p.
Fase 1 · Ingesta → cav-ingest
Delega. Espera STATUS: ok|needs_user y WORK/director_brief.json.
alignment_coverage < 0.6→ el guion no coincide con la toma: detente y pregúntale al usuario (corrige el guion / confirma / proporciona una nueva toma). Las diferencias solo de ortografía están bien.- Falta una entrada de estado de ánimo/paleta requerida → pregunta si agregarla a la biblia o aceptar los valores predeterminados.
- De lo contrario, continúa; muestra las advertencias en tu próximo mensaje dirigido al usuario.
Fase 2 · Dirigir → cav-director
Entradas: WORK/director_brief.json, WORK/storyboard.draft.json, references/storyboard_schema.json. Salida WORK/storyboard.json. Verifica la cordura de la respuesta (mosaico, cortes en puntos de pausa, tomas de 1.5–6 s, variedad de cámara, efectos de sonido presentes). Si no estás satisfecho → una nueva llamada a cav-director con correcciones específicas.
Fase 3 · Dibujar → cav-artist (o cav-artist-fast)
Entradas: WORK/storyboard.json, WORK/style.normalized.json, la biblia del usuario, más los argumentos de CLI originales para las vistas previas de renderizado. Salida WORK/scene_drawers.js, verificada con una vista previa --frames (cero errores de [scene / layer / frame]). El trabajo del artista es solo arte; los cambios necesarios en el guión gráfico se te informan a ti para que los envíes a cav-director.
Fase 4 · Construir → cav-builder
Construcción completa hacia --out (pasa --no-review; la puerta es tuya). Espera BUILD: ok, ducking dentro de ±1 dB del objetivo, ≈ −14 LUFS y cuadros de WORK/qa/. Si falla, dirige el error nombrado [scene / layer / frame] a cav-artist (o un error de sincronización a cav-director), luego reconstruye con --only.
Fase 5 · QA → cav-qa-critic
Ejecuta siempre antes de que el usuario vea algo. En caso de STATUS: FAIL:
- Tickets con
target_file: scene_drawers.js→ nuevocav-artist(modo corrección, lista de tickets en el resumen). Tickets constoryboard.json→ nuevocav-director(actualización específica), luegocav-artistsi cambiaron las claves de escena. cav-buildercon--only <ids de tomas afectadas>.- Nuevo
cav-qa-criticen los nuevos cuadros. Máximo 2 bucles de corrección automática; luego informa al usuario qué sigue fallando y deja que decida (continuar a la puerta de revisión o dirigir una corrección).
Fase 6 · PUERTA DE REVISIÓN (tú, en la sesión principal; nunca la saltes, nunca decidas por el usuario)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
Pregunta con AskUserQuestion, como máximo tres llamadas rápidas (diles la ruta del video y lo que confirmó QA):
- ronda1 · "¿Enviar o cambiar?"
- Si Cambiar, ronda2 en UNA llamada: ¿Qué partes? (Visuales / Cámara y edición / Subtítulos / Sonido, múltiple) y ¿Qué momentos? (Video completo o tomas específicas, múltiple).
- UNA llamada con la pregunta de la ronda3 para cada parte seleccionada (múltiple; "Otro" = texto libre): Visuales → Personaje · Fondo · Colores e iluminación · Movimiento; Cámara → Más cerca · Más abierto · Más calmado · Sincronización de cortes/transiciones; Subtítulos → Apagar · Más grande · Más pequeño · Mover arriba; Sonido → Música más baja/más alta · Efectos más bajos/más altos.
Escribe las respuestas en WORK/review.json:
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "the face looks too long", "sound": "use ~/music/sitar.mp3"}}
Luego:
- Cambios paramétricos (encuadre más cerrado/más abierto/más calmado, subtítulos apagados/tamaño/posición, música/efectos ±3 dB) →
cav-buildercon--apply-review WORK/review.json. Reconstruye solo los objetivos afectados (sonido → audio + remux; cámara → esas tomas; subtítulos → todas las tomas). - Tickets de arte/corte (visuales, sincronización de cortes, notas de texto libre) →
--apply-reviewtambién escribeWORK/review_plan.jsone imprime el comando--onlyexacto. Delega solo las tomas afectadas a un nuevocav-director(sincronización de cortes/ritmo de cámara) y/ocav-artist(visuales), dandoreview_plan.jsony las notas →cav-builder --only <tomas>→cav-qa-criticen las tomas modificadas → de vuelta a la ronda 1. Bucle hasta Enviar.storyboard.prev.jsoncontiene el guión gráfico anterior al cambio por si el usuario quiere deshacer.
Fase 7 · Enviar → cav-builder
Al recibir Enviar, delega --ship (--keep-deps si el usuario va a hacer otro video pronto; --purge-recipe solo si se solicita). Conserva solo el video final (más las entradas del usuario y la receta de pocos KB storyboard.json / scene_drawers.js) y elimina todos los archivos generados y $SKILL_DIR/.runtime/. Informa al usuario: la ruta del video, su línea de especificaciones (resolución/fps/duración) y el espacio en disco liberado. Las herramientas del sistema (python3, ffmpeg, Chrome) nunca se tocan.
Garantías que los subagentes deben preservar (detalle completo en sus archivos)
Director: las tomas se superponen en mosaico; cortes en puntos de pausa; 1.5–6 s; preajustes variados; beat en cada pausa; un estado de ánimo/toma; transiciones en pausas; speaker en tomas de sincronía labial; sfx_events precisos por cuadro (pasos por walk_cycle.frames_per_step, alternancia de ±1.5 dB; swell picos en t_sec + duration_sec en el corte; ambience −24…−28 dB; bgm.gain_db −18…−21).
Arte: color solo de paleta, sin hex, sin #000, sombras shadowOf, una luz clave F.mood.key_dir_deg, cinco capas de paralaje + _lights, márgenes ≥ 400 px, arquitectura fundamentada, celShade + drawTaperedStroke(…, 1.6) + un applyRimLight basado en arreglos, pies plantados IK, cadenas de tela, bocas de sincronía labial, CAV.withBoil en pares (tc) solo para personajes/FX, RNG determinista.
Audio: primero recursos de efectos de sonido, luego procedurales; sidechaincompress ducking ±1 dB de audio_palette.duck_db (15), +3 dB de aumentos en pausas, loudnorm de dos pasos −14 LUFS / −1.5 dBTP; las pistas se eliminan después de la mezcla.
Construcción: clips por toma (x264 crf 16) con eliminación inmediata de cuadros; los hashes de build_state.json hacen que las reejecuciones sean incrementales; --only s2,s3,audio restringe una reejecución; las tomas cuyos cortes se movieron, y un seguidor de fundido de cualquier toma re-renderizada, siempre se re-renderizan. Banderas: --preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto.
API de arte: references/art_reference.md · esquemas: references/storyboard_schema.json, references/style_schema.json.
Solución de problemas
alignment_coveragebajo → el guion y la toma difieren; corrigescript.txt.scene_drawers.js no define scene(s)→ las claves de escena del guión gráfico deben coincidir con las claves deregisterScenes.- Ducking lejos del objetivo → respiración/filtraciones de música; pasa
--duck-dbo subebgm.gain_db. - Cuadros en blanco/negro → una capa falló; lee el error
[scene / layer / frame]. Renderizados lentos →--workers N,--preview. - Entorno de ejecución roto/desactualizado → elimina
$SKILL_DIR/.runtime/y ejecuta--check. Sin conexión → estableceCAV_RUNTIME; el alineador recurre a segmentación solo por energía sin un modelo Whisper. - Nuevos subagentes no listados en la sesión actual → están registrados en disco; inicia una nueva sesión de Claude Code o usa el fallback
general-purposeanterior (con elmodelcoincidente).