Craft Music Video (FilmCraft + EffectCraft)
Workflow reutilizable para producir videoclips sincronizados sobre una pista de audio combinando EffectCraft (escenas 2D, motion graphics, VFX, capa de letras alfa independiente) y FilmCraft (montaje principal multipista, sincronización rítmica, mezcla/masterización de audio, gradación global, doble exportación Master + Clean).
Métodos comunes de animación 2D (encuadres, cambios de pose con anticipación, anclas de personajes/cámaras, trampas de parenting de EffectCraft, orden de apilamiento y legibilidad del texto): seguir craft-2d-animation.
Referencia completa de MCP, comandos de motor verificados y configuraciones Flatpak: references/mcp-and-commands.md.
0. Prerrequisitos MCP y Sandbox (a verificar antes de empezar)
- Verificar que los servidores MCP
effectcraftyfilmcraftestén expuestos en la sesión actual (o cambiar correctamente a los CLIeffectcraft-cli/filmcraft-cli).- Si faltan, no inventar llamadas: consultar references/mcp-and-commands.md para la configuración exacta (Flatpak Linux
ai.storyteller.filmcraft/ai.storyteller.effectcrafto binario nativo, en modo headless o bridge).
- Si faltan, no inventar llamadas: consultar references/mcp-and-commands.md para la configuración exacta (Flatpak Linux
- Atención con Flatpak (Linux): por defecto,
ai.storyteller.effectcraftsolo tiene acceso axdg-documents,xdg-picturesyxdg-videos. Si el proyecto reside en otro lugar (ej.~/.t3/projects/...), pasar--filesystem=<raíz_proyecto>o configurar el override:flatpak override --user --filesystem=home ai.storyteller.effectcraft - Conflicto GUI vs Headless: nunca abrir el mismo
.ecprojo.fcprojsimultáneamente en la aplicación gráfica y en MCP/CLI headless. Usar--bridgepara controlar una ventana abierta.
1. Reparto de roles: EffectCraft vs FilmCraft
| Ámbito | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| Uso principal | Escenas 2D animadas (V01..Vnn), letras en capas transparentes independientes (L01..Lnn), títulos cinéticos, partículas, compositing 2D/3D | Montaje principal multipista (V1 escenas + V2 letras RGBA + A1 audio master), sincronización a fotograma, transiciones, gradación global, doble exportación (con letras + clean) |
| Creación | comp.new, layer.newText, layer.newShape, layer.newSolid, layer.newAdjustment, add_effect, scripts JSX (ec_runtime.py) | file.newSequence, timeline.place, timeline.setTrack, timeline.razor, timeline.trim, timeline.move, clip.speedDuration |
| Sincronización musical | Referencias exactas de audio/lyrics_timing.json + escucha al oído; opcionalmente keys.audioToKeyframes solo si se desea un efecto reactivo medido | markers.add en cada sección, último acento y corte a negro; calado exacto al fotograma (frame: f0) |
| Estilización y Colorimetría | Estilos de capa, máscaras, Bézier, brillos, sombras paralelas, precomposiciones (layer.precompose) | Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition |
| Audio | Sin audio exportado en los renders intermedios (--audio off) | Pista master original en A1 (dejada a 0.0 dB por defecto para preservar el master original; essentialSound.* o sequence.normalizeMixTrack solo bajo demanda) |
2. Pipeline de intercambio de archivos y coherencia técnica
Convención de carpetas del proyecto
<project_root>/
├── audio/ # Pista master (WAV/FLAC/MP3) + lyrics_timing.json (fuente única editable)
├── footage/ # Metraje de vídeo, fotos, logos eventuales
├── renders_vfx/ # Renders intermedios EffectCraft: V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/ # Capturas PNG (render-frame) + MP4 cortos de previsualización con sonido (ej. estribillo, solo)
├── projects/ # Archivos .ecproj y .fcproj
├── scripts/ # Generadores específicos del clip (importante: herramientas compartidas T3 Code)
└── exports/ # Entregables finales 1080p: *_lyrics.mp4 y *_clean.mp4
Formatos de intercambio compatibles
- Letras y Overlays con transparencia (
V2) desde EffectCraft → FilmCraft:- Recomendado (archivo único): QuickTime Apple ProRes 4444 (
.mov),format: "prores",proresProfile: "4444",channels: "rgba",audio: "off". - Alternativa sin pérdida: Secuencia PNG o OpenEXR (
channels: "rgba"), importada en FilmCraft conimage_sequence: true. - Prohibido para alfa:
H264,HevcyAv1no gestionan el canal alfa (alpha: false).
- Recomendado (archivo único): QuickTime Apple ProRes 4444 (
- Escenas visuales opacas (
V1) desde EffectCraft:format: "prores",proresProfile: "hq",channels: "rgb",audio: "off".
- Entrega final desde FilmCraft:
- Web/Difusión:
format: "h264"(.mp4, preset"High Quality 1080p HD"). - Master archivo:
format: "prores". (Nota: en Linux sin codificador hardware,hevcyav1pueden no estar disponibles.)
- Web/Difusión:
Alineación de resolución, cadencia (FPS) y colorimetría
- Fijar desde el inicio un par único
(width, height, fps)compartido entre EffectCraft (comp.new) y FilmCraft (file.newSequence), ej.1920×1080a30o24fps. - Secciones alineadas al fotograma: calcular cada límite de sección en número entero de fotogramas (
f0 / fps .. f1 / fps) para que la suma de las secciones cubra exactamente la duración real de la pista de audio sin desviación ni hueco. - Espacio de color:
workingSpace: "rec709"en SDR en ambos programas (file.projectSettingsen EffectCraft,sequence.colorSettingsen FilmCraft;autoToneMap: truesi el metraje es HDR/Log). - Conversión de tiempo: EffectCraft trabaja en segundos (
f64); FilmCraft usa ticks (254016000000ticks =1s) y también aceptaframe/secondsentimeline.place.
3. Método musical clave (Sincronización al oído, Timing editable, Letras independientes e Instrumentales)
A. Sincronización al oído y medición exacta del final en el master de audio
- Siempre medir la pista original a 44,1 kHz (
hop = 441= 10,000 ms exactos) medianteaudio_cues.py analyze(nunca usar un paso redondeado a 22,05 kHz que crea una deriva de varios cientos de milisegundos en 3 minutos). - Verificar el final exacto en el MP3/WAV antes de fijar el montaje: localizar el último acento fuerte, el último golpe de batería/instrumento (ej. corte a negro) y el final real de la reverberación hasta el silencio final.
- Escuchar realmente la pista por tramos: dividir la pieza en tramos que se solapen (ej. 18 s con 2 s de solapamiento) y luego extractos cortos alrededor de las transiciones, estribillos, coros y finales de frases (
audio_cues.py slice) y escucharlos para fijar el BPM exacto y cada entrada vocal al oído.
B. Archivo único de timing editable (audio/lyrics_timing.json) y marcas dudosas
Centralizar todo el timing de las letras en un único archivo JSON editable a mano (audio/lyrics_timing.json), releído por el generador EffectCraft:
meta: archivo de audio, duración audio/vídeo en ms,fps,bpm,first_drum_hit_ms,last_accent_ms,black_cut_ms.sections: límitesstart_ms/end_msalineados al fotograma.phrases:start_ms,end_msydisplay_end_ms(prolongado de+250a+600 mssi es necesario para que la última palabra sea legible incluso si el plano o la sección cambia).type: "lead"para la voz principal ytype: "echo"en entradas separadas para los coros, respuestas y ad-libs.words(división por palabras/grupos) solo donde se necesite una animación o un acento visual; de lo contrario, mostrar la frase completa correctamente."uncertain": true+"review_note": "..."en cualquier marca ambigua (coros, ecos, vocalizaciones superpuestas, gritos breves) para permitir al usuario reajustarlas fácilmente a mano sin tocar el código.
C. Letras en una capa independiente (V2 RGBA) y doble exportación Master / Clean
- Sin banda negra permanente: colocar cada frase en el espacio libre del plano (ver craft-2d-animation §5), con sombra paralela suave, márgenes de seguridad y continuidad automática (
isContIn/isContOut) cuandodisplay_end_msatraviesa un corte de sección. - Pista transparente dedicada: generar las letras en composiciones separadas
L01..Lnn(omitiendo las secciones puramente instrumentales) renderizadas en ProRes 4444 RGBA y colocadas enV2en FilmCraft. - Conservar el texto del decorado en
V1: carteles, pantallas, copias, tableros permanecen en las escenasV01..Vnn. - Doble exportación rigurosamente idéntica: exportar la versión con letras (
V2activada), luego desactivarV2(timeline.setTrack {"track": "V2", "enabled": false}) para exportar la versión clean con montaje y audio 100 % idénticos, luego reactivarV2antes del guardado final del.fcproj.
D. Acciones visuales durante los pasajes instrumentales (Cero curvas de audio genéricas)
- Prohibir las muletas visuales genéricas: sin curvas de audio, sin zigzags de osciloscopio, sin círculos flotantes decorativos en intros, solos o interludios.
- Coreografiar acciones dibujadas sobre acentos elegidos al oído: una puerta que se cierra de golpe, una serie de lámparas de techo que se encienden una a una, un decorado que se despliega en cartón/papel 3D sobre los riffs, un objeto que se desliza o un personaje que cambia de pose con anticipación y mantenimiento.
- Mantener los planos entre los acentos: dejar una imagen clara y estable entre dos tiempos fuertes para que la acción siga siendo legible.
- Aplicar las reglas 2D comunes: encuadres variados (plano general / OTS / perfil / primer plano), siluetas completas, jerarquía de anclas neutras antes de la transformación (ver craft-2d-animation).
4. Workflow paso a paso
Paso 1 — Análisis de audio al oído y esqueleto de timing
- Sondear el master (
audio_cues.py analyze) a 44,1 kHz para obtener la duración exacta, los transitorios de 10 ms y el detalle del final de la pista. - Extraer tramos de escucha (
audio_cues.py slice) y escucharlos para fijar el BPM exacto, los límites de las secciones alineados a los fotogramas, las frases, los ecos y el corte final. - Inicializar y rellenar
audio/lyrics_timing.jsonmarcando las marcas dudosas con"uncertain": true+"review_note", luego validar el JSON (lyrics_overlay.py --validate).
Paso 2 — Guion gráfico / Storyboard breve (antes de cualquier render grande)
- Redactar un plan de montaje breve (tabla tiempo / sección / lugar y encuadre / acción visual dibujada / tratamiento de las letras).
- Presentar el desglose (y las elecciones de acentos para los pasajes instrumentales) al usuario antes de lanzar renders completos.
Paso 3 — Creación de las escenas (V01..Vnn) y letras (L01..Lnn) en EffectCraft
- Construir las escenas 2D (
V01..Vnn) siguiendo las reglas de anclas, parenting neutro y apilamiento de craft-2d-animation (usandoec_runtime.py). - Generar las composiciones de letras transparentes (
L01..Lnn, excluyendo instrumentales) directamente desdeaudio/lyrics_timing.jsonmediantelyrics_overlay.py. - Control rápido con capturas (
render-frame --max-side 960) en los planos clave (y--transparenten las letras) para corregir inmediatamente cualquier solapamiento o desajuste de ancla antes del render de vídeo. - Previsualizaciones MP4 cortas con sonido (ej. 1 estribillo + 1 solo): renderizar solo estas 1–2 secciones, multiplexar con el extracto exacto del master de audio, mirarlas y escucharlas para reajustar si es necesario las entradas de ecos, el mantenimiento de la última palabra entre planos y la legibilidad del solo.
- Render completo de bajo consumo hacia
./renders_vfx/medianterender_ec_batch.sh(secuencial 1 render a la vez, ProRes HQ RGB paraV*, ProRes 4444 RGBA paraL*, reanudación automática conffprobe). - Guardar
projects/<clip>.ecproj.
Paso 4 — Ensamblaje y doble exportación en FilmCraft
- Ensamblar la secuencia Rec.709 mediante
assemble_filmcraft.py(o vía MCPfile.newProject,file.newSequence,media_import,timeline.place,markers.add):A1: master de audio original intacto (volumeDb: 0.0)V1:V01..Vnn.movcolocados en su fotograma exacto (frame: f0)V2:L01..Lnn.mov(ProRes 4444 RGBA) colocados en los mismos fotogramas exactos (audio: false)
- Verificar la secuencia (
inspect sequence) + renderizar algunos fotogramas compuestosV1+V2yV1solo para confirmar el corte alfa y la presencia del texto diegético en la versión clean. - Exportar la versión con letras (
*_lyrics.mp4), desactivarV2, exportar la versión clean (*_clean.mp4), luego reactivarV2y guardarprojects/<clip>.fcproj.
Paso 5 — Auditoría final obligatoria (Con sonido + Sin sonido)
- Control CON sonido sobre la exportación
*_lyrics.mp4: verificar los finales de frases, los cortes de estribillos, la entrada de los ecos, el corte a negro exacto y el final limpio de la pista de audio original. - Control SIN sonido (mudo) sobre los pasajes instrumentales (solo, interludio) desde
*_clean.mp4: verificar que el objetivo del personaje y la progresión visual sean 100 % comprensibles sin audio, sin ninguna curva de audio residual y con el texto del decorado intacto. - Presentar los entregables y enumerar explícitamente las marcas marcadas como
"uncertain": trueenlyrics_timing.json.
5. Herramientas compartidas T3 Code y dependencias
Las herramientas reutilizables se encuentran en ~/.t3/shared/craft-video/:
| Herramienta | Ruta | Uso en clip musical |
|---|---|---|
| Análisis y división de audio 44,1 kHz | ~/.t3/shared/craft-video/audio_cues.py | analyze, slice |
| Generador de letras desde JSON | ~/.t3/shared/craft-video/lyrics_overlay.py | Valida, genera composiciones |
| Script de render por lotes | ~/.t3/shared/craft-video/render_ec_batch.sh | Render secuencial con ffprobe |
| Ensamblaje de FilmCraft | ~/.t3/shared/craft-video/assemble_filmcraft.py | Colocación automática en línea de tiempo |
| Utilitario de fotogramas | ~/.t3/shared/craft-video/audio_cues.py + lyrics_timing.json | Cálculo de fotogramas |
6. Comandos útiles (resumen rápido)
# --- EffectCraft (ec_runtime.py) ---
# Crear composición
comp.new width=1920 height=1080 fps=30 duration=10.0 name="V01"
# Añadir capa de texto
layer.newText text="Ejemplo" font="Arial" fontSize=48
# Añadir efecto
effect.add name="Drop Shadow"
# Renderizar fotograma (previsualización)
render-frame project="proyecto.ecproj" comp="L01" max-side=960 transparent=true
# --- FilmCraft (MCP) ---
# Nuevo proyecto
file.newProject path="proyecto.fcproj"
# Nueva secuencia
file.newSequence name="Montaje principal" width=1920 height=1080 fps=30
# Importar medios
media_import file="renders_vfx/V01.mov"
# Colocar en línea de tiempo
timeline.place clip="V01" track="V1" frame=0
# Añadir marcador
markers.add label="Estribillo" frame=240
# Exportar
export sequence="Montaje principal" preset="High Quality 1080p HD" output="exports/clip_lyrics.mp4"
7. Notas importantes
- Siempre verificar la configuración de Flatpak antes de comenzar un nuevo proyecto para evitar problemas de permisos de archivos.
- Nunca ejecutar renders paralelos desde EffectCraft: usar
render_ec_batch.shque procesa secuencialmente. - Mantener el audio original intacto en
A1a0.0 dBa menos que se solicite explícitamente un procesamiento. - Validar
lyrics_timing.jsonconlyrics_overlay.py --validateantes de generar composiciones de letras. - Realizar la previsualización auditiva de cada tramo para confirmar la sincronización al oído, especialmente en ecos y cortes rápidos.
- Documentar las marcas dudosas con
uncertain: truepara facilitar la revisión manual por parte del usuario.