Communitygithub.com

craft-music-video

Muestra al agente cómo planificar, construir o editar un 'videoclip artesanal' para que el resultado concreto sea un movimiento que el agente pueda defender plano a plano. El procedimiento recorre la Creación Artesanal de Vídeos Musicales (`FilmCraft` + `EffectCraft`), 0. Prerrequisitos MCP y Sandbox (a verificar antes de empezar), 1. Reparto de roles: EffectCraft vs FilmCraft. Úsalo cuando un nuevo encargo requiera esta técnica.

¿Qué es craft-music-video?

Este skill proporciona un flujo de trabajo reutilizable y detallado para que un agente de IA (como Claude Code, Cursor o Codex) pueda producir vídeos musicales sincronizados con una pista de audio, combinando dos dominios principales: **EffectCraft** para escenas 2D, gráficos en movimiento, VFX y capas de letras con transparencia alfa independiente, y **FilmCraft** para la edición principal multipista, sincronización rítmica, mezcla y masterización de audio, gradación global y exportación doble (con y sin letras). El skill está diseñado para usarse con herramientas como MCP, scripts CLI y entornos sandbox (como Flatpak). Su utilidad principal es guiar al agente a través de un proceso de 5 pasos que incluye el análisis de audio a 44,1 kHz, la creación de un archivo de sincronización de letras editable (`lyrics_timing.json`), la generación de escenas animadas y capas de letras transparentes en EffectCraft, el montaje final y la exportación dual en FilmCraft con un riguroso control de calidad visual y auditivo. Las reglas clave incluyen evitar efectos visuales genéricos, priorizar la escucha real de la pista para la sincronización, mantener las letras en una capa independiente (V2) y realizar una verificación final tanto con sonido como sin él para garantizar la comprensión visual.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

Preguntar en tu IA favorita

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

Documentación

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)

  1. Verificar que los servidores MCP effectcraft y filmcraft estén expuestos en la sesión actual (o cambiar correctamente a los CLI effectcraft-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.effectcraft o binario nativo, en modo headless o bridge).
  2. Atención con Flatpak (Linux): por defecto, ai.storyteller.effectcraft solo tiene acceso a xdg-documents, xdg-pictures y xdg-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
  3. Conflicto GUI vs Headless: nunca abrir el mismo .ecproj o .fcproj simultáneamente en la aplicación gráfica y en MCP/CLI headless. Usar --bridge para controlar una ventana abierta.

1. Reparto de roles: EffectCraft vs FilmCraft

ÁmbitoEffectCraft (.ecproj)FilmCraft (.fcproj)
Uso principalEscenas 2D animadas (V01..Vnn), letras en capas transparentes independientes (L01..Lnn), títulos cinéticos, partículas, compositing 2D/3DMontaje 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óncomp.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 musicalReferencias exactas de audio/lyrics_timing.json + escucha al oído; opcionalmente keys.audioToKeyframes solo si se desea un efecto reactivo medidomarkers.add en cada sección, último acento y corte a negro; calado exacto al fotograma (frame: f0)
Estilización y ColorimetríaEstilos de capa, máscaras, Bézier, brillos, sombras paralelas, precomposiciones (layer.precompose)Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition
AudioSin 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 con image_sequence: true.
    • Prohibido para alfa: H264, Hevc y Av1 no gestionan el canal alfa (alpha: false).
  • 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, hevc y av1 pueden no estar disponibles.)

Alineación de resolución, cadencia (FPS) y colorimetría

  1. Fijar desde el inicio un par único (width, height, fps) compartido entre EffectCraft (comp.new) y FilmCraft (file.newSequence), ej. 1920×1080 a 30 o 24 fps.
  2. 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.
  3. Espacio de color: workingSpace: "rec709" en SDR en ambos programas (file.projectSettings en EffectCraft, sequence.colorSettings en FilmCraft; autoToneMap: true si el metraje es HDR/Log).
  4. Conversión de tiempo: EffectCraft trabaja en segundos (f64); FilmCraft usa ticks (254016000000 ticks = 1 s) y también acepta frame / seconds en timeline.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

  1. Siempre medir la pista original a 44,1 kHz (hop = 441 = 10,000 ms exactos) mediante audio_cues.py analyze (nunca usar un paso redondeado a 22,05 kHz que crea una deriva de varios cientos de milisegundos en 3 minutos).
  2. 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.
  3. 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ímites start_ms / end_ms alineados al fotograma.
  • phrases:
    • start_ms, end_ms y display_end_ms (prolongado de +250 a +600 ms si es necesario para que la última palabra sea legible incluso si el plano o la sección cambia).
    • type: "lead" para la voz principal y type: "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

  1. 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) cuando display_end_ms atraviesa un corte de sección.
  2. Pista transparente dedicada: generar las letras en composiciones separadas L01..Lnn (omitiendo las secciones puramente instrumentales) renderizadas en ProRes 4444 RGBA y colocadas en V2 en FilmCraft.
  3. Conservar el texto del decorado en V1: carteles, pantallas, copias, tableros permanecen en las escenas V01..Vnn.
  4. Doble exportación rigurosamente idéntica: exportar la versión con letras (V2 activada), luego desactivar V2 (timeline.setTrack {"track": "V2", "enabled": false}) para exportar la versión clean con montaje y audio 100 % idénticos, luego reactivar V2 antes del guardado final del .fcproj.

D. Acciones visuales durante los pasajes instrumentales (Cero curvas de audio genéricas)

  1. Prohibir las muletas visuales genéricas: sin curvas de audio, sin zigzags de osciloscopio, sin círculos flotantes decorativos en intros, solos o interludios.
  2. 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.
  3. Mantener los planos entre los acentos: dejar una imagen clara y estable entre dos tiempos fuertes para que la acción siga siendo legible.
  4. 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

  1. 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.
  2. 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.
  3. Inicializar y rellenar audio/lyrics_timing.json marcando 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)

  1. Redactar un plan de montaje breve (tabla tiempo / sección / lugar y encuadre / acción visual dibujada / tratamiento de las letras).
  2. 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

  1. Construir las escenas 2D (V01..Vnn) siguiendo las reglas de anclas, parenting neutro y apilamiento de craft-2d-animation (usando ec_runtime.py).
  2. Generar las composiciones de letras transparentes (L01..Lnn, excluyendo instrumentales) directamente desde audio/lyrics_timing.json mediante lyrics_overlay.py.
  3. Control rápido con capturas (render-frame --max-side 960) en los planos clave (y --transparent en las letras) para corregir inmediatamente cualquier solapamiento o desajuste de ancla antes del render de vídeo.
  4. 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.
  5. Render completo de bajo consumo hacia ./renders_vfx/ mediante render_ec_batch.sh (secuencial 1 render a la vez, ProRes HQ RGB para V*, ProRes 4444 RGBA para L*, reanudación automática con ffprobe).
  6. Guardar projects/<clip>.ecproj.

Paso 4 — Ensamblaje y doble exportación en FilmCraft

  1. Ensamblar la secuencia Rec.709 mediante assemble_filmcraft.py (o vía MCP file.newProject, file.newSequence, media_import, timeline.place, markers.add):
    • A1: master de audio original intacto (volumeDb: 0.0)
    • V1: V01..Vnn.mov colocados en su fotograma exacto (frame: f0)
    • V2: L01..Lnn.mov (ProRes 4444 RGBA) colocados en los mismos fotogramas exactos (audio: false)
  2. Verificar la secuencia (inspect sequence) + renderizar algunos fotogramas compuestos V1+V2 y V1 solo para confirmar el corte alfa y la presencia del texto diegético en la versión clean.
  3. Exportar la versión con letras (*_lyrics.mp4), desactivar V2, exportar la versión clean (*_clean.mp4), luego reactivar V2 y guardar projects/<clip>.fcproj.

Paso 5 — Auditoría final obligatoria (Con sonido + Sin sonido)

  1. 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.
  2. 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.
  3. Presentar los entregables y enumerar explícitamente las marcas marcadas como "uncertain": true en lyrics_timing.json.

5. Herramientas compartidas T3 Code y dependencias

Las herramientas reutilizables se encuentran en ~/.t3/shared/craft-video/:

HerramientaRutaUso en clip musical
Análisis y división de audio 44,1 kHz~/.t3/shared/craft-video/audio_cues.pyanalyze, slice
Generador de letras desde JSON~/.t3/shared/craft-video/lyrics_overlay.pyValida, genera composiciones
Script de render por lotes~/.t3/shared/craft-video/render_ec_batch.shRender secuencial con ffprobe
Ensamblaje de FilmCraft~/.t3/shared/craft-video/assemble_filmcraft.pyColocación automática en línea de tiempo
Utilitario de fotogramas~/.t3/shared/craft-video/audio_cues.py + lyrics_timing.jsonCá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

  1. Siempre verificar la configuración de Flatpak antes de comenzar un nuevo proyecto para evitar problemas de permisos de archivos.
  2. Nunca ejecutar renders paralelos desde EffectCraft: usar render_ec_batch.sh que procesa secuencialmente.
  3. Mantener el audio original intacto en A1 a 0.0 dB a menos que se solicite explícitamente un procesamiento.
  4. Validar lyrics_timing.json con lyrics_overlay.py --validate antes de generar composiciones de letras.
  5. Realizar la previsualización auditiva de cada tramo para confirmar la sincronización al oído, especialmente en ecos y cortes rápidos.
  6. Documentar las marcas dudosas con uncertain: true para facilitar la revisión manual por parte del usuario.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados