Communitygithub.com

yazzang-homelab/motion-studio

Puntúa una película en su cuadrícula rítmica: mide una pista (beats.mjs) o sintetiza una (score.mjs), añade efectos de sonido (SFX) desde la película, agrega voz, mezcla a -14 LUFS / -1 dBTP con duración exacta. Útil para 'añadir música', 'sincronizar con el ritmo', 'SFX', 'sonoridad'.

¿Qué es motion-studio?

Este skill de Motion Studio permite diseñar la banda sonora completa de una película generada por código, sincronizando música, efectos de sonido y voz con una cuadrícula rítmica. Soporta dos flujos de trabajo principales: medir el tempo y los tiempos de una pista de audio proporcionada por el usuario (utilizando un motor JS incorporado o, si está disponible, Python/librosa) o sintetizar música original en estilos como pulso, piano, minimalista o cinematográfico. El skill expone una API de cuadrícula (`grid`) a la película para que escenas, transiciones y animaciones se alineen perfectamente con los tiempos de los beats, acentos y compases. También incluye herramientas para generar efectos de sonido deterministas, superponer locuciones (a través de ElevenLabs) y mezclar todas las pistas cumpliendo con los objetivos profesionales de sonoridad integrada de -14 LUFS y pico verdadero de -1 dBTP. El skill está diseñado para Claude Code, Cursor y Codex, y maneja archivos de proyecto, metadatos y almacenamiento en caché para garantizar flujos de trabajo eficientes y reproducibles.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/sound-design

Preguntar en tu IA favorita

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

Documentación

Diseño de sonido (paso 09 del curso)

El sonido es donde un clip dibujado con código empieza a sentirse como una película. Una línea de tiempo impulsa tres carriles: los tiempos fuertes transportan los cambios de escena, los beats transportan los efectos de sonido y los picos de ataque medidos colocan los acentos exactamente. Dos caminos: si el usuario proporciona una pista, mídela y úsala sin cambios; si no, sintetiza música original en la misma cuadrícula que la imagen.

Trabaja en la raíz del proyecto de la película. Argumentos, mostrados una vez:

Los detalles de la mezcla se encuentran en ${CLAUDE_SKILL_DIR}/references/mixing.md (references/mixing.md).

1. Música: medir o sintetizar

SituaciónComandoResultado
el usuario proporcionó una pistanpm run beats -- audio/track.wav (cualquier formato que ffmpeg decodifique)audio/beats.json con bpm, beats, downbeats, hits medidos
tempo ambiguo (mitad o doble)npm run beats -- audio/track.wav --bpm-hint 120búsqueda de tempo sesgada hacia la pista (30 a 300). Sin una pista, el motor JS busca de 70 a 180 BPM, por lo que una pista de 60 BPM se lee como 120; con una pista, la ventana se amplía (pistas de 45, 60, 65, 200 y 250 recuperan el tempo real)
sin Python / librosanpm run beats -- audio/track.wav --engine jsanálisis JS incorporado (flujo espectral, autocorrelación, seguimiento de beats). --engine auto (el valor predeterminado) recurre a él por sí solo, también cuando MOTION_PYTHON apunta a un intérprete roto (registra MOTION_PYTHON=... no es utilizable y continúa); --engine librosa se detiene con ese mensaje
sin pista: sintetizarnpm run score -- --style pulse --bpm 120 --dur 12audio/music.wav + un audio/beats.json analítico (fuente grid)

Para una pista proporcionada, establece studio.json audio.music en su ruta (por ejemplo, "audio/track.wav") y bpm en el valor medido. Luego nunca ejecutes npm run score directamente: escribe en audio.music (sobrescribiendo la pista) y reemplaza beats.json con una cuadrícula sintética. npm run build es seguro porque llama a score.mjs --if-missing, lo que mantiene una pista proporcionada o reemplazada (su hash no coincide con audio/music.meta.json). Confirma que el usuario tiene derecho a usar la pista (licencia o propiedad) y anótalo en las notas de docs/production.json.

Opciones de Score (node tools/score.mjs):

IndicadorValoresNotas
--stylepulse (bombo 4/4, palmas, hi-hats, sub-bajo, arpegio de punteo) · piano (piano apagado, percusión escasa) · minimal (tics, clics, golpe suave; películas de interfaz de usuario) · cinematic (golpes similares a taikos, ostinato arqueado, explosiones en tiempos fuertes)sin pads genéricos estáticos en ningún estilo
--bpm, --durnúmerosvalores predeterminados de studio.json
--key, --modeA, F#, Bb ... (una m final significa menor), minor / majormenor i-VI-III-VII, mayor I-V-vi-IV
--drop BARíndice de compáspredeterminado alrededor del 40% de la duración, crescendo hasta el drop
--loopindicadorbucle sin fisuras: sin introducción ni final, sin drop, las colas vuelven al inicio; valor predeterminado de studio.json loop. Usa una duración que sea un número entero de compases, o la herramienta advierte que el empalme no coincide con un tiempo fuerte
--seed Nenteromisma semilla, mismos bytes
--if-missingindicadorusado por npm run build: conserva un WAV existente que es una pista proporcionada, o una partitura cuyos ajustes aún coinciden con audio/music.meta.json; regenera (WAV, beats.json, archivo complementario) una partitura que score.mjs creó cuando duration, bpm, estilo, tono, modo, semilla, bucle o compás de drop cambiaron, y dice qué cambió (regenerated en el JSON)

Cada ejecución también escribe audio/music.meta.json (los ajustes resueltos más el sha256 del WAV): así es como --if-missing distingue una partitura que creó a partir de una pista que proporcionaste o reemplazaste, a la que nunca toca.

Las claves opcionales de studio.json audio completan las mismas opciones cuando el indicador está ausente (un indicador gana): style (la plantilla incluye "pulse"), key, mode, seed; voiceId es la voz predeterminada de ElevenLabs para voice.mjs. Ejemplo: "audio": { "style": "cinematic", "key": "D", "mode": "minor", "seed": 7 }.

Los cuatro estilos son pulse, piano, minimal y cinematic. El arreglo comienza con un compás escaso, se construye, entra en un drop en un tiempo fuerte y aterriza un golpe final en el último tiempo fuerte que termina al menos 0.5 s antes de que termine la película, luego una cola de decaimiento; con --loop es un ritmo constante que se pliega sobre sí mismo en lugar de eso. La duración es exactamente la duración de la película.

Notas de beats.json: los resultados se almacenan en caché mediante el sha256 del audio en audio/.cache/, por lo que las re-ejecuciones del mismo audio son instantáneas (--no-cache para forzar). Librosa tiene un arranque en frío: la primera ejecución en un entorno Python nuevo tarda aproximadamente un minuto (numba compila), las ejecuciones posteriores son rápidas. No interpretes ese minuto como un bloqueo; --engine js omite Python. Los tiempos fuertes se eligen puntuando las cuatro fases del beat en los inicios de baja frecuencia, porque "cada 4º beat" está desviado por un beat cuando una canción comienza con un anacrusa. El silencio da una lista de beats vacía con una advertencia; la página entonces recurre a la cuadrícula de BPM.

2. Imagen en la cuadrícula

La película recibe la cuadrícula como ctx.grid (fábrica) y c.grid (dibujo de escena). Se mide cuando audio/beats.json existe, de lo contrario es uniforme en studio.json bpm.

LlamadaDevuelve
grid.beat(n)tiempo del beat n (se permite n fraccionario: beat(4.5) es una corchea después)
grid.bar(n)tiempo del tiempo fuerte n (inicios de compás)
grid.index(t) / grid.nearest(t)índice de beat en t / tiempo del beat más cercano
grid.beatsIn(a, b) / grid.barsIn(a, b)tiempos de beats o compases dentro de [a, b)
grid.isOnBeat(t, tol = 0.02)si t está dentro de tol segundos de un beat
grid.hitspicos de ataque medidos en segundos: congelados, ordenados, deduplicados, dentro de [0, duración); [] cuando la pista no tiene ninguno
grid.hitsIn(a, b)los hits dentro de [a, b), la misma ventana que beatsIn

Reglas: cambios de escena y cambios de estado en tiempos fuertes (grid.bar(n)); acciones de UI, pops y clics en beats; grandes acentos en hits medidos cuando se proporciona una pista. Deriva cada tiempo de la cuadrícula; nunca escribas un tiempo que la cuadrícula pueda darte, o la imagen se desvía cuando la pista o el tempo cambian. Con una pista medida, grid.bar(0) es el primer tiempo fuerte medido, que puede situarse mucho después de 0 s (un anacrusa o una introducción), por lo que los intervalos escritos como compases se mueven con él.

Los hits medidos (picos de ataque, hits en audio/beats.json) llegan a la película como grid.hits y grid.hitsIn(a, b), en la fábrica (ctx.grid) y en cada dibujo de escena (c.grid). Están disponibles incluso cuando la pista no tiene beats rastreados. No obtengas audio/beats.json tú mismo; la cuadrícula ya lo lleva:

// en las cues de la fábrica: acentos medidos entre los segundos 8 y 10
cues: (grid) => [...grid.hitsIn(8, 10).map((t) => ({ t, type: 'snap', gain: 0.5 }))],

Una partitura sintetizada escribe solo sus acentos principales en hits (por ejemplo, el drop y el golpe final).

3. Las cues provienen de la película

Declara las cues junto a la imagen a la que pertenecen, en las cues de la fábrica (un array o una función de la cuadrícula):

export default defineFilm((ctx) => ({
  scenes: [/* ... */],
  cues: (grid) => [
    ...[0, 1, 2, 3, 4].map((n) => ({ t: grid.bar(n), type: 'thump' })),       // cambios de escena en tiempos fuertes
    { t: grid.bar(1), type: 'whoosh', gain: 0.6 },                             // transición a la escena 2: el pico aterriza en el corte
    { t: grid.beat(6), type: 'click', pan: 0.2 },                              // pulsación del cursor en un beat
    ...[0, 1, 2, 3, 4, 5, 6, 7].map((i) => ({ t: grid.beat(8) + i * 0.06, type: 'pop', gain: 0.5, pitch: 1 + i * 0.03 })),
    { t: grid.bar(4), type: 'riser' },                                         // un crescendo COMIENZA en su cue ...
    { t: grid.bar(5), type: 'hit' },                                           // ... y llega en el siguiente hit/thump/snap
  ],
}));

Campos de cue: t (segundos), type, gain (1), pan (-1 a 1, 0), pitch (multiplicador de velocidad de reproducción, 1). Se aceptan alias sfx para type y vol para gain. Las cues en tiempos negativos o no finitos se descartan. Tipos (SFX_TYPES): click tick pop thump whoosh swoosh riser hit chime type glitch snap.

Semántica de ancla: t es el momento en que el sonido aterriza, no donde comienza la muestra. node tools/sfx.mjs --list imprime cada voz con su duración y ancla.

TipoLo que aterriza en tUso
click, tick, pop, thump, hit, chime, type, snapel transitorio (el sonido comienza unos milisegundos antes)el evento visual: una pulsación, una entrada, un bloqueo
glitchsu primer fragmento: comienza en tuna rotura digital, en el fotograma en que aparece
whoosh, swooshel pico de paso (0.31 s y 0.20 s después del inicio del sonido), por lo que el barrido se acumula antes de tcolócalo en el corte o en el movimiento que transporta
riserno aterriza nada: comienza en t y crece hasta la siguiente cue hit, thump o snap entre 0.4 y 4 s después, por lo que llega a ese impacto; sin tal cue en el rango, dura 1.6 scolócalo un compás o un beat antes del impacto, nunca en él

Un crescendo en el mismo tiempo que su hit no encuentra una cue de aterrizaje (necesita una más de 0.35 s después) y se ejecuta 1.6 s más allá del impacto en lugar de hacerlo hacia él. Coloca la cue del crescendo antes, en grid.bar(n - 1) para un hit en grid.bar(n).

Los pops escalonados como el ejemplo de mosaico anterior son cues intencionales fuera del beat; la métrica de sincronización los enumera, lo cual está bien siempre que cada uno se asiente en su evento visual.

4. Efectos de sonido (SFX)

npm run sfx                         # abre la película sin cabeza, lee __studio.cues(), escribe audio/cues.json + audio/sfx.wav
node tools/sfx.mjs --dump-cues      # solo escribe audio/cues.json (verifica los tiempos antes de sintetizar)
node tools/sfx.mjs --cues my.json   # sintetiza a partir de un archivo de cues editado manualmente en lugar de la película

Cada voz se sintetiza de forma determinista (semilla por cue a partir del tipo de cue, el tiempo y su rango entre cues idénticas, más --seed, por lo que agregar, eliminar o reordenar otras cues deja el sonido de esta cue sin cambios), se panea con potencia igual, se suma en un bus flotante, se limita a -1 dBFS, y el archivo tiene exactamente la duración de la película (las cues vacías dan silencio de esa longitud; en una película en bucle, una cola que se extiende más allá del final vuelve al inicio). Para usar muestras grabadas en su lugar, coloca audio/samples/<type>.wav (también .flac, .mp3, .ogg) en el proyecto: esto reemplaza la voz sintetizada para ese tipo (--samples none o --no-samples ignora la carpeta durante una ejecución). El pico más alto del archivo es su ancla, y un crescendo muestreado se cronometra para que este pico aterrice en la llegada. Las muestras necesitan una licencia de uso comercial: tus propias grabaciones, CC0 o una licencia que tengas para una película publicada. Las licencias de solo atribución (CC BY) necesitan el crédito en la publicación; los paquetes de uso No Comercial y "personal use" están descartados. Registra la fuente y la licencia en las notas de docs/production.json.

5. Voz (opcional, ElevenLabs)

  1. La clave va en .env como ELEVENLABS_API_KEY=... (nunca en un aviso, un archivo que hayas confirmado o una captura de pantalla). Refiérete a ella por su nombre: "la clave de ElevenLabs es ELEVENLABS_API_KEY en .env".
  2. Escribe audio/voice.json: [{ "t": 0.5, "text": "Conoce a Driftnote." }, { "t": 4.0, "text": "Notas que se archivan solas." }] (opcionalmente voiceId por línea). Coloca las líneas en tiempos fuertes y deja espacio para ellas en la imagen.
  3. node tools/voice.mjs --dry-run imprime el plan y el recuento de caracteres (sin red, sin costo). Muéstralo al usuario si el presupuesto es importante. Una línea con el mismo texto, id de voz y modelo que una anterior se sintetiza y factura una vez (la ejecución en seco la marca repeat; billableChars cuenta solo caracteres únicos).
  4. node tools/voice.mjs --voice-id <id> sintetiza (almacenado en caché por línea en audio/.cache/), coloca cada línea en su t y escribe audio/voice.wav con la longitud exacta de la película.
  5. Establece studio.json audio.voice en "audio/voice.wav" después de que voice.mjs haya escrito el archivo (voice.mjs imprime el recordatorio pero no edita studio.json). Mientras audio.voice sea null, la mezcla ignora la voz; con este valor establecido, mix.mjs atenúa la música debajo de la voz (duck: true). audio.voiceId es la voz predeterminada para líneas sin su propio voiceId.

6. Mezclar y verificar

npm run mix                                   # todos los formatos: out/score.wav + out/<fmt>/final.mp4 + out/final.mp4
node tools/critique.mjs --format 9x16 --video out/9x16/final.mp4    # evidencia en out/review/9x16/video/

mix tarda de 40 a 80 s: inícialo en segundo plano y consulta el registro cuando la película sea larga o la máquina esté ocupada (nunca esperes en primer plano más de aproximadamente 2 minutos).

Antes de mezclar, mix.mjs decodifica y mide cada pista. Una pista de música, voz o efectos de sonido que sea más corta que la película en más de 0.25 s, esté vacía o en silencio (pico por debajo de -80 dBFS) detiene la mezcla con refusing to mix: ... stem problem(s) do not fit the N s film y no escribe nada: un music.wav obsoleto de una duración anterior solía mezclarse como cola silenciosa. Regenera la pista (npm run score, npm run sfx, npm run voice); para una voz en off o un jingle que se supone que es corto, pasa --allow-short-stems (la parte faltante es silencio). Una pista de SFX silenciosa solo advierte, porque una película sin cues renderiza silencio; una pista más larga que la película advierte que su final se corta sin fundido. El resultado JSON lleva stemInfo (duración decodificada y pico por pista).

Objetivos: -14 LUFS integrados +-0.5, pico verdadero en o por debajo de -1 dBTP, duración de audio igual a la duración del video (nunca -shortest). --lufs (o audio.lufs) debe ser de -70 a -5, --tp (o audio.truePeak) de -20 a 0; por debajo de -9 dBTP, la ruta del limitador aplica el techo, y una mezcla con picos que no puede alcanzar la sonoridad con un techo bajo termina en la advertencia master misses the target en lugar de un bloqueo. mix.mjs usa loudnorm de dos pasadas y mantiene su resultado lineal solo cuando la maestra aterriza dentro de la mitad de la tolerancia del objetivo (+-0.25 LU por defecto); de lo contrario, recurre a la ganancia más un limitador sobremuestreado que apunta a +-0.1 LU, luego vuelve a medir el AAC multiplexado. Cuando un número está mal, la tabla de informe en references/mixing.md dice qué cambiar.

Verificación de sincronía: `metri

...

[truncado para traducción]

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

yazzang-homelab/motion-studio

Make Claude watch its own frames: critique.mjs evidence, harsh 7-axis scores, timestamped P0/P1/P2 problems in docs/review_log.md, fix the 3 worst, re-check, pass the gate. Use for 'critique it', 'review the frames', 'is it good'.

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Build, debug or speed up the seek(t) render engine: render contract, canvas vs page capture, workers/subframes/chunks, determinism fixes, Remotion or HyperFrames handoff. Use for 'render is slow', 'frames differ', 'use Remotion'.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

Skills relacionados