Cutaway skill: build, film and score a 3D object that takes itself apart from one picture

The skill (SKILL.md), the kit for building one HTML page and capturing a 60 fps film, the procedural sound engine, the green page and look, and 3 complete examples: a tarantula, a piranha and a wasp, each with a full film and a 10-second version. The method docs move into docs/ with the README's GIFs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Nyxera0x
2026-11-06 12:57:09 +03:00
parent ca143f35f4
commit 5d8f1c6efe
93 changed files with 15705 additions and 39 deletions
+10
View File
@@ -0,0 +1,10 @@
"""Procedural sound design for motion graphics. Pure Python stdlib, 48 kHz stereo.
python run_sfx.py sfx/cues/effort.py render a cue sheet to WAV
python run_sfx.py --list list the sound generators
"""
from .mix import Mix
from .synth import SR
__all__ = ["Mix", "SR"]
+64
View File
@@ -0,0 +1,64 @@
"""CLI: render a cue sheet, or list the available generators."""
import argparse
import importlib.util
import inspect
import json
import os
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="python run_sfx.py", 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 cutaway-out/<cue>.wav, or $CUTAWAY_OUT)")
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)
# A relative TIMELINE in the cue sheet is read next to the cue sheet, so it runs from any folder.
timeline = args.timeline or os.path.join(os.path.dirname(os.path.abspath(args.cues)), getattr(cues, "TIMELINE", "timeline.json"))
stem = os.path.splitext(os.path.basename(args.cues))[0]
out = args.out or getattr(cues, "OUT", os.path.join(os.environ.get("CUTAWAY_OUT", "cutaway-out"), f"{stem}.wav"))
with open(timeline, encoding="utf8") 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()
+453
View File
@@ -0,0 +1,453 @@
"""DSP building blocks (oscillators, filters, delays, reverb), pure Python stdlib at 48 kHz.
Used by sound scripts that need more than the one-shot generators in synth.py,
e.g. sims/engine/sound.py.
Signals are plain lists of floats. Speed comes from two tricks:
- A Python per-sample loop costs about 0.3 µs/sample and a list comprehension
about 0.05 µs. So constant-pitch oscillators are one comprehension (the naive
ramp) plus a sparse PolyBLEP fix-up at each wrap. Feedback delays and the
reverb combs/allpasses run one block at a time, where the block is no longer
than the delay, so every block depends only on earlier blocks and is a single
comprehension.
- Filters whose state really is sequential (SVF, biquad, ladder) are tight
loops, run only on short one-shots or on the few full-length buses that need
them.
"""
import math
from .synth import SR
TAU = 2.0 * math.pi
_tanh = math.tanh
# ---------------------------------------------------------------- buffers
def zeros(n):
return [0.0] * n
def add(dst, src, at=0, gain=1.0):
"""dst[at:] += gain * src, in place, clipped to dst."""
if at < 0:
src = src[-at:]
at = 0
end = min(len(dst), at + len(src))
if end <= at:
return
seg = dst[at:end]
if gain == 1.0:
dst[at:end] = [a + b for a, b in zip(seg, src)]
else:
dst[at:end] = [a + b * gain for a, b in zip(seg, src)]
def scaled(x, g):
return [v * g for v in x]
def mul(x, y):
return [a * b for a, b in zip(x, y)]
def summed(a, b):
return [p + q for p, q in zip(a, b)]
def rms(x):
return math.sqrt(sum(v * v for v in x) / len(x)) if x else 0.0
def peak(x):
return max(max(x), -min(x)) if x else 0.0
def pan_gains(pan):
"""Equal-power pan, -1 left .. +1 right."""
ang = (pan + 1.0) * math.pi / 4.0
return math.cos(ang), math.sin(ang)
def fade(x, fin=0, fout=0):
"""Linear fade in/out over fin/fout samples, in place."""
n = len(x)
fin, fout = min(fin, n), min(fout, n)
for i in range(fin):
x[i] *= i / fin
for i in range(fout):
x[n - 1 - i] *= i / fout
return x
# ------------------------------------------------------------ oscillators
def _blep(out, phase, dt, n, h=1.0):
"""Subtract the PolyBLEP residual at every wrap of the ramp phase + i*dt (downward jump 2h)."""
k = 1
while True:
j = math.ceil((k - phase) / dt)
# float guard: make j the first sample whose wrapped phase is small
if j < n and (phase + j * dt) % 1.0 > 0.5:
j += 1
if j >= 1 and (phase + (j - 1) * dt) % 1.0 < 0.5:
j -= 1
if j - 1 >= n:
break
if 0 <= j < n:
u = ((phase + j * dt) % 1.0) / dt
if u < 1.0:
out[j] -= h * (u + u - u * u - 1.0)
if 1 <= j <= n:
u = (((phase + (j - 1) * dt) % 1.0) - 1.0) / dt
if u > -1.0:
out[j - 1] -= h * (u * u + u + u + 1.0)
k += 1
def saw(freq, n, phase=0.0):
"""Band-limited sawtooth (PolyBLEP) at constant freq, -1..1."""
dt = freq / SR
phase %= 1.0
out = [2.0 * ((phase + i * dt) % 1.0) - 1.0 for i in range(n)]
if 0.0 < dt < 0.5:
_blep(out, phase, dt, n)
return out
def pulse(freq, n, width=0.5, phase=0.0):
"""Band-limited pulse as the difference of two PolyBLEP saws; zero mean."""
a = saw(freq, n, phase)
b = saw(freq, n, phase + width)
return [p - q for p, q in zip(a, b)]
def sine(freq, n, phase=0.0):
w = TAU * freq / SR
ph = TAU * phase
sin = math.sin
return [sin(ph + w * i) for i in range(n)]
def noise(rng, n):
r = rng.random
return [2.0 * r() - 1.0 for _ in range(n)]
# ---------------------------------------------------------------- filters
def _norm(b0, b1, b2, a0, a1, a2):
return (b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0)
def lp(fc, q=0.7071):
w = TAU * min(fc, 0.45 * SR) / SR
c, al = math.cos(w), math.sin(w) / (2 * q)
return _norm((1 - c) / 2, 1 - c, (1 - c) / 2, 1 + al, -2 * c, 1 - al)
def hp(fc, q=0.7071):
w = TAU * min(fc, 0.45 * SR) / SR
c, al = math.cos(w), math.sin(w) / (2 * q)
return _norm((1 + c) / 2, -(1 + c), (1 + c) / 2, 1 + al, -2 * c, 1 - al)
def bp(fc, q=1.0):
w = TAU * min(fc, 0.45 * SR) / SR
c, al = math.cos(w), math.sin(w) / (2 * q)
return _norm(al, 0.0, -al, 1 + al, -2 * c, 1 - al)
def peaking(fc, q, db):
a = 10 ** (db / 40)
w = TAU * min(fc, 0.45 * SR) / SR
c, al = math.cos(w), math.sin(w) / (2 * q)
return _norm(1 + al * a, -2 * c, 1 - al * a, 1 + al / a, -2 * c, 1 - al / a)
def shelf(fc, db, high=True):
a = 10 ** (db / 40)
w = TAU * min(fc, 0.45 * SR) / SR
c, s = math.cos(w), math.sin(w)
al = s / 2 * math.sqrt(2)
sa = 2 * math.sqrt(a) * al
if high:
return _norm(
a * ((a + 1) + (a - 1) * c + sa), -2 * a * ((a - 1) + (a + 1) * c), a * ((a + 1) + (a - 1) * c - sa),
(a + 1) - (a - 1) * c + sa, 2 * ((a - 1) - (a + 1) * c), (a + 1) - (a - 1) * c - sa,
)
return _norm(
a * ((a + 1) - (a - 1) * c + sa), 2 * a * ((a - 1) - (a + 1) * c), a * ((a + 1) - (a - 1) * c - sa),
(a + 1) + (a - 1) * c + sa, -2 * ((a - 1) + (a + 1) * c), (a + 1) + (a - 1) * c - sa,
)
def biquad(x, c):
"""Static biquad (transposed direct form II); c from lp/hp/bp/peaking/shelf."""
b0, b1, b2, a1, a2 = c
z1 = z2 = 0.0
out = [0.0] * len(x)
i = 0
for v in x:
y = b0 * v + z1
z1 = b1 * v - a1 * y + z2
z2 = b2 * v - a2 * y
out[i] = y
i += 1
return out
def svf(x, fc, q=0.7071, mode="lp", ctrl=32):
"""Zero-delay-feedback state-variable filter (Cytomic/Simper), stable under fast modulation.
fc: Hz, or a function of the sample index evaluated every `ctrl` samples.
mode: 'lp', 'bp' or 'hp'.
"""
n = len(x)
out = [0.0] * n
k = 1.0 / q
ic1 = ic2 = 0.0
const = not callable(fc)
if const:
ctrl = max(n, 1)
tan = math.tan
pis = math.pi / SR
for s in range(0, n, ctrl):
f = fc if const else fc(s)
f = 10.0 if f < 10.0 else 20000.0 if f > 20000.0 else f
g = tan(pis * f)
a1 = 1.0 / (1.0 + g * (g + k))
a2 = g * a1
a3 = g * a2
e = s + ctrl if s + ctrl < n else n
if mode == "lp":
for i in range(s, e):
v3 = x[i] - ic2
v1 = a1 * ic1 + a2 * v3
v2 = ic2 + a2 * ic1 + a3 * v3
ic1 = v1 + v1 - ic1
ic2 = v2 + v2 - ic2
out[i] = v2
elif mode == "bp":
for i in range(s, e):
v3 = x[i] - ic2
v1 = a1 * ic1 + a2 * v3
v2 = ic2 + a2 * ic1 + a3 * v3
ic1 = v1 + v1 - ic1
ic2 = v2 + v2 - ic2
out[i] = v1
else:
for i in range(s, e):
xi = x[i]
v3 = xi - ic2
v1 = a1 * ic1 + a2 * v3
v2 = ic2 + a2 * ic1 + a3 * v3
ic1 = v1 + v1 - ic1
ic2 = v2 + v2 - ic2
out[i] = xi - k * v1 - v2
return out
def onepole_hp(x, fc):
"""Gentle 6 dB/oct high-pass; used as a DC blocker."""
a = math.exp(-TAU * fc / SR)
out = [0.0] * len(x)
px = py = 0.0
i = 0
for v in x:
py = a * (py + v - px)
px = v
out[i] = py
i += 1
return out
def sweep(x, start, end, f0, f1, mode="lp", q=0.9, wet_in=0.0, wet_out=0.0):
"""Filter x[start:end] in place, cutoff gliding exponentially f0 -> f1.
wet_in / wet_out (fractions of the region) crossfade from / back to the
dry signal, so the region's edges are seamless.
"""
start, end = max(0, start), min(len(x), end)
n = end - start
if n <= 0:
return
seg = x[start:end]
r = f1 / f0
y = svf(seg, lambda i: f0 * r ** (i / n), q, mode, 32)
a = max(1, int(wet_in * n))
b = max(1, int(wet_out * n))
out = []
for i in range(n):
w = 1.0
if wet_in and i < a:
w = i / a
if wet_out and i > n - b:
w = min(w, (n - i) / b)
out.append(seg[i] + (y[i] - seg[i]) * w)
x[start:end] = out
# ------------------------------------------------------- delay and reverb
_COMBS = (1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617)
_ALLPASSES = (556, 441, 341, 225)
def _comb(x, m, fb, damp):
"""Freeverb comb, block-vectorized; the in-loop damping is a 2-tap low-pass."""
n = len(x)
a = fb * (1.0 - damp)
b = fb * damp
w = [0.0] * (n + m + 1) # w[i + m + 1] = W(i)
for s in range(0, n, m):
e = min(s + m, n)
w[s + m + 1:e + m + 1] = [xi + a * p + b * q for xi, p, q in zip(x[s:e], w[s + 1:e + 1], w[s:e])]
return w[1:n + 1]
def _allpass(x, m, g=0.5):
n = len(x)
v = [0.0] * (n + m) # v[i + m] = V(i)
for s in range(0, n, m):
e = min(s + m, n)
v[s + m:e + m] = [xi + g * p for xi, p in zip(x[s:e], v[s:e])]
return [p - xi for xi, p in zip(x, v)]
def reverb(x, size=0.7, damp=0.45, scale=1.0, spread=23):
"""Freeverb (8 combs + 4 allpasses per side): mono in, (left, right) wet out.
size 0..1 maps to comb feedback 0.7..0.98; scale stretches every delay
(0.3 = small room, 1.5 = hall). Output is roughly level-matched to input.
"""
fb = 0.7 + 0.28 * size
r = SR / 44100 * scale
outs = []
for off in (0, spread):
acc = None
for m in _COMBS:
c = _comb(x, max(8, int((m + off) * r)), fb, damp)
acc = c if acc is None else [p + q for p, q in zip(acc, c)]
for m in _ALLPASSES:
acc = _allpass(acc, max(8, int((m + off) * r)))
outs.append(acc)
g = math.sqrt((1 - fb * fb) / 8.0) * 1.4
return [v * g for v in outs[0]], [v * g for v in outs[1]]
def pingpong(x, d, fb=0.5, damp=0.35):
"""Ping-pong delay, mono in -> (left, right) wet; first echo left at d samples, then alternating."""
n = len(x)
xp = [0.0] * d + x
a = [0.0] * (n + d + 1) # a[i + d + 1] = A(i)
b = [0.0] * (n + d + 1)
c0 = fb * (1.0 - damp)
c1 = fb * damp
for s in range(0, n, d):
e = min(s + d, n)
av = [xi + c0 * p + c1 * q for xi, p, q in zip(xp[s:e], b[s + 1:e + 1], b[s:e])]
bv = [c0 * p + c1 * q for p, q in zip(a[s + 1:e + 1], a[s:e])]
a[s + d + 1:e + d + 1] = av
b[s + d + 1:e + d + 1] = bv
return a[d + 1:], b[d + 1:]
# --------------------------------------------------------------- dynamics
def softclip(x, drive=1.5):
norm = 1.0 / _tanh(drive)
return [_tanh(drive * v) * norm for v in x]
def compress(left, right, thresh_db=-12.0, ratio=2.0, attack=0.01, release=0.15, knee_db=6.0, block=64):
"""Stereo-linked RMS bus compressor at control rate (one gain per block, interpolated)."""
n = len(left)
pw = [a * a + b * b for a, b in zip(left, right)]
ca = math.exp(-block / (attack * SR))
cr = math.exp(-block / (release * SR))
slope = 1.0 / ratio - 1.0
half = knee_db / 2
gr = 0.0
gains = []
# warm the detector on the first second so the start isn't uncompressed
for warm in (True, False):
for s in range(0, n if not warm else min(n, SR), block):
p = sum(pw[s:s + block]) / (2 * block)
db = 10 * math.log10(p + 1e-12)
over = db - thresh_db
if over <= -half:
want = 0.0
elif over < half:
want = slope * (over + half) ** 2 / (2 * knee_db)
else:
want = slope * over
c = ca if want < gr else cr
gr = c * gr + (1 - c) * want
if not warm:
gains.append(10 ** (gr / 20))
ramp = [k / block for k in range(block)]
g = []
prev = gains[0]
for cur in gains:
d = cur - prev
g.extend([prev + d * r for r in ramp])
prev = cur
return [a * b for a, b in zip(left, g)], [a * b for a, b in zip(right, g)]
def mono_below(left, right, fc=120.0):
"""Collapse the side signal below fc (24 dB/oct), so the low end is mono."""
mid = [(a + b) * 0.5 for a, b in zip(left, right)]
side = [(a - b) * 0.5 for a, b in zip(left, right)]
c = hp(fc)
side = biquad(biquad(side, c), c)
return [m + s for m, s in zip(mid, side)], [m - s for m, s in zip(mid, side)]
# --------------------------------------------------------- glitch effects
def crush(x, bits=8, hold=2):
"""Bit and sample-rate reduction (intentionally aliasing)."""
q = float(2 ** (bits - 1))
return [round(x[i - i % hold] * q) / q for i in range(len(x))]
def stutter(x, start, slice_n, repeats, decay=0.9, edge=48):
"""Beat-repeat in place: x[start:start+slice_n] repeated `repeats` times."""
sl = x[start:start + slice_n]
if len(sl) < slice_n:
return
sl = fade(sl[:], edge, edge)
for r in range(repeats):
a = start + r * slice_n
if a + slice_n > len(x):
break
x[a:a + slice_n] = [v * decay ** r for v in sl]
def tapestop(x, start, n, curve=1.6):
"""Tape stop in place over x[start:start+n]: playback slows to zero."""
seg = x[start:start + n]
n = len(seg)
if n < 2:
return
out = []
pos = 0.0
for i in range(n):
j = int(pos)
if j + 1 >= n:
out.append(0.0)
else:
f = pos - j
out.append(seg[j] + (seg[j + 1] - seg[j]) * f)
pos += (1 - i / n) ** curve
fade(out, 0, min(n, 480))
x[start:start + n] = out
+72
View File
@@ -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))
+111
View File
@@ -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))
+23
View File
@@ -0,0 +1,23 @@
# Recorded samples
Real recordings for what synthesis does badly: keyboards, room tone, a mouth pop, a tape eject.
All 12 are CC0 1.0. Each Freesound page was checked for the CC0 licence on 2026-10-18.
Taken from the `sound-effects` skill of github.com/Barty-Bart/motion-graphics (MIT), which had already trimmed them, normalised them (one-shots to -3 dBFS peak, ambience to -35 LUFS) and encoded them as OGG.
Load one in a cue sheet with `sample("<file>")` from `sfx.synth`.
| File | Use | Author | Source |
|---|---|---|---|
| fs-447909-keyboard-typing.ogg | keyboard, 3.8 s | Breviceps | https://freesound.org/people/Breviceps/sounds/447909/ |
| fs-323432-typing.ogg | keyboard, 4 s | Alivvie | https://freesound.org/people/Alivvie/sounds/323432/ |
| fs-79388-keyboard-typing-wav.ogg | keyboard, 4 s | j1987 | https://freesound.org/people/j1987/sounds/79388/ |
| fs-416777-digital-typing-wav.ogg | digital typing, 1 s | Sky_Motion | https://freesound.org/people/Sky_Motion/sounds/416777/ |
| fs-329533-room-tone-in-an-apartment-livi.ogg | room tone, 17 s | leonelmail | https://freesound.org/people/leonelmail/sounds/329533/ |
| fs-426767-apartment-room-tone-wav.ogg | room tone, 20 s | cMilan | https://freesound.org/people/cMilan/sounds/426767/ |
| fs-329569-roomtone-bedroom-yew.ogg | room tone, 20 s | leonelmail | https://freesound.org/people/leonelmail/sounds/329569/ |
| fs-258269-mouth-pop.ogg | mouth pop | jcallison | https://freesound.org/people/jcallison/sounds/258269/ |
| fs-447910-plop.ogg | plop | Breviceps | https://freesound.org/people/Breviceps/sounds/447910/ |
| fs-824189-pop-in-sfx.ogg | pop-in | Sadiquecat | https://freesound.org/people/Sadiquecat/sounds/824189/ |
| fs-349504-triangle-open-04.ogg | triangle ding, 4 s | cabled_mess | https://freesound.org/people/cabled_mess/sounds/349504/ |
| fs-339521-vhs-rewind-forward-and-eject.ogg | VHS rewind and eject, 4 s | lucaslima | https://freesound.org/people/lucaslima/sounds/339521/ |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+206
View File
@@ -0,0 +1,206 @@
"""Shared pieces for the figure scores: a parameterised lo-fi bed and a handful of accents.
A figure's score.py imports this (it sits next to the sfx engine on sys.path when run through
run_sfx.py) and adds its own accents on the tour's seconds.
"""
import math
import os
import random
from sfx.dsp import add, reverb, svf, zeros
from sfx.synth import SR, bandnoise, bass, blip, epiano, hat, kick, snare
def env_fade(x, fin, fout):
n = len(x)
a = max(1, int(fin * SR))
b = max(1, int(fout * SR))
for i in range(min(a, n)):
x[i] *= i / a
for i in range(min(b, n)):
x[n - 1 - i] *= i / b
return x
def bed(dur, bpm, chords, motif=(), motif_voice="epiano", bass_pattern=((0, 1.15, 0.9), (2.5, 0.85, 0.6)),
kicks=(0, 2.75), snares=(1, 3), hats=8, swing=0.12, drums_from=1, keys_lp=4200, crackle_level=0.0, keys_vel=0.9):
"""A looping bed: e-piano chords (one per bar), a bass line, soft drums and an optional motif every other bar.
chords: [([note Hz, ...], root Hz), ...]. bass_pattern: (beat, length in beats, velocity). Returns stereo keys
plus mono bass and drum stems, all faded in and out.
"""
if os.environ.get("FIG_VARIANT"):
# the second-upload variant: three semitones up, a touch faster, the other motif voice
up = 2 ** (3 / 12)
chords = [([f * up for f in notes], root * up) for notes, root in chords]
motif = [(bt, f * up) for bt, f in motif]
motif_voice = "blip" if motif_voice == "epiano" else "epiano"
bpm *= 1.06
beat = 60 / bpm
bar = 4 * beat
n = int(dur * SR)
keys, low, drums = zeros(n), zeros(n), zeros(n)
bars = int(dur / bar) + 1
for b in range(bars):
t = 0.12 + b * bar
notes, root = chords[b % len(chords)]
for i, f in enumerate(notes):
add(keys, epiano(f, 2.9 * 84 / bpm + 0.4, keys_vel), int((t + 0.012 * i) * SR))
if i >= 2:
add(keys, epiano(f, 1.3, keys_vel * 0.5), int((t + 1.5 * beat + 0.01 * i) * SR))
if b % 2 == 1:
for bt, f in motif:
v = epiano(f, 1.1, 0.34, 0.6) if motif_voice == "epiano" else blip(f, 0.32, 0.11)
add(keys, v, int((t + bt * beat) * SR), 1.0 if motif_voice == "epiano" else 0.5)
for bt, length, vel in bass_pattern:
add(low, bass(root, length * beat, vel), int((t + bt * beat) * SR))
if drums_from <= b < bars - 2:
for bt in kicks:
add(drums, kick(1.0 if bt == 0 else 0.75), int((t + bt * beat) * SR))
for bt in snares:
add(drums, snare(0.55), int((t + bt * beat) * SR))
for e in range(hats):
sw = swing * beat if (hats == 8 and e % 2) else 0.0
add(drums, hat(0.5 if e % 2 == 0 else 0.32), int((t + e * 4 * beat / hats + sw) * SR))
keys = svf(keys, keys_lp, 0.6, "lp")
wl, wr = reverb(keys, size=0.6, damp=0.5, scale=0.9)
left = [k * 0.8 + w * 0.36 for k, w in zip(keys, wl)]
right = [k * 0.8 + w * 0.36 for k, w in zip(keys, wr)]
low = svf(low, 900, 0.7, "lp")
drums = svf(drums, 7000, 0.6, "lp")
for buf in (left, right, low, drums):
env_fade(buf, 1.0, 2.2)
return left, right, low, drums
def thud(f=95, decay=0.12, dur=0.4):
"""A soft body hitting something: a plush toy landing, a knock."""
n = int(dur * SR)
return [math.sin(2 * math.pi * f * k / SR) * math.exp(-k / (decay * SR)) * min(1, k / 40) for k in range(n)]
def motor(dur, f0=220, grit_hz=1400, wobble=17):
"""A small electric motor: a buzzy tone plus brush noise, faded at both ends."""
n = int(dur * SR)
grit = bandnoise(n, lambda k: grit_hz, q=0.8)
out = []
for k in range(n):
t = k / SR
m = 1 + 0.15 * math.sin(2 * math.pi * wobble * t)
s = sum(math.sin(2 * math.pi * f0 * h * t) / h for h in (1, 2, 3, 4))
out.append(m * (0.35 * s + 0.5 * grit[k]))
return env_fade(out, 0.06, 0.1)
def airy(dur, f0, f1, level=1.0):
"""Moving air: band noise sweeping from f0 to f1 with a soft swell."""
n = int(dur * SR)
x = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=0.7)
return [x[k] * level * 1.4 * math.sin(math.pi * k / n) for k in range(n)]
def bang(level=1.0, seed=0):
"""A small explosion: a low punch and a burst of dark noise."""
rnd = random.Random(seed)
n = int(0.42 * SR)
noise = bandnoise(n, lambda k: 700 + 1600 * math.exp(-k / (0.03 * SR)), q=0.5)
out = []
ph = 0.0
for k in range(n):
t = k / SR
f = 48 + 90 * math.exp(-t / 0.03)
ph += 2 * math.pi * f / SR
s = math.sin(ph) * math.exp(-t / 0.12) * 1.1 + noise[k] * 1.8 * math.exp(-t / 0.05)
out.append(level * math.tanh(1.5 * s) * (0.92 + 0.08 * rnd.random()))
return out
def puff(level=1.0):
"""A breath of gas out of a pipe."""
n = int(0.3 * SR)
x = bandnoise(n, lambda k: 900, q=0.6)
return [level * x[k] * 1.6 * math.sin(math.pi * min(1, k / (0.06 * SR)) / 2) * math.exp(-k / (0.09 * SR)) for k in range(n)]
def rumble(dur, f_at, level=1.0):
"""An engine's low hum whose pitch follows f_at(t)."""
n = int(dur * SR)
out = []
ph = 0.0
for k in range(n):
f = f_at(k / SR)
ph += 2 * math.pi * f / SR
out.append(level * (math.sin(ph) + 0.4 * math.sin(2 * ph) + 0.2 * math.sin(3 * ph)))
return env_fade(out, 0.3, 0.4)
_SEMI = {"C": -9, "D": -7, "E": -5, "F": -4, "G": -2, "A": 0, "B": 2}
def hz(name):
"""Note name to frequency: "A4" = 440, "F#3", "Bb2"."""
base, rest = name[0], name[1:]
shift = 0
while rest and rest[0] in "#b":
shift += 1 if rest[0] == "#" else -1
rest = rest[1:]
return 440.0 * 2 ** ((_SEMI[base] + shift + 12 * (int(rest) - 4)) / 12)
def chords(*specs):
"""chords("Fmaj7:F3 A3 C4 E4/F2", ...) -> bed() chord list; the part after / is the bass root."""
out = []
for spec in specs:
notes, root = spec.split(":", 1)[1].split("/")
out.append(([hz(n) for n in notes.split()], hz(root.strip())))
return out
def beep(freq, dur=0.12, level=1.0):
"""A clean electronic beep: a keypad, a timer, a piezo horn."""
n = int(dur * SR)
a = max(1, int(0.004 * SR))
return [level * math.sin(2 * math.pi * freq * k / SR) * min(1, k / a, (n - k) / a) for k in range(n)]
def rattle(dur, rate=18.0, f=3200, seed=0, level=1.0):
"""Many small hard things settling: coins in a box, shavings, capsules."""
rnd = random.Random(seed)
n = int(dur * SR)
out = zeros(n)
t = 0.0
while t < dur:
k = int(t * SR)
tick = [math.sin(2 * math.pi * f * (0.7 + 0.6 * rnd.random()) * j / SR) * math.exp(-j / (0.004 * SR)) for j in range(int(0.03 * SR))]
add(out, tick, k, level * (0.4 + 0.6 * rnd.random()) * math.sin(math.pi * min(1.0, t / dur)))
t += rnd.expovariate(rate)
return out
def hiss(dur, fc=5200, level=1.0):
"""Steam or air escaping: bright band noise with a soft swell."""
n = int(dur * SR)
x = bandnoise(n, lambda k: fc, q=0.5)
return [x[k] * level * 1.3 * min(1, k / (0.15 * SR), (n - k) / (0.25 * SR)) for k in range(n)]
def spans(tl, field, pred):
"""Intervals (t0, t1) in seconds where pred(sampled value of field) holds, from a timeline made with --sample."""
i = tl["fields"].index(field)
rate, out, start = tl["rate"], [], None
for k, row in enumerate(tl["samples"]):
on = bool(pred(row[i]))
if on and start is None:
start = k / rate
elif not on and start is not None:
out.append((start, k / rate))
start = None
if start is not None:
out.append((start, len(tl["samples"]) / rate))
return out
def rising(tl, field, pred):
"""Moments where pred(sampled value) turns true."""
return [a for a, _ in spans(tl, field, pred)]
+294
View File
@@ -0,0 +1,294 @@
"""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; `python run_sfx.py --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 array
import bisect
import math
import os
import random
import subprocess
SR = 48000
FFMPEG = r"C:\Users\user_\.claude\bin\ffmpeg.exe"
SAMPLES = os.path.join(os.path.dirname(os.path.abspath(__file__)), "samples")
def sample(name, start=0.0, dur=None):
"""Recorded sound from sfx/samples (or any path): keyboards, room tone. start/dur trim it in seconds."""
path = name if os.path.isabs(name) else os.path.join(SAMPLES, name)
cmd = [FFMPEG, "-v", "error", "-ss", str(start), "-i", path]
if dur is not None:
cmd += ["-t", str(dur)]
cmd += ["-ac", "1", "-ar", str(SR), "-f", "s16le", "-"]
raw = subprocess.run(cmd, check=True, capture_output=True).stdout
pcm = array.array("h")
pcm.frombytes(raw[: len(raw) // 2 * 2])
return [x / 32768 for x in pcm]
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
# ---------------------------------------------------------------- a small band, for music beds
# Added 2026-10-18 for the coffee-machine film. Soft, warm, low in the mix: the bed sits under the picture,
# the accents (clicks, hiss) sit on top of it.
def epiano(freq, dur=2.6, vel=1.0, decay=1.1):
"""Electric-piano note (tine and warm body), for lo-fi chords. Keep freq in key; vel 0..1."""
n = int(dur * SR)
out = [0.0] * n
w1 = 2 * math.pi * freq / SR
w2 = 2 * w1
wt = 2 * math.pi * freq * 6.98 / SR
wtrem = 2 * math.pi * 4.6 / SR
sin = math.sin
exp = math.exp
for k in range(n):
t = k / SR
a = (t / 0.006 if t < 0.006 else 1.0) * exp(-t / decay)
body = sin(w1 * k) + 0.28 * sin(w2 * k) * exp(-t / 0.5)
tine = 0.16 * sin(wt * k) * exp(-t / 0.09)
out[k] = vel * a * (body + tine) * (1 + 0.1 * sin(wtrem * k))
tail = min(n, int(0.08 * SR))
for i in range(tail):
out[n - 1 - i] *= i / tail
return out
def bass(freq, dur=0.9, vel=1.0):
"""Round bass note: sine plus a little second harmonic, gently saturated. Roots under the chords."""
n = int(dur * SR)
out = [0.0] * n
w = 2 * math.pi * freq / SR
sin = math.sin
exp = math.exp
for k in range(n):
t = k / SR
a = (t / 0.012 if t < 0.012 else 1.0) * exp(-t / 0.45)
out[k] = math.tanh(1.4 * vel * a * (sin(w * k) + 0.22 * sin(2 * w * k)))
tail = min(n, int(0.05 * SR))
for i in range(tail):
out[n - 1 - i] *= i / tail
return out
def kick(vel=1.0):
"""Soft kick: a sine dropping from 110 to 46 Hz. Lo-fi, not club."""
n = int(0.32 * SR)
out = [0.0] * n
ph = 0.0
for k in range(n):
t = k / SR
f = 46 + 64 * math.exp(-t / 0.035)
ph += 2 * math.pi * f / SR
out[k] = vel * math.sin(ph) * math.exp(-t / 0.11) * min(1.0, t / 0.002)
return out
def snare(vel=1.0):
"""Brushed snare: band-passed noise with a short body tone, for beats 2 and 4."""
n = int(0.22 * SR)
noise = bandnoise(n, lambda k: 2100, q=0.55)
return [vel * (noise[k] * 1.6 * math.exp(-k / (0.06 * SR)) + 0.25 * math.sin(2 * math.pi * 190 * k / SR) * math.exp(-k / (0.025 * SR))) for k in range(n)]
def hat(vel=1.0):
"""Closed hat tick: high band noise, very short. Swing the off-beats."""
n = int(0.05 * SR)
noise = bandnoise(n, lambda k: 7600, q=0.4)
return [vel * noise[k] * 1.8 * math.exp(-k / (0.011 * SR)) for k in range(n)]
def crackle(dur, density=7.0, hiss=0.012):
"""Vinyl crackle bed: sparse clicks over a faint hiss. density is clicks per second."""
n = int(dur * SR)
out = [random.uniform(-1, 1) * hiss for _ in range(n)]
for _ in range(int(dur * density)):
at = random.randrange(n)
g = random.uniform(0.05, 0.35) * random.choice((-1, 1))
for i in range(min(40, n - at)):
out[at + i] += g * math.exp(-i / 6.0)
return out