Sounddesign (Kursschritt 09)
Sound ist der Punkt, an dem sich ein codegezeichneter Clip wie ein Film anfühlt. Eine Zeitachse steuert drei Spuren: Downbeats tragen Szenenwechsel, Beats tragen SFX, und gemessene Onset-Spitzen setzen die Akzente exakt. Zwei Pfade: Wenn der Benutzer einen Track bereitstellt, diesen messen und unverändert verwenden; wenn nicht, originäre Musik auf demselben Gitter wie das Bild synthetisieren.
Arbeiten Sie im Filmprojekt-Stammverzeichnis. Argumente, einmal gezeigt:
Die Mischungsdetails befinden sich in
${CLAUDE_SKILL_DIR}/references/mixing.md (references/mixing.md).
1. Musik: messen oder synthetisieren
| Situation | Befehl | Ergebnis |
|---|---|---|
| Benutzer hat einen Track bereitgestellt | npm run beats -- audio/track.wav (jedes Format, das ffmpeg dekodiert) | audio/beats.json mit gemessenen bpm, beats, downbeats, hits |
| Mehrdeutiges Tempo (halb oder doppelt) | npm run beats -- audio/track.wav --bpm-hint 120 | Temposuche zum Hinweis hin verzerrt (30 bis 300). Ohne Hinweis sucht die JS-Engine 70 bis 180 BPM, ein 60-BPM-Track wird also als 120 gelesen; mit Hinweis wird das Fenster breiter (Hinweise von 45, 60, 65, 200 und 250 finden das echte Tempo) |
| Kein Python / librosa | npm run beats -- audio/track.wav --engine js | Integrierte JS-Analyse (spektraler Fluss, Autokorrelation, Beat-Tracking). --engine auto (Standard) fällt selbstständig darauf zurück, auch wenn MOTION_PYTHON auf einen defekten Interpreter zeigt (es protokolliert MOTION_PYTHON=... is not usable und fährt fort); --engine librosa stoppt mit dieser Meldung |
| Kein Track: synthetisieren | npm run score -- --style pulse --bpm 120 --dur 12 | audio/music.wav + ein analytisches audio/beats.json (Quelle grid) |
Setzen Sie für einen bereitgestellten Track in studio.json audio.music auf seinen Pfad (z. B. "audio/track.wav") und bpm auf den gemessenen Wert. Führen Sie dann niemals einfach npm run score aus: Es überschreibt audio.music (überschreibt den Track) und ersetzt beats.json durch ein synthetisches Gitter. npm run build ist sicher, da es score.mjs --if-missing aufruft, was einen bereitgestellten oder ersetzten Track beibehält (sein Hash stimmt nicht mit audio/music.meta.json überein).
Bestätigen Sie, dass der Benutzer das Recht zur Nutzung des Tracks hat (Lizenz oder Eigentum) und vermerken Sie dies in den Notizen von docs/production.json.
Score-Optionen (node tools/score.mjs):
| Flag | Werte | Hinweise |
|---|---|---|
--style | pulse (Kick 4/4, Claps, Hi-Hats, Subbass, Pluck-Arp) · piano (Filzklavier, reduzierte Percussion) · minimal (Ticks, Klicks, sanfter Kick; UI-Filme) · cinematic (Taiko-ähnliche Hits, gestrichene Ostinati, Downbeat-Booms) | Keine statischen generischen Pads in irgendeinem Stil |
--bpm, --dur | Zahlen | Standard aus studio.json |
--key, --mode | A, F#, Bb ... (ein nachgestelltes m bedeutet Moll), minor / major | Moll i-VI-III-VII, Dur I-V-vi-IV |
--drop BAR | Taktnummer | Standard etwa 40 % der Länge, Riser hinein |
--loop | Flag | Nahtlose Schleife: kein Intro oder Ende, kein Drop, Enden wickeln sich zum Anfang zurück; Standard aus studio.json loop. Verwenden Sie eine Dauer, die eine ganze Anzahl von Takten beträgt, sonst warnt das Tool, dass die Naht einen Downbeat verpasst |
--seed N | Ganzzahl | Gleicher Seed, gleiche Bytes |
--if-missing | Flag | Von npm run build verwendet: Behalten einer vorhandenen WAV, die ein bereitgestellter Track oder ein Score ist, dessen Einstellungen noch mit audio/music.meta.json übereinstimmen; Neu generieren (WAV, beats.json, Sidecar) eines Scores, den score.mjs erstellt hat, als duration, bpm, Style, Tonart, Modus, Seed, Loop oder Drop-Takt sich geändert haben, und sagen, was sich geändert hat (regenerated im JSON) |
Jeder Lauf schreibt auch audio/music.meta.json (die aufgelösten Einstellungen plus den SHA256 der WAV): So erkennt --if-missing, ob es sich um einen Score handelt, den es aus einem von Ihnen bereitgestellten oder ersetzten Track erstellt hat – diesen berührt es niemals.
Optionale studio.json audio-Schlüssel füllen dieselben Optionen, wenn das Flag fehlt (ein Flag gewinnt): style (die Vorlage liefert "pulse"), key, mode, seed; voiceId ist die Standard-ElevenLabs-Stimme für voice.mjs. Beispiel: "audio": { "style": "cinematic", "key": "D", "mode": "minor", "seed": 7 }.
Die vier Stile sind pulse, piano, minimal und cinematic. Das Arrangement beginnt mit einem spärlichen Takt, baut auf, droppt auf einem Downbeat und landet einen letzten Hit auf dem letzten Downbeat, der mindestens 0,5 s vor Filmende endet, dann ein Auskling-Schwanz; mit --loop ist es ein gleichmäßiger Groove, der stattdessen auf sich selbst zurückfaltet. Die Länge entspricht exakt der Filmdauer.
beats.json Hinweise: Ergebnisse werden nach dem SHA256 des Audios in audio/.cache/ zwischengespeichert, sodass Wiederholungen desselben Audios sofort erfolgen (--no-cache zum Erzwingen). Librosa hat einen Kaltstart: Der erste Lauf in einer frischen Python-Umgebung dauert etwa eine Minute (numba kompiliert), spätere Läufe sind schnell. Lesen Sie diese Minute nicht als Hängenbleiben; --engine js überspringt Python.
Downbeats werden durch Bewertung der vier Beat-Phasen auf niederfrequenten Einsätzen ausgewählt, da "jeder 4. Schlag" um einen Schlag versetzt ist, wenn ein Song mit einem Auftakt beginnt. Stille erzeugt eine leere Beat-Liste mit einer Warnung; die Seite fällt dann auf das BPM-Raster zurück.
2. Bild im Raster
Der Film erhält das Raster als ctx.grid (Factory) und c.grid (Szenen-Zeichnung). Gemessen, wenn audio/beats.json existiert, sonst gleichmäßig bei studio.json bpm.
| Aufruf | Rückgabe |
|---|---|
grid.beat(n) | Zeitpunkt von Beat n (gebrochenes n erlaubt: beat(4.5) ist eine Achtelnote später) |
grid.bar(n) | Zeitpunkt von Downbeat n (Taktanfänge) |
grid.index(t) / grid.nearest(t) | Beat-Index bei t / Zeitpunkt des nächsten Beats |
grid.beatsIn(a, b) / grid.barsIn(a, b) | Beat- oder Taktzeiten innerhalb [a, b) |
grid.isOnBeat(t, tol = 0.02) | Ob t innerhalb von tol Sekunden eines Beats liegt |
grid.hits | Gemessene Akzent-Spitzen in Sekunden: eingefroren, sortiert, dedupliziert, innerhalb [0, duration); [] wenn der Track keine hat |
grid.hitsIn(a, b) | Die Hits innerhalb [a, b), dasselbe Fenster wie beatsIn |
Regeln: Szenenwechsel und Zustandsänderungen auf Downbeats (grid.bar(n)); UI-Aktionen, Pops und Klicks auf Beats; große Akzente auf gemessenen Hits, wenn ein Track bereitgestellt wird. Leiten Sie jede Zeit aus dem Raster ab; geben Sie niemals eine Zeit ein, die das Raster Ihnen geben kann, sonst driftet das Bild, wenn sich der Track oder das Tempo ändert. Bei einem gemessenen Track ist grid.bar(0) der erste gemessene Downbeat, der deutlich nach 0 s liegen kann (ein Auftakt oder Intro), daher verschieben sich als Takte geschriebene Spannen mit ihm.
Gemessene Hits (Onset-Spitzen, hits in audio/beats.json) erreichen den Film als grid.hits und grid.hitsIn(a, b), in der Factory (ctx.grid) und in jeder Szenen-Zeichnung (c.grid). Sie sind verfügbar, auch wenn der Track keine getrackten Beats hat. Rufen Sie audio/beats.json nicht selbst ab; das Raster trägt es bereits:
// in den Cues der Factory: gemessene Akzente zwischen Sekunde 8 und 10
cues: (grid) => [...grid.hitsIn(8, 10).map((t) => ({ t, type: 'snap', gain: 0.5 }))],
Ein synthetisierter Score schreibt nur seine Hauptakzente in hits (z. B. den Drop und den finalen Hit).
3. Cues kommen aus dem Film
Deklarieren Sie Cues neben dem Bild, zu dem sie gehören, in den cues der Factory (ein Array oder eine Funktion des Rasters):
export default defineFilm((ctx) => ({
scenes: [/* ... */],
cues: (grid) => [
...[0, 1, 2, 3, 4].map((n) => ({ t: grid.bar(n), type: 'thump' })), // Szenenwechsel auf Downbeats
{ t: grid.bar(1), type: 'whoosh', gain: 0.6 }, // Übergang in Szene 2: der Peak trifft den Schnitt
{ t: grid.beat(6), type: 'click', pan: 0.2 }, // Cursor-Druck auf einem 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' }, // Ein Riser STARTET auf seinem Cue ...
{ t: grid.bar(5), type: 'hit' }, // ... und trifft beim nächsten Hit/Thump/Snap ein
],
}));
Cue-Felder: t (Sekunden), type, gain (1), pan (-1 bis 1, 0), pitch (Wiedergabegeschwindigkeits-Multiplikator, 1). Aliase sfx für type und vol für gain werden akzeptiert. Cues zu negativen oder nicht endlichen Zeiten werden verworfen. Typen (SFX_TYPES): click tick pop thump whoosh swoosh riser hit chime type glitch snap.
Anker-Semantik: t ist der Moment, in dem der Klang auftrifft, nicht wo das Sample beginnt. node tools/sfx.mjs --list gibt jede Stimme mit ihrer Länge und ihrem Anker aus.
| Typ | Was trifft bei t ein | Verwendung |
|---|---|---|
click, tick, pop, thump, hit, chime, type, snap | Der Einschwingvorgang (der Klang beginnt einige Millisekunden früher) | Das visuelle Ereignis: ein Druck, ein Eintritt, eine Verriegelung |
glitch | Sein erstes Fragment: Es beginnt bei t | Ein digitaler Bruch, im Frame, in dem er erscheint |
whoosh, swoosh | Der Vorbeiflug-Peak (0,31 s bzw. 0,20 s im Klang), also baut sich der Schwung vor t auf | Setzen Sie ihn auf den Schnitt oder die Bewegung, die er trägt |
riser | Nichts trifft ein: Es beginnt bei t und schwillt in den nächsten hit-, thump- oder snap-Cue 0,4 bis 4 s später an, trifft also bei diesem Einschlag ein; ohne einen solchen Cue in Reichweite dauert es 1,6 s | Setzen Sie ihn einen Takt oder einen Beat vor dem Einschlag, niemals darauf |
Ein Riser zur gleichen Zeit wie sein hit findet keinen Landungs-Cue (er braucht einen mehr als 0,35 s später) und läuft 1,6 s über den Einschlag hinaus, anstatt in ihn hinein. Setzen Sie den Riser-Cue früher, bei grid.bar(n - 1) für einen Hit bei grid.bar(n).
Gestaffelte Pops wie das obige Kachel-Beispiel sind beabsichtigte Off-Beat-Cues; die Sync-Metrik listet sie auf, was in Ordnung ist, solange jeder auf seinem visuellen Ereignis sitzt.
4. SFX
npm run sfx # öffnet den Film headless, liest __studio.cues(), schreibt audio/cues.json + audio/sfx.wav
node tools/sfx.mjs --dump-cues # nur audio/cues.json schreiben (Zeiten vor dem Synthetisieren prüfen)
node tools/sfx.mjs --cues my.json # aus einer manuell bearbeiteten Cue-Datei statt aus dem Film synthetisieren
Jede Stimme wird deterministisch synthetisiert (Pro-Cue-Seed aus Typ, Zeit und Rang des Cues unter identischen Cues, plus --seed, sodass das Hinzufügen, Entfernen oder Umsortieren anderer Cues den Klang dieses Cues unverändert lässt), mit gleicher Leistung paniert, auf einem Float-Bus summiert, auf -1 dBFS begrenzt, und die Datei hat exakt die Filmdauer (leere Cues erzeugen Stille dieser Länge; bei einem Loop-Film wird ein über das Ende hinauslaufender Schweif zum Anfang zurückgefaltet). Um stattdessen aufgenommene Samples zu verwenden, legen Sie audio/samples/<type>.wav (auch .flac, .mp3, .ogg) im Projekt ab: Es ersetzt die synthetisierte Stimme für diesen Typ (--samples none oder --no-samples ignoriert den Ordner für einen Lauf). Der lauteste Peak der Datei ist sein Anker, und ein gesampelter Riser wird so getaktet, dass dieser Peak bei der Ankunft landet. Samples benötigen eine kommerzielle Nutzungslizenz: eigene Aufnahmen, CC0 oder eine Lizenz, die Sie für einen veröffentlichten Film besitzen. Nur-Nennung-Lizenzen (CC BY) benötigen die Quellenangabe im Abspann; Lizenzen für nicht-kommerzielle und "persönliche Nutzung"-Pakete sind ausgeschlossen. Dokumentieren Sie die Quelle und Lizenz in den Notizen von docs/production.json.
5. Sprache (optional, ElevenLabs)
- Der Schlüssel kommt in
.envalsELEVENLABS_API_KEY=...(niemals in einem Prompt, einer Datei, die Sie committen, oder einem Screenshot). Verweisen Sie darauf mit Namen: "der ElevenLabs-Schlüssel ist ELEVENLABS_API_KEY in .env". - Schreiben Sie
audio/voice.json:[{ "t": 0.5, "text": "Meet Driftnote." }, { "t": 4.0, "text": "Notes that file themselves." }](optional pro ZeilevoiceId). Platzieren Sie Zeilen auf Downbeats und lassen Sie dem Bild Platz dafür. node tools/voice.mjs --dry-rungibt den Plan und die Zeichenanzahl aus (kein Netzwerk, keine Kosten). Zeigen Sie es dem Benutzer, wenn das Budget wichtig ist. Eine Zeile mit demselben Text, derselben Stimmen-ID und demselben Modell wie eine frühere wird einmal synthetisiert und abgerechnet (der Dry Run markiert sie alsrepeat;billableCharszählt nur eindeutige Zeichen).node tools/voice.mjs --voice-id <id>synthetisiert (pro Zeile inaudio/.cache/zwischengespeichert), platziert jede Zeile bei ihremtund schreibtaudio/voice.wavin der exakten Filmlänge.- Setzen Sie
studio.jsonaudio.voiceauf"audio/voice.wav", nachdemvoice.mjsdie Datei geschrieben hat (voice.mjsgibt die Erinnerung aus, bearbeitet aber nichtstudio.json). Solangeaudio.voicenullist, ignoriert die Mischung die Sprache; wenn es gesetzt ist, ducktmix.mjsdie Musik unter der Sprache (duck: true).audio.voiceIdist die Standardstimme für Zeilen ohne eigenevoiceId.
6. Mischen und verifizieren
npm run mix # alle Formate: out/score.wav + out/<fmt>/final.mp4 + out/final.mp4
node tools/critique.mjs --format 9x16 --video out/9x16/final.mp4 # Nachweise in out/review/9x16/video/
mix dauert 40 bis 80 s: Starten Sie es im Hintergrund und prüfen Sie das Log, wenn der Film lang oder die Maschine ausgelastet ist (niemals länger als etwa 2 Minuten im Vordergrund warten).
Bevor es mischt, dekodiert und misst mix.mjs jeden Stem. Ein Musik-, Sprach- oder SFX-Stem, der mehr als 0,25 s kürzer als der Film, leer oder still ist (Peak unter -80 dBFS), stoppt die Mischung mit refusing to mix: ... stem problem(s) do not fit the N s film und schreibt nichts: Eine veraltete music.wav aus einer früheren Dauer wurde als stiller Schweif eingemischt. Generieren Sie den Stem neu (npm run score, npm run sfx, npm run voice); für einen Voice-Over oder Jingle, der kurz sein soll, übergeben Sie --allow-short-stems (der fehlende Teil ist Stille). Ein stiller SFX-Stem warnt nur, da ein Film ohne Cues Stille rendert; ein Stem, der länger als der Film ist, warnt, dass sein Ende ohne Einblendung abgeschnitten wird. Das JSON-Ergebnis enthält stemInfo (dekodierte Dauer und Peak pro Stem).
Ziele: Integrierte -14 LUFS +-0,5, True Peak bei oder unter -1 dBTP, Audiolänge gleich Videolänge (niemals -shortest). --lufs (oder audio.lufs) muss -70 bis -5 sein, --tp (oder audio.truePeak) -20 bis 0; unter -9 dBTP erzwingt der Limiter-Pfad die Obergrenze, und eine spitzenreiche Mischung, die die Lautstärke bei einer niedrigen Obergrenze nicht erreichen kann, endet mit der Warnung master misses the target statt einem Absturz. mix.mjs verwendet den Zweidurchlauf-Loudnorm und behält sein lineares Ergebnis nur, wenn der Master innerhalb der halben Toleranz des Ziels liegt (+-0,25 LU standardmäßig); andernfalls fällt es auf Verstärkung plus einen überabgetasteten Limiter zurück, der auf +-0,1 LU abzielt, und misst dann den gemultiplexten AAC neu. Wenn eine Zahl abweicht, sagt die Berichtstabelle in references/mixing.md, was zu ändern ist.
Sync-Prüfung: metri…