Communitygithub.com

yazzang-homelab/motion-studio

Vertone einen Film auf dessen Beat-Gitter: Messen eines Tracks (beats.mjs) oder Synthese (score.mjs), Soundeffekte aus dem Film einspielen, Sprachausgabe hinzufügen, Mischung auf -14 LUFS / -1 dBTP bei exakter Länge. Verwenden für 'Musik hinzufügen', 'zum Takt synchronisieren', 'SFX', 'Lautstärke'.

Was ist motion-studio?

Dieses Skill für KI-Agenten (Claude Code, Cursor, Codex) ermöglicht die vollständige Sound-Postproduktion eines Films, der mit dem Motion Studio Framework erstellt wurde. Es verarbeitet einen vom Benutzer bereitgestellten Musiktrack, indem es dessen BPM, Beats, Downbeats und Einsätze mit einem JavaScript-basierten Beat-Tracker oder über eine Python/librosa-Option misst oder originäre, prozedural generierte Musik in vier Stilen (Pulse, Piano, Minimal, Kino) synthetisiert. Das Skill legt alle Audiobearbeitungen auf einem gemeinsamen Zeitgitter ab, das vom Film genutzt wird, um Szenenwechsel, UI-Interaktionen und Soundeffekte auf den genauen Beats und Downbeats zu platzieren. Es enthält einen deterministischen SFX-Synthesizer (Klicks, Pops, Whooshes, Riser, Hits usw.), optionale ElevenLabs-Sprachausgabe, eine Stereo-Mischung, die auf die Rundfunk-Lautstärkenormen -14 LUFS / -1 dBTP mit einem Zweidurchlauf-Loudnorm-Prozessor abzielt, und eine Metrik-zentrierte Build-Pipeline, die die Bild-Synchronisation überprüft. Es ist nützlich für Entwickler und Content-Ersteller, die filmische, codegesteuerte Animationen mit professioneller Audioqualität und präzisem Timing versehen möchten, ohne manuelle DAW-Workflows.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

SituationBefehlErgebnis
Benutzer hat einen Track bereitgestelltnpm 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 120Temposuche 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 / librosanpm run beats -- audio/track.wav --engine jsIntegrierte 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: synthetisierennpm run score -- --style pulse --bpm 120 --dur 12audio/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):

FlagWerteHinweise
--stylepulse (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, --durZahlenStandard aus studio.json
--key, --modeA, F#, Bb ... (ein nachgestelltes m bedeutet Moll), minor / majorMoll i-VI-III-VII, Dur I-V-vi-IV
--drop BARTaktnummerStandard etwa 40 % der Länge, Riser hinein
--loopFlagNahtlose 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 NGanzzahlGleicher Seed, gleiche Bytes
--if-missingFlagVon 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.

AufrufRü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.hitsGemessene 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.

TypWas trifft bei t einVerwendung
click, tick, pop, thump, hit, chime, type, snapDer Einschwingvorgang (der Klang beginnt einige Millisekunden früher)Das visuelle Ereignis: ein Druck, ein Eintritt, eine Verriegelung
glitchSein erstes Fragment: Es beginnt bei tEin digitaler Bruch, im Frame, in dem er erscheint
whoosh, swooshDer Vorbeiflug-Peak (0,31 s bzw. 0,20 s im Klang), also baut sich der Schwung vor t aufSetzen Sie ihn auf den Schnitt oder die Bewegung, die er trägt
riserNichts 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 sSetzen 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)

  1. Der Schlüssel kommt in .env als ELEVENLABS_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".
  2. Schreiben Sie audio/voice.json: [{ "t": 0.5, "text": "Meet Driftnote." }, { "t": 4.0, "text": "Notes that file themselves." }] (optional pro Zeile voiceId). Platzieren Sie Zeilen auf Downbeats und lassen Sie dem Bild Platz dafür.
  3. node tools/voice.mjs --dry-run gibt 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 als repeat; billableChars zählt nur eindeutige Zeichen).
  4. node tools/voice.mjs --voice-id <id> synthetisiert (pro Zeile in audio/.cache/ zwischengespeichert), platziert jede Zeile bei ihrem t und schreibt audio/voice.wav in der exakten Filmlänge.
  5. Setzen Sie studio.json audio.voice auf "audio/voice.wav", nachdem voice.mjs die Datei geschrieben hat (voice.mjs gibt die Erinnerung aus, bearbeitet aber nicht studio.json). Solange audio.voice null ist, ignoriert die Mischung die Sprache; wenn es gesetzt ist, duckt mix.mjs die Musik unter der Sprache (duck: true). audio.voiceId ist die Standardstimme für Zeilen ohne eigene voiceId.

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…

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'.

Verwandte Skills