Skip to content

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/.gitignore
index 2902387..e4953e3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@ node_modules/
out/
.remotion/
public/sfx.wav
+__pycache__/
.mcp.json
.env
drafts/
diff --git a/package.json b/package.json
index 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.py
deleted file mode 100644
index 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.mjs
index 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 beats
import {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.mjs
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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, right
diff --git a/src/lib.ts b/src/lib.ts
index 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},
});
};