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ón | Comando | Resultado |
|---|---|---|
| el usuario proporcionó una pista | npm 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 120 | bú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 / librosa | npm run beats -- audio/track.wav --engine js | aná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: sintetizar | npm run score -- --style pulse --bpm 120 --dur 12 | audio/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):
| Indicador | Valores | Notas |
|---|---|---|
--style | pulse (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, --dur | números | valores predeterminados de studio.json |
--key, --mode | A, F#, Bb ... (una m final significa menor), minor / major | menor i-VI-III-VII, mayor I-V-vi-IV |
--drop BAR | índice de compás | predeterminado alrededor del 40% de la duración, crescendo hasta el drop |
--loop | indicador | bucle 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 N | entero | misma semilla, mismos bytes |
--if-missing | indicador | usado 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.
| Llamada | Devuelve |
|---|---|
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.hits | picos 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.
| Tipo | Lo que aterriza en t | Uso |
|---|---|---|
click, tick, pop, thump, hit, chime, type, snap | el transitorio (el sonido comienza unos milisegundos antes) | el evento visual: una pulsación, una entrada, un bloqueo |
glitch | su primer fragmento: comienza en t | una rotura digital, en el fotograma en que aparece |
whoosh, swoosh | el 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 t | colócalo en el corte o en el movimiento que transporta |
riser | no 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 s | coló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)
- La clave va en
.envcomoELEVENLABS_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". - Escribe
audio/voice.json:[{ "t": 0.5, "text": "Conoce a Driftnote." }, { "t": 4.0, "text": "Notas que se archivan solas." }](opcionalmentevoiceIdpor línea). Coloca las líneas en tiempos fuertes y deja espacio para ellas en la imagen. node tools/voice.mjs --dry-runimprime 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 marcarepeat;billableCharscuenta solo caracteres únicos).node tools/voice.mjs --voice-id <id>sintetiza (almacenado en caché por línea enaudio/.cache/), coloca cada línea en suty escribeaudio/voice.wavcon la longitud exacta de la película.- Establece
studio.jsonaudio.voiceen"audio/voice.wav"después de quevoice.mjshaya escrito el archivo (voice.mjsimprime el recordatorio pero no editastudio.json). Mientrasaudio.voiceseanull, la mezcla ignora la voz; con este valor establecido,mix.mjsatenúa la música debajo de la voz (duck: true).audio.voiceIdes la voz predeterminada para líneas sin su propiovoiceId.
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]