@olegkoval/agent-skills 1.60.0 → 1.62.0

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/audio/dsp.ts

@@ -0,0 +1,193 @@
+// DSP kit: rng, filters, oscillators, envelopes, noise, reverb, delay, mixing.
+// The only state is a typed array a function allocates (or is handed as its output buffer), plus a filter's
+// own memory and a seeded rng closure.
+export const SR = 48000;
+export const TAU = Math.PI * 2;
+
+export type Rng = () => number;
+export type Stereo = { readonly L: Float32Array; readonly R: Float32Array };
+export type Bus = Stereo & { readonly n: number };
+export type Voice = Float32Array | Stereo;
+
+export const rng = (seed: number): Rng => {
+  let s = seed >>> 0 || 1;
+  return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
+};
+export const human = (r: Rng, amt = 0.1): number => 1 - amt / 2 + r() * amt;
+export const mtof = (m: number): number => 440 * Math.pow(2, (m - 69) / 12);
+export const dbToGain = (db: number): number => Math.pow(10, db / 20);
+export const clamp = (x: number, a: number, b: number): number => Math.max(a, Math.min(b, x));
+
+// ---------- buses and mixing ----------
+export function makeBus(sec: number): Bus {
+  const n = Math.ceil(sec * SR);
+  return { L: new Float32Array(n), R: new Float32Array(n), n };
+}
+const isStereo = (v: Voice): v is Stereo => !(v instanceof Float32Array);
+
+// mix a mono or stereo voice in at time `at` (seconds), equal-power pan -1..1
+export function busAdd(bus: Bus, v: Voice, at: number, gain = 1, pan = 0): void {
+  const i0 = Math.round(at * SR);
+  const pl = Math.cos((pan + 1) * Math.PI / 4) * Math.SQRT2, pr = Math.sin((pan + 1) * Math.PI / 4) * Math.SQRT2;
+  const vl = isStereo(v) ? v.L : v, vr = isStereo(v) ? v.R : v;
+  for (let i = 0; i < vl.length; i++) {
+    const j = i0 + i;
+    if (j < 0) continue;
+    if (j >= bus.n) break;
+    bus.L[j] += vl[i] * gain * pl;
+    bus.R[j] += vr[i] * gain * pr;
+  }
+}
+export function busMixFrom(dst: Bus, b: Bus, gain = 1): void {
+  for (let i = 0; i < dst.n && i < b.n; i++) { dst.L[i] += b.L[i] * gain; dst.R[i] += b.R[i] * gain; }
+}
+export function busGain(bus: Bus, k: number): void {
+  for (let i = 0; i < bus.n; i++) { bus.L[i] *= k; bus.R[i] *= k; }
+}
+
+// ---------- typed-array helpers ----------
+export const tabulate = (n: number, f: (i: number) => number): Float32Array => Float32Array.from({ length: n }, (_, i) => f(i));
+export function addInto(dst: Float32Array, src: Float32Array, off: number, f: (x: number) => number): void {
+  for (let i = 0; i < src.length && i + off < dst.length; i++) dst[i + off] += f(src[i]);
+}
+export function scaleBy(a: Float32Array, g: (i: number) => number): Float32Array {
+  for (let i = 0; i < a.length; i++) a[i] *= g(i);
+  return a;
+}
+export function mulInto(a: Float32Array, b: Float32Array): Float32Array {
+  for (let i = 0; i < a.length; i++) a[i] *= b[i] ?? 0;
+  return a;
+}
+
+// ---------- RBJ biquad ----------
+export type FilterType = "lp" | "hp" | "bp" | "lowshelf" | "highshelf";
+type Coefs = readonly [number, number, number, number, number, number];
+type Terms = { readonly cs: number; readonly a: number; readonly A: number };
+
+const shelf = (sg: number) => ({ cs, a, A }: Terms): Coefs => {
+  const s = Math.sqrt(A) * 2 * a;
+  return [
+    A * ((A + 1) - sg * (A - 1) * cs + s), 2 * sg * A * ((A - 1) - sg * (A + 1) * cs), A * ((A + 1) - sg * (A - 1) * cs - s),
+    (A + 1) + sg * (A - 1) * cs + s, -2 * sg * ((A - 1) + sg * (A + 1) * cs), (A + 1) + sg * (A - 1) * cs - s,
+  ];
+};
+const COEF: Record<FilterType, (t: Terms) => Coefs> = {
+  lp: ({ cs, a }) => { const b0 = (1 - cs) / 2; return [b0, 1 - cs, b0, 1 + a, -2 * cs, 1 - a]; },
+  hp: ({ cs, a }) => { const b0 = (1 + cs) / 2; return [b0, -(1 + cs), b0, 1 + a, -2 * cs, 1 - a]; },
+  bp: ({ cs, a }) => [a, 0, -a, 1 + a, -2 * cs, 1 - a],
+  lowshelf: shelf(1),
+  highshelf: shelf(-1),
+};
+function coef(type: FilterType, f: number, q: number, db: number): readonly [number, number, number, number, number] {
+  const w = TAU * clamp(f, 10, SR / 2.2) / SR, cs = Math.cos(w), sn = Math.sin(w);
+  const [b0, b1, b2, a0, a1, a2] = COEF[type]({ cs, a: sn / (2 * q), A: Math.pow(10, db / 40) });
+  return [b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0];
+}
+export type Filter = (x: number) => number;
+export type Biquad = Filter & { set(f: number, q?: number): void };
+
+// the filter's own memory is a closure; `set` retunes it mid-stream (the riser sweeps its band)
+export function biquad(type: FilterType, f: number, q = 0.707, db = 0): Biquad {
+  let c = coef(type, f, q, db);
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+  const run: Filter = (x) => { const y = c[0] * x + c[1] * x1 + c[2] * x2 - c[3] * y1 - c[4] * y2; x2 = x1; x1 = x; y2 = y1; y1 = y; return y; };
+  const set = (nf: number, nq = q): void => { c = coef(type, nf, nq, db); };
+  return Object.assign(run, { set });
+}
+export function filt(buf: Float32Array, ...fs: readonly Filter[]): Float32Array {
+  for (const f of fs) for (let i = 0; i < buf.length; i++) buf[i] = f(buf[i]);
+  return buf;
+}
+
+// ---------- oscillators, envelopes, noise ----------
+// band-limited saw (polyBLEP)
+function blep(t: number, dt: number): number {
+  if (t < dt) { const u = t / dt; return u + u - u * u - 1; }
+  if (t > 1 - dt) { const u = (t - 1) / dt; return u * u + u + u + 1; }
+  return 0;
+}
+const SHAPES = {
+  sine: (ph: number) => Math.sin(TAU * ph),
+  saw: (ph: number, dt: number) => 2 * ph - 1 - blep(ph, dt),
+};
+export function osc(kind: keyof typeof SHAPES, freq: number, sec: number, phase = 0): Float32Array {
+  const n = Math.ceil(sec * SR), out = new Float32Array(n), shape = SHAPES[kind], dt = freq / SR;
+  let ph = phase;
+  for (let i = 0; i < n; i++) {
+    out[i] = shape(ph, dt);
+    ph += dt; if (ph >= 1) ph -= 1;
+  }
+  return out;
+}
+// attack / decay / sustain / release envelope over `sec`
+export function adsr(sec: number, a: number, d: number, s: number, r: number): Float32Array {
+  const n = Math.ceil(sec * SR), A = a * SR, D = d * SR, R = r * SR, hold = n - R;
+  return tabulate(n, (i) => {
+    const v = i < A ? i / A : i < A + D ? 1 - (1 - s) * ((i - A) / D) : s;
+    return i > hold ? v * Math.max(0, 1 - (i - hold) / R) : v;
+  });
+}
+export const expDecay = (sec: number, tau: number): Float32Array => tabulate(Math.ceil(sec * SR), (i) => Math.exp(-i / (tau * SR)));
+
+export function noise(sec: number, r: Rng, pink = false): Float32Array {
+  const n = Math.ceil(sec * SR), o = new Float32Array(n);
+  if (!pink) { for (let i = 0; i < n; i++) o[i] = r() * 2 - 1; return o; }
+  let b0 = 0, b1 = 0, b2 = 0;
+  for (let i = 0; i < n; i++) {
+    const w = r() * 2 - 1;
+    b0 = 0.99765 * b0 + w * 0.099046; b1 = 0.963 * b1 + w * 0.2965164; b2 = 0.57 * b2 + w * 1.0526913;
+    o[i] = (b0 + b1 + b2 + w * 0.1848) * 0.2;
+  }
+  return o;
+}
+
+// ---------- Freeverb (Jezar), stereo, tuned for 48 kHz ----------
+type Lines = { readonly buf: readonly Float32Array[]; readonly idx: Int32Array };
+const makeLines = (taps: readonly number[], spread: number): Lines => ({ buf: taps.map((t) => new Float32Array(t + spread)), idx: new Int32Array(taps.length) });
+
+function combSum(c: Lines, flt: Float64Array, x: number, room: number, damp: number): number {
+  let y = 0;
+  for (let j = 0; j < c.buf.length; j++) {
+    const b = c.buf[j], o = b[c.idx[j]];
+    flt[j] = o * (1 - damp) + flt[j] * damp;
+    b[c.idx[j]] = x + flt[j] * room;
+    c.idx[j] = (c.idx[j] + 1) % b.length;
+    y += o;
+  }
+  return y;
+}
+function allpass(a: Lines, input: number): number {
+  let y = input;
+  for (let j = 0; j < a.buf.length; j++) {
+    const b = a.buf[j], o = b[a.idx[j]], v = -y + o;
+    b[a.idx[j]] = y + o * 0.5;
+    a.idx[j] = (a.idx[j] + 1) % b.length;
+    y = v;
+  }
+  return y;
+}
+export function reverb(bus: Bus, { room = 0.82, damp = 0.35, wet = 1 } = {}): Bus {
+  const k = SR / 44100;
+  const combT = [1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617].map((x) => Math.round(x * k));
+  const apT = [556, 441, 341, 225].map((x) => Math.round(x * k));
+  const out = makeBus(bus.n / SR);
+  const channels: readonly (readonly [Float32Array, Float32Array, number])[] = [[bus.L, out.L, 0], [bus.R, out.R, Math.round(23 * k)]];
+  for (const [src, dst, spread] of channels) {
+    const combs = makeLines(combT, spread), aps = makeLines(apT, spread), flt = new Float64Array(combT.length);
+    for (let n = 0; n < bus.n; n++) dst[n] = allpass(aps, combSum(combs, flt, src[n] * 0.015, room, damp)) * wet;
+  }
+  return out;
+}
+
+// ping-pong delay
+export function delay(bus: Bus, time: number, fb = 0.35, lp = 4500): Bus {
+  const d = Math.round(time * SR), out = makeBus(bus.n / SR);
+  const bl = new Float32Array(d), br = new Float32Array(d);
+  const fl = biquad("lp", lp), fr = biquad("lp", lp);
+  for (let i = 0, j = 0; i < bus.n; i++, j = (j + 1) % d) {
+    const ol = bl[j], or = br[j];
+    bl[j] = fl(bus.L[i] + or * fb); br[j] = fr(bus.R[i] * 0.4 + ol * fb);
+    out.L[i] = ol; out.R[i] = or;
+  }
+  return out;
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/audio/instruments.ts

@@ -0,0 +1,185 @@
+// Voiced to sound played, not like a ringtone: electric piano, felt plucks, warm pads, a round sub and
+// soft drums, all in the low and middle register. Nothing melodic sits above about B4, no bare sine or
+// square plays up high, and every source is low-passed before it reaches the mix.
+import {
+  SR, TAU, addInto, adsr, biquad, expDecay, filt, human, mtof, mulInto, noise, osc, scaleBy, tabulate,
+} from "./dsp.ts";
+import type { Rng, Stereo } from "./dsp.ts";
+
+// ---------- drums ----------
+type KickOpts = { pitch?: number; dec?: number; punch?: number };
+
+function kickBody(n: number, pitch: number, dec: number, punch: number): Float32Array {
+  const o = new Float32Array(n);
+  let ph = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    ph += pitch * (1 + 1.1 * punch * Math.exp(-t / 0.035)) / SR;
+    o[i] = Math.sin(TAU * ph) * Math.exp(-t / (dec * 0.45)) * Math.min(1, i / 48);
+  }
+  return o;
+}
+// round kick: a short sweep down to the fundamental, a felt click, a little saturation
+export function kick(r: Rng, { pitch = 50, dec = 0.36, punch = 1 }: KickOpts = {}): Float32Array {
+  const sec = dec + 0.12, n = Math.ceil(sec * SR), o = kickBody(n, pitch, dec, punch);
+  const click = filt(mulInto(noise(0.01, r), expDecay(0.01, 0.002)), biquad("lp", 1400));
+  addInto(o, click, 0, (x) => x * 0.18 * punch);
+  for (let i = 0; i < n; i++) o[i] = Math.tanh(o[i] * 1.3) / Math.tanh(1.3);
+  return o;
+}
+
+type SnareOpts = { tone?: number; dec?: number; top?: number };
+// a soft, dusty snare: a short tuned body and a band of noise with the top rolled off
+export function snare(r: Rng, { tone = 190, dec = 0.14, top = 7000 }: SnareOpts = {}): Float32Array {
+  const sec = dec * 3, n = Math.ceil(sec * SR), o = new Float32Array(n);
+  let ph = 0;
+  for (let i = 0; i < n; i++) { const t = i / SR; ph += tone * (1 + 0.25 * Math.exp(-t / 0.01)) / SR; o[i] = Math.sin(TAU * ph) * Math.exp(-t / 0.045) * 0.7; }
+  const nz = filt(mulInto(noise(sec, r, true), expDecay(sec, dec * 0.6)), biquad("bp", 1700, 0.6), biquad("lp", top), biquad("hp", 300));
+  return tabulate(n, (i) => (o[i] + nz[i] * 3.2) * Math.min(1, i / 72));
+}
+// brush: a slow-onset sweep of noise, no crack
+export function brush(r: Rng): Float32Array {
+  const o = filt(noise(0.28, r, true), biquad("bp", 2200, 0.5), biquad("lp", 7000), biquad("hp", 450));
+  return scaleBy(o, (i) => { const t = i / SR; return Math.min(1, t / 0.018) * Math.exp(-t / 0.09) * 2.4; });
+}
+// a closed hat with the fizz taken off (nothing above ~9 kHz)
+export function hat(r: Rng): Float32Array {
+  const o = filt(noise(0.07, r), biquad("hp", 5600, 0.7), biquad("lp", 11000));
+  return scaleBy(o, (i) => { const t = i / SR; return Math.min(1, i / 96) * Math.exp(-t / 0.018); });
+}
+// shaker: a short grain of high noise with a soft onset (the light percussion of a calm bed)
+export function shaker(r: Rng): Float32Array {
+  const o = filt(noise(0.09, r), biquad("bp", 4200, 1.1), biquad("lp", 9000));
+  return scaleBy(o, (i) => { const t = i / SR; return Math.min(1, t / 0.008) * Math.exp(-t / 0.03) * 1.6; });
+}
+function crackle(o: Float32Array, i: number, r: Rng): void {
+  const a = (r() * 0.6 + 0.2) * (r() < 0.5 ? -1 : 1);
+  for (let k = 0; k < 30 && i + k < o.length; k++) o[i + k] += a * Math.exp(-k / 6);
+}
+// vinyl: sparse soft crackle and a little low hiss (the lofi bed's air)
+export function vinyl(sec: number, r: Rng): Float32Array {
+  const n = Math.ceil(sec * SR), o = new Float32Array(n);
+  for (let i = 0; i < n; i++) if (r() < 0.00035) crackle(o, i, r);
+  addInto(o, noise(sec, r, true), 0, (x) => x * 0.05);
+  return filt(o, biquad("lp", 3200), biquad("hp", 250));
+}
+
+// ---------- bass and keys ----------
+type BassOpts = { a?: number; r?: number; drive?: number; tone?: number };
+// sub bass: a sine with a touch of its own second harmonic, so it still reads on a phone speaker
+export function bass(note: number, sec: number, { a = 0.006, r = 0.08, drive = 1.3, tone = 0.18 }: BassOpts = {}): Float32Array {
+  const f = mtof(note), n = Math.ceil(sec * SR), env = adsr(sec, a, 0.18, 0.75, r);
+  const o = tabulate(n, (i) => {
+    const t = i / SR, x = Math.sin(TAU * f * t) + tone * Math.sin(TAU * 2 * f * t + 0.6);
+    return Math.tanh(x * drive) / Math.tanh(drive) * env[i];
+  });
+  return filt(o, biquad("lp", 520));
+}
+
+// electric piano (FM, Rhodes-like): a 1:1 pair for the body and the bark of a harder hit, the tine
+// short and quiet, rounder the softer it's played; low notes ring longer. `rh` feeds the hammer noise.
+export function ep(note: number, sec: number, vel: number, rh: Rng): Float32Array {
+  const f = mtof(note), n = Math.ceil(sec * SR);
+  const ham = scaleBy(filt(mulInto(noise(0.03, rh), expDecay(0.03, 0.006)), biquad("bp", 2600, 0.7)), () => 1.6 * vel);
+  const idx = 0.5 + 1.7 * vel, tau = 0.7 + 1.8 * Math.exp(-(note - 48) / 16), rel = Math.min(n, Math.round(0.09 * SR));
+  const o = tabulate(n, (i) => {
+    const t = i / SR, I = idx * Math.exp(-t / 0.25) + 0.15;
+    const body = Math.sin(TAU * f * t + I * Math.sin(TAU * f * t));
+    const tine = Math.sin(TAU * f * 4 * t) * Math.exp(-t / 0.025) * 0.12 * vel + (ham[i] || 0);
+    const e = Math.min(1, i / (0.003 * SR)) * Math.exp(-t / tau);
+    return (body + tine) * (i > n - rel ? e * ((n - i) / rel) : e) * (0.55 + 0.45 * vel);
+  });
+  return filt(o, biquad("lp", 2200 + 3000 * vel, 0.6), biquad("hp", 70));
+}
+type ChordOpts = { roll?: number; trem?: number };
+// a chord on the electric piano: slightly rolled, with a slow stereo tremolo
+export function epChord(notes: readonly number[], sec: number, vel: number, r: Rng, rh: Rng, { roll = 0.012, trem = 0.18 }: ChordOpts = {}): Stereo {
+  const n = Math.ceil((sec + roll * notes.length) * SR), L = new Float32Array(n), R = new Float32Array(n);
+  const share = (x: number) => x / notes.length * 1.8;
+  notes.forEach((m, k) => {
+    const v = ep(m, sec, vel * human(r, 0.16), rh), off = Math.round(k * roll * SR * human(r, 0.6));
+    addInto(L, v, off, share); addInto(R, v, off, share);
+  });
+  const ph = r() * TAU;
+  for (let i = 0; i < n; i++) { const p = trem * Math.sin(TAU * 4.6 * i / SR + ph); L[i] *= 1 - p; R[i] *= 1 + p; }
+  return { L, R };
+}
+
+// ---------- plucks, pads, synth ----------
+type PluckOpts = { bright?: number; decay?: number };
+// felt pluck (Karplus-Strong, dark): muted guitar, kalimba or felt piano, with a warm body under it
+export function pluck(note: number, sec: number, r: Rng, { bright = 0.25, decay = 0.995 }: PluckOpts = {}): Float32Array {
+  const f = mtof(note), p = Math.max(2, Math.round(SR / f)), n = Math.ceil(sec * SR), o = new Float32Array(n);
+  const buf = new Float32Array(p);
+  for (let i = 0; i < p; i++) buf[i] = r() * 2 - 1;
+  const pre = biquad("lp", 500 + bright * 3000);
+  filt(buf, pre, pre);
+  let last = 0;
+  for (let i = 0; i < n; i++) {
+    const j = i % p, v = buf[j];
+    buf[j] = (v + last) * 0.5 * decay;
+    last = v; o[i] = v;
+  }
+  for (let i = 0; i < n; i++) o[i] += Math.sin(TAU * f * i / SR) * Math.exp(-i / SR / 0.25) * 0.25;
+  return filt(mulInto(o, adsr(sec, 0.003, 0.05, 1, 0.1)), biquad("hp", 90), biquad("lp", 5200));
+}
+// a strummed chord on the felt pluck (the guitar's ending)
+export function strum(notes: readonly number[], sec: number, r: Rng, o: PluckOpts = {}): Float32Array {
+  const n = Math.ceil((sec + 0.2) * SR), out = new Float32Array(n);
+  notes.forEach((m, k) => addInto(out, pluck(m, sec, r, o), Math.round(k * 0.028 * SR), (x) => x * 0.55));
+  return out;
+}
+
+type PadOpts = { cutoff?: number; attack?: number; release?: number; detune?: number };
+// the saws, detuned across a note's four voices and split left/right, summed before filtering
+function padSaws(notes: readonly number[], sec: number, r: Rng, detune: number): Stereo {
+  const n = Math.ceil(sec * SR), L = new Float32Array(n), R = new Float32Array(n);
+  for (const m of notes) {
+    for (let k = 0; k < 4; k++) addInto(k % 2 ? R : L, osc("saw", mtof(m + (k - 1.5) * detune / 1.5), sec, r()), 0, (x) => x * 0.16);
+  }
+  return { L, R };
+}
+// a warm pad: detuned saws through a steep low-pass, a sine an octave under, slow in and out, stereo
+export function pad(notes: readonly number[], sec: number, r: Rng, { cutoff = 2600, attack = 0.8, release = 1.4, detune = 0.07 }: PadOpts = {}): Stereo {
+  const { L, R } = padSaws(notes, sec, r, detune), n = L.length;
+  const lo = osc("sine", mtof(notes[0] - 12), sec);
+  const env = adsr(sec, attack, 0.5, 0.85, release);
+  const f = [biquad("lp", cutoff, 0.55), biquad("lp", cutoff, 0.55), biquad("lp", cutoff * 1.1, 0.55), biquad("lp", cutoff * 1.1, 0.55)];
+  const h = [biquad("hp", 110), biquad("hp", 110)];
+  const g = 2.2 / notes.length;
+  const air = filt(noise(sec, r, true), biquad("bp", 3800, 0.6), biquad("lp", 9000));
+  for (let i = 0; i < n; i++) {
+    L[i] = (h[0](f[2](f[0](L[i]))) * g + lo[i] * 0.12 + air[i] * 0.1) * env[i];
+    R[i] = (h[1](f[3](f[1](R[i]))) * g + lo[i] * 0.12 - air[i] * 0.1) * env[i];
+  }
+  return { L, R };
+}
+// a soft, low synth note (Terminal's arpeggio): a saw through a low filter
+export function softSynth(note: number, sec: number, cut = 1800): Float32Array {
+  const o = osc("saw", mtof(note), sec), f = biquad("lp", cut, 0.7);
+  for (let i = 0; i < o.length; i++) { const t = i / SR; o[i] = f(o[i]) * Math.min(1, i / 120) * Math.exp(-t / (sec * 0.6)); }
+  return o;
+}
+
+// ---------- the ending ----------
+// a low, dark swell that grows into its end (a hiss climbing to the sky is what sounds cheap)
+export function outroRiser(r: Rng, sec: number): Stereo {
+  const n = Math.ceil(sec * SR), L = new Float32Array(n), R = new Float32Array(n);
+  const src = noise(sec, r, true), bl = biquad("bp", 140, 0.8), br = biquad("bp", 140, 0.8), ll = biquad("lp", 2200), lr = biquad("lp", 2200);
+  const fo = Math.round(0.04 * SR);
+  for (let i = 0; i < n; i++) {
+    const k = i / n, f = 140 * Math.pow(1600 / 140, k * k);
+    if (i % 32 === 0) { bl.set(f, 0.8); br.set(f * 1.04, 0.8); }
+    const env = Math.pow(k, 2.2) * (i > n - fo ? (n - i) / fo : 1) * 2.6;
+    L[i] = ll(bl(src[i])) * env; R[i] = lr(br(src[i])) * env;
+  }
+  return { L, R };
+}
+// one deep hit with a breath of air after it
+export function outroImpact(r: Rng, note: number): Stereo {
+  const n = Math.ceil(2.4 * SR), L = new Float32Array(n), R = new Float32Array(n);
+  const boom = filt(kick(r, { pitch: mtof(note - 24) * 0.9, punch: 0.4, dec: 1.4 }), biquad("lp", 700));
+  const air = filt(mulInto(noise(1.3, r, true), expDecay(1.3, 0.3)), biquad("lp", 1100), biquad("hp", 90));
+  for (let i = 0; i < n; i++) { const b = boom[i] || 0, a = air[i] || 0; L[i] = b * 0.9 + a * 0.45; R[i] = b * 0.9 + a * 0.4; }
+  return { L, R };
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/audio/master.ts

@@ -0,0 +1,55 @@
+// Mastering: gentle bus glue and a look-ahead brickwall, peaks held under the ceiling without pumping.
+import { SR, biquad, dbToGain } from "./dsp.ts";
+import type { Bus } from "./dsp.ts";
+
+// presence (the instruments are voiced dark, so the top is lifted broadly, never a narrow treble boost)
+// and a little tape saturation. The filters keep per-channel memory, so each channel gets its own.
+function eqChannel(ch: Float32Array): void {
+  const hp = biquad("hp", 32), lo = biquad("lowshelf", 110, 0.7, -1.5), hi = biquad("highshelf", 2200, 0.6, 5);
+  for (let i = 0; i < ch.length; i++) ch[i] = Math.tanh(1.15 * hi(lo(hp(ch[i])))) / Math.tanh(1.15);
+}
+// a soft knee on the loudest transients first, so the limiter barely has to work
+function softKnee(ch: Float32Array, knee: number): void {
+  for (let i = 0; i < ch.length; i++) {
+    const x = ch[i], a = Math.abs(x);
+    if (a > knee) ch[i] = Math.sign(x) * (knee + (1 - knee) * Math.tanh((a - knee) / (1 - knee)));
+  }
+}
+// sample peaks and the half-sample peaks between them (cubic interpolation ~ true peak)
+const half = (x: Float32Array, i: number): number => (-(x[i - 1] || 0) + 9 * x[i] + 9 * (x[i + 1] || 0) - (x[i + 2] || 0)) / 16;
+const peakAmp = (bus: Bus): Float32Array =>
+  Float32Array.from({ length: bus.n }, (_, i) => Math.max(Math.abs(bus.L[i]), Math.abs(bus.R[i]), Math.abs(half(bus.L, i)), Math.abs(half(bus.R, i))));
+
+// the exact max over the next `look` samples (monotonic queue); kept as one loop, the queue is the mechanism
+function wantedGain(amp: Float32Array, look: number, ceil: number): Float32Array {
+  const n = amp.length, want = new Float32Array(n), q = new Int32Array(n);
+  let h = 0, t = 0;
+  for (let i = 0, j = 0; i < n; i++) {
+    for (; j < Math.min(n, i + look); j++) { while (t > h && amp[q[t - 1]] <= amp[j]) t--; q[t++] = j; }
+    while (q[h] < i) h++;
+    const pk = amp[q[h]];
+    want[i] = pk > ceil ? ceil / pk : 1;
+  }
+  return want;
+}
+// gain glides down before a peak arrives (attack over the look-ahead) and recovers over ~120 ms
+function applyGlide(bus: Bus, want: Float32Array): void {
+  const rel = Math.exp(-1 / (0.12 * SR));
+  let g = 1;
+  for (let i = 0; i < bus.n; i++) {
+    const w = want[i];
+    g = w < g ? w : w - (w - g) * rel;
+    bus.L[i] *= g; bus.R[i] *= g;
+  }
+}
+const hardClip = (ch: Float32Array, ceil: number): void => {
+  for (let i = 0; i < ch.length; i++) { if (ch[i] > ceil) ch[i] = ceil; else if (ch[i] < -ceil) ch[i] = -ceil; }
+};
+
+export function master(bus: Bus, eq = true): void {
+  if (eq) { eqChannel(bus.L); eqChannel(bus.R); }
+  const knee = dbToGain(-6), look = Math.round(0.005 * SR), ceil = dbToGain(-2.3);
+  softKnee(bus.L, knee); softKnee(bus.R, knee);
+  applyGlide(bus, wantedGain(peakAmp(bus), look, ceil));
+  hardClip(bus.L, ceil); hardClip(bus.R, ceil);
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/audio/soundtrack.ts

@@ -0,0 +1,119 @@
+// audio: the soundtrack, composed and mixed offline for each video.
+// A music bed in the style's genre, in tempo, warm and low (played instruments, not beeps), one stereo mix,
+// -16 LUFS. Pure JS synthesis (no samples), seeded so a rebuild sounds identical. ffmpeg measures loudness.
+// This file is the edge: ffmpeg reads and loudness, WAV writes, the mastering loop.
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { PRESETS, composeMusic } from "./compose.ts";
+import type { Preset } from "./compose.ts";
+import { SR, busGain, busMixFrom, clamp, dbToGain, makeBus, rng } from "./dsp.ts";
+import type { Bus, Rng } from "./dsp.ts";
+import { master } from "./master.ts";
+
+export { SR } from "./dsp.ts";
+export { PRESETS } from "./compose.ts";
+
+// `cues` (sound effects) is accepted for old callers and ignored.
+export type Plan = {
+  duration: number;
+  style?: string;
+  preset?: string;
+  bpm?: number;
+  boundaries?: readonly number[];
+  outroAt?: number;
+  cues?: readonly unknown[];
+  music?: string; // "auto" | "none" | a file path
+  musicVolume?: number;
+  musicStart?: number;
+};
+export type Report = {
+  music: string;
+  preset: string | undefined;
+  bpm: number;
+  sfx: number;
+  lufs: number | null;
+  truePeak: number | null;
+};
+type Loud = { readonly I: number; readonly TP: number };
+
+// ---------- ffmpeg and files ----------
+function writeWav(file: string, bus: Bus, seconds: number): void {
+  const n = Math.min(bus.n, Math.round(seconds * SR));
+  const b = Buffer.alloc(44 + n * 4);
+  b.write("RIFF", 0); b.writeUInt32LE(36 + n * 4, 4); b.write("WAVEfmt ", 8); b.writeUInt32LE(16, 16); b.writeUInt16LE(1, 20); b.writeUInt16LE(2, 22);
+  b.writeUInt32LE(SR, 24); b.writeUInt32LE(SR * 4, 28); b.writeUInt16LE(4, 32); b.writeUInt16LE(16, 34); b.write("data", 36); b.writeUInt32LE(n * 4, 40);
+  for (let i = 0; i < n; i++) { b.writeInt16LE(Math.round(clamp(bus.L[i], -1, 1) * 32767), 44 + i * 4); b.writeInt16LE(Math.round(clamp(bus.R[i], -1, 1) * 32767), 46 + i * 4); }
+  fs.writeFileSync(file, b);
+}
+function readAudio(file: string, seconds: number): Bus | null {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-t", String(seconds), "-f", "f32le", "-ac", "2", "-ar", String(SR), "-"], { maxBuffer: 1 << 30 });
+  if (r.status !== 0) return null;
+  const f = new Float32Array(r.stdout.buffer, r.stdout.byteOffset, Math.floor(r.stdout.length / 4));
+  const bus = makeBus(f.length / 2 / SR);
+  for (let i = 0; i < bus.n; i++) { bus.L[i] = f[i * 2]; bus.R[i] = f[i * 2 + 1]; }
+  return bus;
+}
+function loudness(file: string): Loud | null {
+  const r = spawnSync("ffmpeg", ["-hide_banner", "-i", file, "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], { encoding: "utf8" });
+  const m = /\{[\s\S]*\}/.exec(r.stderr || "");
+  if (!m) return null;
+  try {
+    const j: unknown = JSON.parse(m[0]);
+    if (typeof j !== "object" || j === null) return null;
+    return { I: "input_i" in j ? Number(j.input_i) : NaN, TP: "input_tp" in j ? Number(j.input_tp) : NaN };
+  } catch { return null; }
+}
+
+// ---------- the bed ----------
+const presetFor = (plan: Plan): Preset => {
+  const pick = (name: string | undefined): Preset | undefined => (name !== undefined && Object.hasOwn(PRESETS, name) ? PRESETS[name] : undefined);
+  const base = pick(plan.preset) ?? pick(plan.style) ?? PRESETS.keynote;
+  return plan.bpm ? { ...base, bpm: plan.bpm } : base;
+};
+// your own track, trimmed to the video, faded in and out under the volume
+function addOwnTrack(mix: Bus, plan: Plan, file: string): void {
+  const m = readAudio(file, plan.duration + (plan.musicStart || 0) + 3);
+  if (!m) return;
+  const off = Math.round((plan.musicStart || 0) * SR), fo = Math.round(Math.min(2, plan.duration * 0.1) * SR), end = Math.round(plan.duration * SR);
+  for (let i = 0; i < end && i + off < m.n; i++) {
+    const g = Math.min(1, i / (0.25 * SR)) * (i > end - fo ? (end - i) / fo : 1) * (plan.musicVolume ?? 0.8);
+    mix.L[i] += m.L[i + off] * g; mix.R[i] += m.R[i + off] * g;
+  }
+}
+function addMusic(mix: Bus, plan: Plan, P: Preset, r: Rng, ham: Rng): void {
+  if (plan.music === "auto" || plan.music == null) busMixFrom(mix, composeMusic(P, plan, r, ham), 0.9);
+  else if (plan.music && plan.music !== "none") addOwnTrack(mix, plan, plan.music);
+}
+
+// ---------- loudness loop ----------
+// -16 LUFS integrated (full, not loud) with peaks under -2 dBTP (headroom for the AAC encode). A few passes of
+// gain -> soft knee + limiter -> measure, so transient-heavy styles get there too.
+function trimPeaks(mix: Bus, outFile: string, seconds: number, L2: Loud | null): Loud | null {
+  if (!L2 || L2.TP <= -1.95) return L2;
+  busGain(mix, dbToGain(-2.05 - L2.TP));
+  writeWav(outFile, mix, seconds);
+  return loudness(outFile);
+}
+function loudnessPass(mix: Bus, outFile: string, seconds: number, L2: Loud | null, pass: number): Loud | null {
+  if (pass >= 4 || !L2 || !isFinite(L2.I)) return L2;
+  const g = clamp(-16 - L2.I, -20, 20);
+  if (Math.abs(g) < 0.25 && L2.TP <= -1.95) return L2;
+  busGain(mix, dbToGain(g));
+  master(mix, false);
+  writeWav(outFile, mix, seconds);
+  return loudnessPass(mix, outFile, seconds, trimPeaks(mix, outFile, seconds, loudness(outFile)), pass + 1);
+}
+
+export function renderSoundtrack(plan: Plan, outFile: string, { seed = 7 }: { seed?: number } = {}): Report {
+  const r = rng(seed), ham = rng(seed + 1), P = presetFor(plan);
+  const seconds = plan.duration + 0.05;
+  const mix = makeBus(plan.duration + 3);
+  addMusic(mix, plan, P, r, ham);
+  master(mix);
+  const tmp = outFile.replace(/\.wav$/, ".pre.wav");
+  writeWav(tmp, mix, seconds);
+  const L2 = loudnessPass(mix, outFile, seconds, loudness(tmp), 0);
+  if (!fs.existsSync(outFile)) writeWav(outFile, mix, seconds);
+  fs.rmSync(tmp, { force: true });
+  return { music: plan.music || "auto", preset: plan.preset || plan.style, bpm: P.bpm, sfx: 0, lufs: L2 ? L2.I : null, truePeak: L2 ? L2.TP : null };
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/domain/captions.ts

@@ -0,0 +1,35 @@
+import type { Line } from "./types.ts";
+
+// "*" and "|" are emphasis and pause marks for the writer; they are never spoken or shown.
+export const words = (s: string): readonly string[] => s.replace(/\*|\|/g, "").split(/\s+/).filter(Boolean);
+
+const STOP = /[,.;:!?…\u2014]$/;
+
+/** How many words the next chunk takes: an even share, nudged one word to land on punctuation. */
+function chunkSize(w: readonly string[], n: number, i: number, parts: number): number {
+  const left = w.length - i;
+  const even = Math.round(left / parts);
+  const nudge = [0, 1, -1].find((d) => {
+    const size = even + d;
+    return size >= 2 && left - size >= 2 && size <= n && STOP.test(w[i + size - 1] ?? "");
+  });
+  return even + (nudge ?? 0);
+}
+
+function split(w: readonly string[], n: number, i: number, parts: number): readonly string[] {
+  if (parts <= 1) return [w.slice(i).join(" ")];
+  const size = chunkSize(w, n, i, parts);
+  return [w.slice(i, i + size).join(" "), ...split(w, n, i + size, parts - 1)];
+}
+
+/** Balanced chunks of at most n words (7 words become 4 + 3, not 5 + 2). */
+export function chunks(text: string, n: number): readonly string[] {
+  const w = words(text);
+  return w.length <= n ? [w.join(" ")] : split(w, n, 0, Math.ceil(w.length / n));
+}
+
+/** A "/" in a line's caption forces a break there; in spoken text it is just a character ("and/or"). */
+export function captionChunks(line: Line, n: number): readonly string[] {
+  if (line.caption?.includes("/")) return line.caption.split("/").map((x) => x.trim()).filter(Boolean);
+  return chunks(line.caption ?? line.say, n);
+}