A motion design toolkit for coding agents.
JavaScript
Turn sound design into a reusable sfx engine with cue sheets and auto-mastering
whaleybabb369900e5
diff --git a/.gitignore b/.gitignoreindex 2902387..e4953e3 100644--- a/.gitignore+++ b/.gitignore@@ -2,6 +2,7 @@ node_modules/out/.remotion/public/sfx.wav+__pycache__/.mcp.json.envdrafts/diff --git a/package.json b/package.jsonindex a633116..ee93d85 100644--- a/package.json+++ b/package.json@@ -8,7 +8,7 @@"still": "remotion still EffortVideo","draft": "remotion render EffortVideo out/draft.mp4 --scale=0.5 --crf=28","render": "remotion render EffortVideo out/effort-silent.mp4",- "sfx": "python3 scripts/sfx.py",+ "sfx": "python3 -m sfx sfx/cues/effort.py","mux": "ffmpeg -loglevel error -y -i out/effort-silent.mp4 -i public/sfx.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 256k -movflags +faststart -shortest out/effort.mp4","build": "npm run sfx && npm run render && npm run mux","sheet": "node scripts/sheet.mjs",diff --git a/scripts/sfx.py b/scripts/sfx.pydeleted file mode 100644index 658d5da..0000000--- a/scripts/sfx.py+++ /dev/null@@ -1,299 +0,0 @@-"""Procedural sound design for the effort video, synced to timeline.json.--Pure stdlib so it runs anywhere: python3 scripts/sfx.py -> public/sfx.wav-"""--import json-import math-import os-import random-import struct-import wave--SR = 48000-ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))-TL = json.load(open(os.path.join(ROOT, "timeline.json")))-DUR = TL["duration"]-N = int(SR * DUR)-L = [0.0] * N-R = [0.0] * N-random.seed(11)--PROMPT_1 = "redesign the /config menu"-PROMPT_2 = "build an HTML sanitizer"---def put(t, samples, gain=1.0, pan=0.0):- i0 = int(t * SR)- ang = (pan + 1) * math.pi / 4- gl, gr = gain * math.cos(ang), gain * math.sin(ang)- for k, s in enumerate(samples):- i = i0 + k- if 0 <= i < N:- L[i] += s * gl- R[i] += s * gr---def bandnoise(n, fc_at, q=0.8):- """White noise through a state-variable band-pass; fc_at(k) gives cutoff per sample."""- low = band = 0.0- out = []- for k in range(n):- f = 2 * math.sin(math.pi * min(fc_at(k), SR / 6) / SR)- x = random.uniform(-1, 1)- low += f * band- high = x - low - q * band- band += f * high- out.append(band)- return out---def click(freq=1800, dur=0.05):- n = int(dur * SR)- out = []- for k in range(n):- tt = k / SR- s = math.sin(2 * math.pi * freq * tt) * math.exp(-tt / 0.012)- s += random.uniform(-1, 1) * math.exp(-tt / 0.0015) * 0.6- out.append(s)- return out---def key():- n = int(0.018 * SR)- fc = random.uniform(2400, 4200)- noise = bandnoise(n, lambda k: fc, q=0.5)- thock = random.uniform(160, 220)- return [- noise[k] * math.exp(-k / (0.0025 * SR)) * 2.2- + math.sin(2 * math.pi * thock * k / SR) * math.exp(-k / (0.006 * SR)) * 0.5- for k in range(n)- ]---def blip(freq, dur=0.35, tau=0.12):- n = int(dur * SR)- out = []- ph = 0.0- for k in range(n):- tt = k / SR- ph += 2 * math.pi * freq / SR- a = min(1, tt / 0.003) * math.exp(-tt / tau)- out.append(a * (math.sin(ph) + 0.25 * math.sin(2 * ph) + 0.08 * math.sin(3 * ph)))- return out---def pop(f0, f1, dur=0.16):- n = int(dur * SR)- out = []- ph = 0.0- for k in range(n):- tt = k / SR- f = f0 * (f1 / f0) ** min(1, tt / 0.06)- ph += 2 * math.pi * f / SR- a = min(1, tt / 0.002) * math.exp(-tt / 0.045)- out.append(a * math.sin(ph))- return out---def chime(freqs, dur=1.8, tau=0.7):- n = int(dur * SR)- out = [0.0] * n- for j, f in enumerate(freqs):- ph1 = ph2 = 0.0- g = 1.0 / (1 + j * 0.35)- for k in range(n):- tt = k / SR- ph1 += 2 * math.pi * f / SR- ph2 += 2 * math.pi * f * 2.76 / SR- a = min(1, tt / 0.004) * math.exp(-tt / tau)- out[k] += g * a * (math.sin(ph1) + 0.18 * math.sin(ph2) * math.exp(-tt / 0.15))- return out---def whoosh(dur, f0, f1, peak=0.6, q=0.9):- n = int(dur * SR)- p = math.log(0.5) / math.log(peak)- noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=q)- return [noise[k] * math.sin(math.pi * (k / n) ** p) ** 2 * 1.6 for k in range(n)]---def riser(dur, f0=260, f1=5200):- n = int(dur * SR)- noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=0.6)- out = []- ph = 0.0- for k in range(n):- x = k / n- ph += 2 * math.pi * (180 * (4.0 ** x)) / SR- tail = min(1, (n - k) / (0.02 * SR))- out.append((noise[k] * 1.3 + 0.35 * math.sin(ph)) * x ** 2.2 * tail)- return out---def impact(dur=1.2):- n = int(dur * SR)- out = []- ph = 0.0- lp = 0.0- for k in range(n):- tt = k / SR- f = 38 + 60 * math.exp(-tt / 0.07)- ph += 2 * math.pi * f / SR- lp += 0.08 * (random.uniform(-1, 1) - lp)- s = math.sin(ph) * math.exp(-tt / 0.38)- s += lp * math.exp(-tt / 0.05) * 3.0- out.append(math.tanh(1.6 * s))- return out---def scratch(dur):- """Pencil-on-paper texture for the sketch draw-on."""- n = int(dur * SR)- noise = bandnoise(n, lambda k: 3800 + 1400 * math.sin(k / SR * 23), q=0.35)- out = []- for k in range(n):- tt = k / SR- stroke = max(0.0, math.sin(tt * 2 * math.pi * 7.5)) ** 3- env = math.sin(math.pi * k / n)- out.append(noise[k] * stroke * env * 1.4)- return out---def pad():- chord_a = [146.83, 220.0, 293.66, 369.99, 554.37]- chord_b = [146.83, 220.0, 293.66, 440.0, 587.33, 739.99]- t_switch = TL["s4"]["irisOut"]-- duck, lift = TL["s4"]["merge"], TL["s4"]["irisOut"]-- def vol(t):- v = min(1.0, t / 1.4)- if duck < t < lift:- v *= 1 - 0.65 * min(1, (t - duck) / 0.3)- if t >= lift:- v = 0.35 + 0.8 * min(1, (t - lift) / 0.5)- if t > DUR - 1.2:- v *= max(0.0, 1 - (t - (DUR - 1.2)) / 1.2)- return v-- phl = [0.0] * len(chord_a)- phr = [0.0] * len(chord_a)- for i in range(N):- t = i / SR- v = vol(t) * 0.028- if v <= 0:- continue- mix = min(1, max(0, (t - t_switch) / 0.35))- trem = 0.85 + 0.15 * math.sin(2 * math.pi * 0.23 * t)- sl = sr = 0.0- for j, f in enumerate(chord_a):- phl[j] += 2 * math.pi * (f - 0.6) / SR- phr[j] += 2 * math.pi * (f + 0.6) / SR- g = (1 - mix) / (1 + j * 0.5)- sl += g * math.sin(phl[j])- sr += g * math.sin(phr[j])- if mix > 0:- for j, f in enumerate(chord_b):- g = mix / (1 + j * 0.45)- sl += g * math.sin(2 * math.pi * (f - 0.5) * t)- sr += g * math.sin(2 * math.pi * (f + 0.5) * t)- L[i] += sl * v * trem- R[i] += sr * v * trem---s1, s2, s3, s4 = TL["s1"], TL["s2"], TL["s3"], TL["s4"]--pad()--# scene 1-put(s1["spark"], chime([1318.5, 1975.5, 2637.0], dur=1.6, tau=0.5), 0.10, 0.0)-put(s1["spark"], whoosh(0.9, 200, 1400, peak=0.3), 0.10)-for i, w in enumerate([s1["line1"], s1["line1"] + 0.09, s1["line2"], s1["line2"] + 0.09]):- put(w, whoosh(0.28, 500, 2400, peak=0.45), 0.10, -0.3 + i * 0.2)- put(w + 0.12, blip(98 if i < 2 else 110, dur=0.3, tau=0.08), 0.22)-put(s1["bar"], pop(420, 180), 0.25)-put(s1["sparkDock"], whoosh(0.5, 2600, 700, peak=0.5), 0.12, -0.4)-put(s1["sparkDock"] + 0.48, click(2400), 0.18, -0.5)--for k in range(len(PROMPT_1)):- tk = s1["typeStart"] + (s1["typeEnd"] - s1["typeStart"]) * k / len(PROMPT_1)- put(tk + random.uniform(-0.006, 0.006), key(), random.uniform(0.16, 0.26), random.uniform(-0.3, 0.3))--put(s1["exit"], whoosh(0.42, 600, 3200, peak=0.4), 0.16)-put(s1["flipStart"], whoosh(s1["flipEnd"] - s1["flipStart"], 400, 2200, peak=0.55), 0.2, 0.2)--# scene 2-put(s2["drawOn"] + 0.05, scratch(1.2), 0.12, 0.1)-notes = [659.25, 739.99, 880.0, 987.77]-for i, st in enumerate(s2["steps"]):- put(st, click(1600 + i * 250), 0.28, -0.1 + i * 0.07)- put(st + 0.01, blip(notes[i], dur=0.5, tau=0.14), 0.16, -0.1 + i * 0.07)- if i in (1, 2):- put(st + 0.08, whoosh(0.5, 1800, 7000, peak=0.35, q=0.5), 0.07)-arrive_max = s2["steps"][3] + 0.2-put(arrive_max, chime([987.77, 1479.98, 1975.53], dur=1.8, tau=0.6), 0.16, 0.1)-for i, c in enumerate(s2["callouts"]):- put(c, pop(900 + i * 180, 380 + i * 80), 0.32, [0.4, -0.5, 0.3][i])-put(s2["exit"], whoosh(0.5, 3000, 500, peak=0.45), 0.2)--# scene 3-for k in range(6):- put(s3["rewind"] + k * 0.035, click(2600 - k * 260, dur=0.03), 0.14 * (1 - k * 0.1), 0.3 - k * 0.1)-for k in range(len(PROMPT_2)):- tk = s3["retypeStart"] + (s3["retypeEnd"] - s3["retypeStart"]) * k / len(PROMPT_2)- put(tk + random.uniform(-0.004, 0.004), key(), random.uniform(0.14, 0.22), random.uniform(-0.3, 0.3))-for i in range(5):- put(s3["enter"] + 0.15 + i * 0.06, click(900 + i * 60, dur=0.04), 0.06, (i - 2) * 0.3)-put(s3["lowResult"], pop(1200, 520), 0.3, -0.5)-put(s3["lowResult"] + 0.02, blip(880, dur=0.4), 0.1, -0.5)-for i in range(1, 5):- put(s3["lowResult"] + 0.1 + i * 0.05, blip(146.8, dur=0.2, tau=0.05), 0.2, (i - 2) * 0.3)-put(s3["climb"] - 0.05, riser(s3["arrive"] - s3["climb"] + 0.05), 0.22)-for i, c in enumerate(s3["chips"]):- put(c, pop(1500 + i * 120, 900), 0.14, -0.4 + i * 0.27)-put(s3["arrive"], click(2000), 0.22)-pop_notes = [1046.5, 1318.5, 1568.0, 2093.0]-for i, pp in enumerate(s3["pops"]):- put(pp, pop(pop_notes[i] * 0.9, pop_notes[i] * 0.45), 0.34, -0.25 + i * 0.25)- put(pp + 0.005, blip(pop_notes[i] / 2, dur=0.4, tau=0.12), 0.1, -0.25 + i * 0.25)-put(s3["pops"][3] + 0.08, chime([523.25, 783.99, 1046.5, 1318.5], dur=2.0, tau=0.8), 0.14)--# transition + finale-put(s4["merge"] - 0.05, whoosh(0.3, 3500, 800, peak=0.8), 0.18)-put(s4["irisIn"], whoosh(s4["irisOut"] - s4["irisIn"] + 0.05, 300, 4200, peak=0.85, q=0.7), 0.32)-put(s4["irisOut"] - 0.01, impact(), 0.34)-put(s4["irisOut"], whoosh(0.7, 5000, 300, peak=0.15, q=0.6), 0.14)-for i in range(4):- put(s4["setup"] + i * 0.07 + 0.1, blip(220 * (1.5 if i % 2 else 1), dur=0.25, tau=0.05), 0.08)-put(s4["line1"] + 0.12, blip(73.4, dur=0.7, tau=0.25), 0.35)-put(s4["line1"] + 0.12, click(900), 0.08)-put(s4["line2"] + 0.12, blip(82.4, dur=0.7, tau=0.25), 0.35)-put(s4["line2"] + 0.12, click(1100), 0.08)-put(s4["mini"], pop(700, 350), 0.14)-put(s4["miniTravel"], riser(s4["miniArrive"] - s4["miniTravel"], 600, 3800), 0.1)-put(s4["miniArrive"], chime([587.33, 880.0, 1174.66, 1479.98], dur=1.1, tau=0.5), 0.2)-put(s4["miniArrive"], click(2200), 0.2)-put(s4["footer"], pop(1100, 600), 0.1, -0.6)--# master: normalize, soft clip, short fade-out-# DRIVE sets loudness, CEIL leaves headroom for AAC overshoot (target -14 LUFS, true peak <= -1 dBFS)-DRIVE = 1.8-CEIL = 0.76-peak = max(max(abs(x) for x in L), max(abs(x) for x in R)) or 1.0-fade_n = int(0.25 * SR)-os.makedirs(os.path.join(ROOT, "public"), exist_ok=True)-path = os.path.join(ROOT, "public", "sfx.wav")-with wave.open(path, "wb") as wf:- wf.setnchannels(2)- wf.setsampwidth(2)- wf.setframerate(SR)- frames = bytearray()- drive = math.tanh(DRIVE)- for i in range(N):- g = 1.0 if i < N - fade_n else (N - i) / fade_n- l = math.tanh(DRIVE * L[i] / peak) / drive * CEIL * g- r = math.tanh(DRIVE * R[i] / peak) / drive * CEIL * g- frames += struct.pack("<hh", int(l * 32767), int(r * 32767))- wf.writeframes(bytes(frames))-print("wrote", path, f"{DUR}s peak(pre)={peak:.3f}")diff --git a/scripts/sheet.mjs b/scripts/sheet.mjsindex b4705db..9404ebb 100644--- a/scripts/sheet.mjs+++ b/scripts/sheet.mjs@@ -7,7 +7,7 @@// node scripts/sheet.mjs --from 3 --to 5 --every 0.2 scrub a transition//// Options: --video out/draft.mp4 (default: newest of out/draft.mp4, out/effort.mp4)-// --offset 0.3 --cols 4 --rows 2 --size 540 --name beats+// --timeline timeline.json --offset 0.3 --cols 4 --rows 2 --size 540 --name beatsimport {execFileSync} from 'node:child_process';import fs from 'node:fs';import path from 'node:path';@@ -27,6 +27,7 @@ const newest = ['out/draft.mp4', 'out/effort.mp4'].filter((p) => fs.existsSync(p)).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0];const video = path.resolve(opt('video', newest ?? ''));+const timelinePath = path.resolve(opt('timeline', path.join(ROOT, 'timeline.json')));const offset = Number(opt('offset', '0.3'));const every = opt('every', null);const from = Number(opt('from', '0'));@@ -46,7 +47,7 @@ const probe = (args) =>const duration = Number(probe(['-show_entries', 'format=duration']));const beats = () => {- const tl = JSON.parse(fs.readFileSync(path.join(ROOT, 'timeline.json'), 'utf8'));+ const tl = JSON.parse(fs.readFileSync(timelinePath, 'utf8'));const out = [];const walk = (v, key) => {if (key === 'fps' || key === 'duration') return;diff --git a/scripts/wave.mjs b/scripts/wave.mjsindex 7312db8..f82d939 100644--- a/scripts/wave.mjs+++ b/scripts/wave.mjs@@ -3,6 +3,7 @@//// node scripts/wave.mjs public/sfx.wav → out/wave.png// node scripts/wave.mjs out/effort.mp4 measure the final mux instead+// --timeline other.json beats from another timeline (default timeline.json)//// Every hit in the waveform should sit on (or a hair after) a beat line.import {execFileSync, spawnSync} from 'node:child_process';@@ -10,7 +11,10 @@ import fs from 'node:fs';import path from 'node:path';const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');-const input = path.resolve(process.argv[2] ?? path.join(ROOT, 'public', 'sfx.wav'));+const argv = process.argv.slice(2);+const ti = argv.indexOf('--timeline');+const timelinePath = path.resolve(ti === -1 ? path.join(ROOT, 'timeline.json') : argv.splice(ti, 2)[1]);+const input = path.resolve(argv[0] ?? path.join(ROOT, 'public', 'sfx.wav'));if (!fs.existsSync(input)) {console.error(`${path.relative(ROOT, input)} not found. Run \`npm run sfx\` first.`);process.exit(1);@@ -21,7 +25,7 @@ const MAX_TRUE_PEAK = -1;const W = 1800;const H = 280;-const tl = JSON.parse(fs.readFileSync(path.join(ROOT, 'timeline.json'), 'utf8'));+const tl = JSON.parse(fs.readFileSync(timelinePath, 'utf8'));const beats = [];const walk = (v, key) => {if (key === 'fps' || key === 'duration') return;@@ -57,5 +61,5 @@ const peak = Number(summary.match(/Peak:\s+(-?[\d.]+) dBFS/)?.[1]);console.log(`waveform: ${path.relative(ROOT, png)} (${beats.length} beats in coral, grid = 1s)`);console.log(`loudness: ${lufs} LUFS integrated (target ${TARGET_LUFS} ±1)`);console.log(`true peak: ${peak} dBFS (keep ≤ ${MAX_TRUE_PEAK})`);-if (Math.abs(lufs - TARGET_LUFS) > 1) console.warn('WARN loudness off target: adjust master gain in scripts/sfx.py');+if (Math.abs(lufs - TARGET_LUFS) > 1) console.warn('WARN loudness off target: re-run the cue sheet, check TARGET_LUFS');if (peak > MAX_TRUE_PEAK) console.warn('WARN true peak too hot: AAC encoding may clip, lower the master ceiling');diff --git a/sfx/__init__.py b/sfx/__init__.pynew file mode 100644index 0000000..fd8be6e--- /dev/null+++ b/sfx/__init__.py@@ -0,0 +1,10 @@+"""Procedural sound design for motion graphics. Pure Python stdlib, 48 kHz stereo.++ python3 -m sfx sfx/cues/effort.py render a cue sheet to WAV+ python3 -m sfx --list list the sound generators+"""++from .mix import Mix+from .synth import SR++__all__ = ["Mix", "SR"]diff --git a/sfx/__main__.py b/sfx/__main__.pynew file mode 100644index 0000000..9399f24--- /dev/null+++ b/sfx/__main__.py@@ -0,0 +1,61 @@+"""CLI: render a cue sheet, or list the available generators."""++import argparse+import importlib.util+import inspect+import json+import sys++from . import synth+from .mix import Mix+++def list_generators():+ for name, fn in inspect.getmembers(synth, inspect.isfunction):+ if fn.__module__ != synth.__name__ or name.startswith("_"):+ continue+ doc = (fn.__doc__ or "").strip().splitlines()[0] if fn.__doc__ else ""+ print(f"{name}{inspect.signature(fn)}\n {doc}")+++def load_cues(path):+ spec = importlib.util.spec_from_file_location("cues", path)+ cues = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(cues)+ if not hasattr(cues, "score"):+ sys.exit(f"{path} needs a score(mix, tl) function")+ return cues+++def main():+ ap = argparse.ArgumentParser(prog="python3 -m sfx", description="Render a cue sheet to a mastered WAV.")+ ap.add_argument("cues", nargs="?", help="cue sheet: a .py file with score(mix, tl)")+ ap.add_argument("--timeline", help="timeline JSON (default: the cue sheet's TIMELINE, else timeline.json)")+ ap.add_argument("--out", help="output WAV (default: the cue sheet's OUT, else public/sfx.wav)")+ ap.add_argument("--list", action="store_true", help="list sound generators and exit")+ args = ap.parse_args()++ if args.list:+ list_generators()+ return+ if not args.cues:+ ap.error("pass a cue sheet, or --list")++ cues = load_cues(args.cues)+ timeline = args.timeline or getattr(cues, "TIMELINE", "timeline.json")+ out = args.out or getattr(cues, "OUT", "public/sfx.wav")+ with open(timeline) as f:+ tl = json.load(f)++ mix = Mix(tl["duration"], seed=getattr(cues, "SEED", 11))+ cues.score(mix, tl)+ stats = mix.master(target_lufs=getattr(cues, "TARGET_LUFS", -14.0))+ mix.write(out)+ print(+ f"wrote {out}: {tl['duration']}s, {mix.count} sounds, "+ f"{stats['lufs']:.1f} LUFS, true peak {stats['peak_db']:.1f} dBFS, drive {stats['drive']}"+ )+++if __name__ == "__main__":+ main()diff --git a/sfx/cues/effort.py b/sfx/cues/effort.pynew file mode 100644index 0000000..0517a42--- /dev/null+++ b/sfx/cues/effort.py@@ -0,0 +1,92 @@+"""Sound design for EffortVideo. Every time comes from timeline.json.++ python3 -m sfx sfx/cues/effort.py+"""++from sfx.synth import blip, chime, click, envelope, impact, pad, pop, riser, scratch, whoosh++TIMELINE = "timeline.json"+OUT = "public/sfx.wav"+TARGET_LUFS = -14.0++PROMPT_1 = "redesign the /config menu"+PROMPT_2 = "build an HTML sanitizer"++# D major: the bed moves from Dmaj7(add9) to D6/9 on the iris hit.+BED_A = [146.83, 220.0, 293.66, 369.99, 554.37]+BED_B = [146.83, 220.0, 293.66, 440.0, 587.33, 739.99]+STEP_NOTES = [659.25, 739.99, 880.0, 987.77]+POP_NOTES = [1046.5, 1318.5, 1568.0, 2093.0]+++def score(mix, tl):+ s1, s2, s3, s4 = tl["s1"], tl["s2"], tl["s3"], tl["s4"]+ dur = tl["duration"]+ put = mix.put++ duck, lift = s4["merge"], s4["irisOut"]+ volume = envelope([+ (0, 0), (1.4, 1), (duck, 1), (duck + 0.3, 0.35),+ (lift, 0.35), (lift + 0.5, 1.15), (dur - 1.2, 1.15), (dur, 0),+ ])+ mix.put_stereo(0, *pad(dur, [(0, BED_A), (lift, BED_B)], volume=volume), gain=0.028)++ # scene 1: title, prompt bar, typing, flip+ put(s1["spark"], chime([1318.5, 1975.5, 2637.0], dur=1.6, tau=0.5), 0.10)+ put(s1["spark"], whoosh(0.9, 200, 1400, peak=0.3), 0.10)+ for i, w in enumerate([s1["line1"], s1["line1"] + 0.09, s1["line2"], s1["line2"] + 0.09]):+ put(w, whoosh(0.28, 500, 2400, peak=0.45), 0.10, -0.3 + i * 0.2)+ put(w + 0.12, blip(98 if i < 2 else 110, dur=0.3, tau=0.08), 0.22)+ put(s1["bar"], pop(420, 180), 0.25)+ put(s1["sparkDock"], whoosh(0.5, 2600, 700, peak=0.5), 0.12, -0.4)+ put(s1["sparkDock"] + 0.48, click(2400), 0.18, -0.5)+ mix.typing(s1["typeStart"], s1["typeEnd"], len(PROMPT_1))+ put(s1["exit"], whoosh(0.42, 600, 3200, peak=0.4), 0.16)+ put(s1["flipStart"], whoosh(s1["flipEnd"] - s1["flipStart"], 400, 2200, peak=0.55), 0.2, 0.2)++ # scene 2: sketch draws on, slider notches through every level+ put(s2["drawOn"] + 0.05, scratch(1.2), 0.12, 0.1)+ for i, st in enumerate(s2["steps"]):+ put(st, click(1600 + i * 250), 0.28, -0.1 + i * 0.07)+ put(st + 0.01, blip(STEP_NOTES[i], dur=0.5, tau=0.14), 0.16, -0.1 + i * 0.07)+ if i in (1, 2):+ put(st + 0.08, whoosh(0.5, 1800, 7000, peak=0.35, q=0.5), 0.07)+ put(s2["steps"][3] + 0.2, chime([987.77, 1479.98, 1975.53], dur=1.8, tau=0.6), 0.16, 0.1)+ for i, c in enumerate(s2["callouts"]):+ put(c, pop(900 + i * 180, 380 + i * 80), 0.32, [0.4, -0.5, 0.3][i])+ put(s2["exit"], whoosh(0.5, 3000, 500, peak=0.45), 0.2)++ # scene 3: rewind, retype, 1/5 at low, climb to 5/5 at xhigh+ for k in range(6):+ put(s3["rewind"] + k * 0.035, click(2600 - k * 260, dur=0.03), 0.14 * (1 - k * 0.1), 0.3 - k * 0.1)+ mix.typing(s3["retypeStart"], s3["retypeEnd"], len(PROMPT_2), gain=(0.14, 0.22), jitter=0.004)+ for i in range(5):+ put(s3["enter"] + 0.15 + i * 0.06, click(900 + i * 60, dur=0.04), 0.06, (i - 2) * 0.3)+ put(s3["lowResult"], pop(1200, 520), 0.3, -0.5)+ put(s3["lowResult"] + 0.02, blip(880, dur=0.4), 0.1, -0.5)+ for i in range(1, 5):+ put(s3["lowResult"] + 0.1 + i * 0.05, blip(146.8, dur=0.2, tau=0.05), 0.2, (i - 2) * 0.3)+ put(s3["climb"] - 0.05, riser(s3["arrive"] - s3["climb"] + 0.05), 0.22)+ for i, c in enumerate(s3["chips"]):+ put(c, pop(1500 + i * 120, 900), 0.14, -0.4 + i * 0.27)+ put(s3["arrive"], click(2000), 0.22)+ for i, pp in enumerate(s3["pops"]):+ put(pp, pop(POP_NOTES[i] * 0.9, POP_NOTES[i] * 0.45), 0.34, -0.25 + i * 0.25)+ put(pp + 0.005, blip(POP_NOTES[i] / 2, dur=0.4, tau=0.12), 0.1, -0.25 + i * 0.25)+ put(s3["pops"][3] + 0.08, chime([523.25, 783.99, 1046.5, 1318.5], dur=2.0, tau=0.8), 0.14)++ # iris transition and finale: the only impact in the mix+ put(s4["merge"] - 0.05, whoosh(0.3, 3500, 800, peak=0.8), 0.18)+ put(s4["irisIn"], whoosh(s4["irisOut"] - s4["irisIn"] + 0.05, 300, 4200, peak=0.85, q=0.7), 0.32)+ put(s4["irisOut"] - 0.01, impact(), 0.34)+ put(s4["irisOut"], whoosh(0.7, 5000, 300, peak=0.15, q=0.6), 0.14)+ for i in range(4):+ put(s4["setup"] + i * 0.07 + 0.1, blip(220 * (1.5 if i % 2 else 1), dur=0.25, tau=0.05), 0.08)+ for line, (note, tick) in zip((s4["line1"], s4["line2"]), ((73.4, 900), (82.4, 1100))):+ put(line + 0.12, blip(note, dur=0.7, tau=0.25), 0.35)+ put(line + 0.12, click(tick), 0.08)+ put(s4["mini"], pop(700, 350), 0.14)+ put(s4["miniTravel"], riser(s4["miniArrive"] - s4["miniTravel"], 600, 3800), 0.1)+ put(s4["miniArrive"], chime([587.33, 880.0, 1174.66, 1479.98], dur=1.1, tau=0.5), 0.2)+ put(s4["miniArrive"], click(2200), 0.2)+ put(s4["footer"], pop(1100, 600), 0.1, -0.6)diff --git a/sfx/loudness.py b/sfx/loudness.pynew file mode 100644index 0000000..6dce897--- /dev/null+++ b/sfx/loudness.py@@ -0,0 +1,72 @@+"""Integrated loudness (ITU-R BS.1770-4, EBU R128 gating) for 48 kHz stereo."""++import math++# K-weighting at 48 kHz: high shelf, then high-pass (coefficients from BS.1770).+_SHELF = ((1.53512485958697, -2.69169618940638, 1.19839281085285), (-1.69065929318241, 0.73248077421585))+_HIGHPASS = ((1.0, -2.0, 1.0), (-1.99004745483398, 0.99007225036621))+++def _biquad(x, coeffs):+ (b0, b1, b2), (a1, a2) = coeffs+ y = [0.0] * len(x)+ x1 = x2 = y1 = y2 = 0.0+ for i, xi in enumerate(x):+ yi = b0 * xi + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2+ x2, x1, y2, y1 = x1, xi, y1, yi+ y[i] = yi+ return y+++def _kernels(taps=8):+ out = []+ for frac in (0.25, 0.5, 0.75):+ k = []+ for j in range(-taps + 1, taps + 1):+ d = j - frac+ k.append((j, math.sin(math.pi * d) / (math.pi * d) * 0.5 * (1 + math.cos(math.pi * d / taps))))+ out.append(k)+ return out+++_TP_KERNELS = _kernels()+++def true_peak(x, near=0.7):+ """Linear true peak: 4x windowed-sinc interpolation around samples above near × sample peak."""+ peak = max(map(abs, x)) or 0.0+ lim = near * peak+ tp = peak+ for i in range(8, len(x) - 8):+ if abs(x[i]) < lim and abs(x[i + 1]) < lim:+ continue+ for kernel in _TP_KERNELS:+ v = abs(sum(c * x[i + j] for j, c in kernel))+ if v > tp:+ tp = v+ return tp+++def integrated_lufs(left, right, sr=48000):+ """Integrated loudness in LUFS; -inf for silence."""+ if sr != 48000:+ raise ValueError("K-weighting coefficients here are for 48 kHz")+ kl = _biquad(_biquad(left, _SHELF), _HIGHPASS)+ kr = _biquad(_biquad(right, _SHELF), _HIGHPASS)++ cs = [0.0]+ acc = 0.0+ for a, b in zip(kl, kr):+ acc += a * a + b * b+ cs.append(acc)++ block, hop = int(0.4 * sr), int(0.1 * sr)+ z = [(cs[i + block] - cs[i]) / block for i in range(0, len(kl) - block + 1, hop)]+ lufs = lambda power: -0.691 + 10 * math.log10(power)++ above_abs = [p for p in z if p > 0 and lufs(p) > -70]+ if not above_abs:+ return float("-inf")+ relative = lufs(sum(above_abs) / len(above_abs)) - 10+ gated = [p for p in above_abs if lufs(p) > relative]+ return lufs(sum(gated) / len(gated))diff --git a/sfx/mix.py b/sfx/mix.pynew file mode 100644index 0000000..358294b--- /dev/null+++ b/sfx/mix.py@@ -0,0 +1,111 @@+"""Mixer: place sounds in time, master to a loudness target, write a WAV."""++import math+import os+import random+import struct+import wave++from .loudness import integrated_lufs, true_peak+from .synth import SR, key++DRIVES = (1.2, 1.5, 1.8, 2.0, 2.2, 2.5, 3.0, 4.0)+++class Mix:+ def __init__(self, duration, seed=11):+ random.seed(seed)+ self.duration = duration+ self.n = int(SR * duration)+ self.left = [0.0] * self.n+ self.right = [0.0] * self.n+ self.count = 0+ self._out = None++ def put(self, t, samples, gain=1.0, pan=0.0):+ """Place mono samples at t seconds. pan: -1 left, 0 centre, +1 right (equal power)."""+ ang = (pan + 1) * math.pi / 4+ gl, gr = gain * math.cos(ang), gain * math.sin(ang)+ i0 = int(t * SR)+ for k, s in enumerate(samples):+ i = i0 + k+ if 0 <= i < self.n:+ self.left[i] += s * gl+ self.right[i] += s * gr+ self.count += 1++ def put_stereo(self, t, left, right, gain=1.0):+ """Place a stereo pair (e.g. from synth.pad) at t seconds."""+ i0 = int(t * SR)+ for k, (a, b) in enumerate(zip(left, right)):+ i = i0 + k+ if 0 <= i < self.n:+ self.left[i] += a * gain+ self.right[i] += b * gain+ self.count += 1++ def typing(self, start, end, chars, gain=(0.16, 0.26), jitter=0.006, spread=0.3):+ """One keystroke per character, evenly spaced from start to end, humanized."""+ for k in range(chars):+ tk = start + (end - start) * k / chars+ self.put(tk + random.uniform(-jitter, jitter), key(), random.uniform(*gain), random.uniform(-spread, spread))++ def master(self, target_lufs=-14.0, ceiling_db=-2.0, fade_out=0.25):+ """Soft-clip and set gain so the mix hits target_lufs with true peak <= ceiling_db.++ Drive only rises when the ceiling would otherwise be crossed. The ceiling+ leaves room for AAC overshoot, so the muxed MP4 stays under -1 dBTP. If no+ drive reaches the target within the ceiling, the mix comes out quieter+ rather than crushed.+ """+ peak = max(max(map(abs, self.left)), max(map(abs, self.right))) or 1.0+ fade_n = int(fade_out * SR)+ fade = [1.0 if i < self.n - fade_n else (self.n - i) / fade_n for i in range(self.n)]+ ceiling = 10 ** (ceiling_db / 20)++ best = None+ for drive in DRIVES:+ norm = math.tanh(drive)+ left = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.left, fade)]+ right = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.right, fade)]+ gain = 10 ** ((target_lufs - integrated_lufs(left, right)) / 20)+ if gain > ceiling:+ continue+ tp = max(true_peak(left), true_peak(right))+ fit = min(gain, ceiling / tp)+ if best is None or fit / gain > best[0]:+ best = (fit / gain, drive, left, right, fit, tp)+ if gain * tp <= ceiling:+ break+ if best is None:+ drive = DRIVES[0]+ norm = math.tanh(drive)+ left = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.left, fade)]+ right = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.right, fade)]+ tp = max(true_peak(left), true_peak(right))+ best = (0, drive, left, right, ceiling / tp, tp)+ _, drive, left, right, gain, tp = best++ self._out = ([x * gain for x in left], [x * gain for x in right])+ lufs = integrated_lufs(*self._out)+ if lufs < target_lufs - 0.5:+ print(+ f"warning: {lufs:.1f} LUFS, short of {target_lufs}: the mix is too sparse to get louder "+ "without clipping. Add sustained sound (a pad, longer tails) or accept it quieter."+ )+ return {"lufs": lufs, "peak_db": 20 * math.log10(gain * tp), "drive": drive}++ def write(self, path):+ """Write 16-bit stereo WAV; masters with defaults first if master() wasn't called."""+ if self._out is None:+ self.master()+ os.makedirs(os.path.dirname(path) or ".", exist_ok=True)+ left, right = self._out+ with wave.open(path, "wb") as wf:+ wf.setnchannels(2)+ wf.setsampwidth(2)+ wf.setframerate(SR)+ frames = bytearray()+ for a, b in zip(left, right):+ frames += struct.pack("<hh", int(a * 32767), int(b * 32767))+ wf.writeframes(bytes(frames))diff --git a/sfx/synth.py b/sfx/synth.pynew file mode 100644index 0000000..50dc457--- /dev/null+++ b/sfx/synth.py@@ -0,0 +1,193 @@+"""Sound generators.++Every generator returns mono samples (a list of floats, roughly -1..1) at SR.+The first line of each docstring says what it's for; `python3 -m sfx --list`+prints them. To add a sound, write a function here in the same shape.+Use the module-level `random` for noise so renders stay reproducible.+"""++import bisect+import math+import random++SR = 48000+++def bandnoise(n, fc_at, q=0.8):+ """Building block: white noise through a band-pass, fc_at(k) is the cutoff in Hz at sample k."""+ low = band = 0.0+ out = []+ for k in range(n):+ f = 2 * math.sin(math.pi * min(fc_at(k), SR / 6) / SR)+ x = random.uniform(-1, 1)+ low += f * band+ high = x - low - q * band+ band += f * high+ out.append(band)+ return out+++def click(freq=1800, dur=0.05):+ """UI click: a control snapping to a step, a toggle, a tick. Higher freq sounds smaller."""+ n = int(dur * SR)+ out = []+ for k in range(n):+ tt = k / SR+ s = math.sin(2 * math.pi * freq * tt) * math.exp(-tt / 0.012)+ s += random.uniform(-1, 1) * math.exp(-tt / 0.0015) * 0.6+ out.append(s)+ return out+++def key():+ """One keystroke; every call is slightly different. For typing use Mix.typing()."""+ n = int(0.018 * SR)+ fc = random.uniform(2400, 4200)+ noise = bandnoise(n, lambda k: fc, q=0.5)+ thock = random.uniform(160, 220)+ return [+ noise[k] * math.exp(-k / (0.0025 * SR)) * 2.2+ + math.sin(2 * math.pi * thock * k / SR) * math.exp(-k / (0.006 * SR)) * 0.5+ for k in range(n)+ ]+++def blip(freq, dur=0.35, tau=0.12):+ """Soft tonal blip: a word or element landing, one note of a sequence. Keep freq in key."""+ n = int(dur * SR)+ out = []+ ph = 0.0+ for k in range(n):+ tt = k / SR+ ph += 2 * math.pi * freq / SR+ a = min(1, tt / 0.003) * math.exp(-tt / tau)+ out.append(a * (math.sin(ph) + 0.25 * math.sin(2 * ph) + 0.08 * math.sin(3 * ph)))+ return out+++def pop(f0, f1, dur=0.16):+ """Pitched pop: a badge, chip or callout popping in. Sweeps f0 to f1; raise f0 across a sequence."""+ n = int(dur * SR)+ out = []+ ph = 0.0+ for k in range(n):+ tt = k / SR+ f = f0 * (f1 / f0) ** min(1, tt / 0.06)+ ph += 2 * math.pi * f / SR+ a = min(1, tt / 0.002) * math.exp(-tt / 0.045)+ out.append(a * math.sin(ph))+ return out+++def chime(freqs, dur=1.8, tau=0.7):+ """Bell chord: success, arrival, a payoff. Pass freqs from the video's key."""+ n = int(dur * SR)+ out = [0.0] * n+ for j, f in enumerate(freqs):+ ph1 = ph2 = 0.0+ g = 1.0 / (1 + j * 0.35)+ for k in range(n):+ tt = k / SR+ ph1 += 2 * math.pi * f / SR+ ph2 += 2 * math.pi * f * 2.76 / SR+ a = min(1, tt / 0.004) * math.exp(-tt / tau)+ out[k] += g * a * (math.sin(ph1) + 0.18 * math.sin(ph2) * math.exp(-tt / 0.15))+ return out+++def whoosh(dur, f0, f1, peak=0.6, q=0.9):+ """Air whoosh: movement, reveals, transitions. f0 to f1 sets direction, peak (0..1) where it's loudest."""+ n = int(dur * SR)+ p = math.log(0.5) / math.log(peak)+ noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=q)+ return [noise[k] * math.sin(math.pi * (k / n) ** p) ** 2 * 1.6 for k in range(n)]+++def riser(dur, f0=260, f1=5200):+ """Build-up into a payoff. End it exactly on the hit; one big riser per video."""+ n = int(dur * SR)+ noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=0.6)+ out = []+ ph = 0.0+ for k in range(n):+ x = k / n+ ph += 2 * math.pi * (180 * (4.0 ** x)) / SR+ tail = min(1, (n - k) / (0.02 * SR))+ out.append((noise[k] * 1.3 + 0.35 * math.sin(ph)) * x ** 2.2 * tail)+ return out+++def impact(dur=1.2):+ """Low impact for the hero moment. One per video."""+ n = int(dur * SR)+ out = []+ ph = 0.0+ lp = 0.0+ for k in range(n):+ tt = k / SR+ f = 38 + 60 * math.exp(-tt / 0.07)+ ph += 2 * math.pi * f / SR+ lp += 0.08 * (random.uniform(-1, 1) - lp)+ s = math.sin(ph) * math.exp(-tt / 0.38)+ s += lp * math.exp(-tt / 0.05) * 3.0+ out.append(math.tanh(1.6 * s))+ return out+++def scratch(dur):+ """Pencil on paper: a sketch or line drawing itself on."""+ n = int(dur * SR)+ noise = bandnoise(n, lambda k: 3800 + 1400 * math.sin(k / SR * 23), q=0.35)+ out = []+ for k in range(n):+ tt = k / SR+ stroke = max(0.0, math.sin(tt * 2 * math.pi * 7.5)) ** 3+ env = math.sin(math.pi * k / n)+ out.append(noise[k] * stroke * env * 1.4)+ return out+++def envelope(points):+ """Helper: piecewise-linear gain curve from [(t, value), ...], for pad volume and ducking."""+ pts = sorted(points)+ ts = [p[0] for p in pts]++ def at(t):+ i = bisect.bisect_right(ts, t)+ if i == 0:+ return pts[0][1]+ if i == len(pts):+ return pts[-1][1]+ (t0, v0), (t1, v1) = pts[i - 1], pts[i]+ return v0 + (v1 - v0) * (t - t0) / (t1 - t0)++ return at+++def pad(duration, chords, volume=None, detune=0.6, tremolo=0.23, xfade=0.35):+ """Music bed under everything; returns (left, right) for Mix.put_stereo. chords = [(start_s, [freqs]), ...]."""+ n = int(duration * SR)+ left = [0.0] * n+ right = [0.0] * n+ for ci, (t0, freqs) in enumerate(chords):+ t_next = chords[ci + 1][0] if ci + 1 < len(chords) else None+ i0 = int(t0 * SR)+ i1 = n if t_next is None else min(n, int((t_next + xfade) * SR))+ phl = [0.0] * len(freqs)+ phr = [0.0] * len(freqs)+ for i in range(i0, i1):+ t = i / SR+ w = 1.0 if ci == 0 else min(1.0, (t - t0) / xfade)+ if t_next is not None and t > t_next:+ w *= max(0.0, 1 - (t - t_next) / xfade)+ v = w * (volume(t) if volume else 1.0) * (0.85 + 0.15 * math.sin(2 * math.pi * tremolo * t))+ sl = sr = 0.0+ for j, f in enumerate(freqs):+ phl[j] += 2 * math.pi * (f - detune) / SR+ phr[j] += 2 * math.pi * (f + detune) / SR+ g = 1 / (1 + j * 0.5)+ sl += g * math.sin(phl[j])+ sr += g * math.sin(phr[j])+ left[i] += sl * v+ right[i] += sr * v+ return left, rightdiff --git a/src/lib.ts b/src/lib.tsindex b767bad..2ba8e13 100644--- a/src/lib.ts+++ b/src/lib.ts@@ -53,12 +53,13 @@ export const sp = (frame: number,startSec: number,config: Partial<SpringConfig> = {},+ fps: number = FPS,) => {- const fr = frame - startSec * FPS;+ const fr = frame - startSec * fps;if (fr <= 0) return 0;return spring({frame: fr,- fps: FPS,+ fps,config: {damping: 14, mass: 0.8, stiffness: 140, ...config},});};