paper-motion 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +45 -2
  2. package/bin/pamo.mjs +535 -0
  3. package/examples/breath/brief.md +11 -0
  4. package/examples/breath/poster.jpg +0 -0
  5. package/examples/breath/scene.html +59 -0
  6. package/examples/chrome-endcard/brief.md +7 -0
  7. package/examples/chrome-endcard/fonts/GeistMono-Variable.woff2 +0 -0
  8. package/examples/chrome-endcard/fonts/GeistSerif-Regular.woff2 +0 -0
  9. package/examples/chrome-endcard/poster.jpg +0 -0
  10. package/examples/chrome-endcard/scene.html +68 -0
  11. package/examples/chrome-endcard/wordmark.js +16 -0
  12. package/examples/install-loop/brief.md +7 -0
  13. package/examples/install-loop/fonts/GeistMono-Variable.woff2 +0 -0
  14. package/examples/install-loop/fonts/GeistSerif-Regular.woff2 +0 -0
  15. package/examples/install-loop/poster.jpg +0 -0
  16. package/examples/install-loop/scene.html +46 -0
  17. package/examples/signal/brief.md +10 -0
  18. package/examples/signal/poster.jpg +0 -0
  19. package/examples/signal/scene.html +50 -0
  20. package/lib/board.mjs +95 -0
  21. package/lib/browser.mjs +88 -0
  22. package/lib/catalog.mjs +77 -0
  23. package/lib/keys.mjs +93 -0
  24. package/lib/modules.mjs +23 -0
  25. package/lib/react-hooks.mjs +9 -0
  26. package/lib/render.mjs +193 -0
  27. package/lib/server.mjs +88 -0
  28. package/lib/sfx.mjs +285 -0
  29. package/lib/shaderset.mjs +65 -0
  30. package/lib/wordmark.mjs +64 -0
  31. package/package.json +46 -4
  32. package/runtime/brand.js +71 -0
  33. package/runtime/index.js +606 -0
  34. package/runtime/jsx-shim.js +3 -0
  35. package/runtime/moves.js +174 -0
  36. package/runtime/player.js +69 -0
  37. package/runtime/react-shim.js +15 -0
  38. package/templates/blank/brief.md +39 -0
  39. package/templates/blank/scene.html +44 -0
  40. package/templates/brand-sheet/index.html +241 -0
  41. package/templates/move-demo/brief.md +4 -0
  42. package/templates/move-demo/scene.html +157 -0
  43. package/templates/piece/brief.md +39 -0
  44. package/templates/piece/scene.html +62 -0
  45. package/templates/shader-set/shot.js +47 -0
  46. package/templates/still/brief.md +3 -0
  47. package/templates/still/scene.html +56 -0
@@ -0,0 +1,23 @@
1
+ // Where an engine dependency lives on disk. Inside the repo it is packages/engine/node_modules; installed from npm,
2
+ // npm hoists it next to the engine (…/node_modules/<dep>, or npx's cache). Walk up like Node's resolver does.
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ export const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
8
+
9
+ const found = new Map();
10
+ /** Absolute folder of an installed package (e.g. '@paper-design/shaders'), or null. */
11
+ export function moduleDir(name) {
12
+ if (found.has(name)) return found.get(name);
13
+ let dir = ENGINE, hit = null;
14
+ for (;;) {
15
+ const d = path.join(dir, 'node_modules', name);
16
+ if (fs.existsSync(path.join(d, 'package.json'))) { hit = d; break; }
17
+ const up = path.dirname(dir);
18
+ if (up === dir) break;
19
+ dir = up;
20
+ }
21
+ found.set(name, hit);
22
+ return hit;
23
+ }
@@ -0,0 +1,9 @@
1
+ // Node module hook: resolve `react` to the paper-motion shim so the official
2
+ // shader components can be inspected in Node (used by `paper-motion shaders`).
3
+ const shim = new URL('../runtime/react-shim.js', import.meta.url).href;
4
+ const jsx = new URL('../runtime/jsx-shim.js', import.meta.url).href;
5
+ export async function resolve(specifier, context, next) {
6
+ if (specifier === 'react') return { url: shim, shortCircuit: true, format: 'module' };
7
+ if (specifier === 'react/jsx-runtime') return { url: jsx, shortCircuit: true, format: 'module' };
8
+ return next(specifier, context);
9
+ }
package/lib/render.mjs ADDED
@@ -0,0 +1,193 @@
1
+ import { spawn } from 'node:child_process';
2
+ import fs from 'node:fs';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
5
+ import { launch, openScene } from './browser.mjs';
6
+ import { synthesize, writeWav } from './sfx.mjs';
7
+
8
+ function ffmpeg(args, { stdin = false } = {}) {
9
+ const p = spawn(process.env.PAPER_MOTION_FFMPEG || 'ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', ...args], { stdio: [stdin ? 'pipe' : 'ignore', 'inherit', 'pipe'] });
10
+ let err = '';
11
+ p.stderr.on('data', (d) => { err += d; });
12
+ if (stdin) p.stdin.on('error', () => {}); // surfaced through p.done instead
13
+ p.done = new Promise((res, rej) => {
14
+ p.on('error', (e) => rej(e.code === 'ENOENT' ? new Error('ffmpeg not found. Install it (macOS: brew install ffmpeg · Ubuntu: apt install ffmpeg · Windows: winget install ffmpeg)') : e));
15
+ p.on('close', (code) => (code === 0 ? res() : rej(new Error(`ffmpeg failed (${code}): ${err.trim()}`))));
16
+ });
17
+ return p;
18
+ }
19
+
20
+ const write = (proc, buf) => {
21
+ if (proc.stdin.write(buf)) return Promise.resolve();
22
+ return Promise.race([
23
+ new Promise((res) => proc.stdin.once('drain', res)),
24
+ proc.done.then(() => { throw new Error('ffmpeg exited early'); }),
25
+ ]);
26
+ };
27
+
28
+ /** Render stills at given times; returns file paths. Optionally a contact sheet. */
29
+ export async function renderStills({ url, times, count, outDir, dpr = 1, sheet = true, motionBlur = 1, shutter = 180 }) {
30
+ fs.mkdirSync(outDir, { recursive: true });
31
+ const browser = await launch();
32
+ try {
33
+ const s = await openScene(browser, url, { dpr });
34
+ const { duration, fps } = s.config;
35
+ if (!times?.length) {
36
+ const n = count ?? 6;
37
+ times = Array.from({ length: n }, (_, i) => (n === 1 ? 0 : (i * duration) / n));
38
+ }
39
+ const files = [];
40
+ for (const t of times) {
41
+ const tt = Math.round(Math.min(t, duration - 1 / fps) * fps) / fps;
42
+ const f = path.join(outDir, `t${tt.toFixed(2).padStart(6, '0')}.png`);
43
+ const k = Math.max(1, Math.round(motionBlur));
44
+ if (k === 1) { await s.seek(tt); fs.writeFileSync(f, await s.capture()); }
45
+ else {
46
+ const p = ffmpeg(['-f', 'image2pipe', '-framerate', String(k), '-c:v', 'png', '-i', '-', '-vf', `tmix=frames=${k},select='eq(n\\,${k - 1})'`, '-frames:v', '1', f], { stdin: true });
47
+ for (const st of subframes(Math.round(tt * fps), fps, k, shutter, duration)) { await s.seek(st); await write(p, await s.capture()); }
48
+ p.stdin.end(); await p.done;
49
+ }
50
+ files.push(f);
51
+ }
52
+ let sheetPath = null;
53
+ if (sheet && files.length > 1) {
54
+ sheetPath = path.join(outDir, 'contact-sheet.jpg');
55
+ const cols = files.length <= 4 ? files.length : Math.ceil(Math.sqrt(files.length));
56
+ const gap = 8;
57
+ const w = Math.min(640, s.config.width);
58
+ const h = Math.round((w * s.config.height) / s.config.width / 2) * 2;
59
+ const inputs = files.flatMap((f) => ['-i', f]);
60
+ const scaled = files.map((_, i) => `[${i}:v]scale=${w}:${h}:flags=lanczos[v${i}]`).join(';');
61
+ const stack = files.map((_, i) => `[v${i}]`).join('');
62
+ const layout = files.map((_, i) => `${(i % cols) * (w + gap)}_${Math.floor(i / cols) * (h + gap)}`).join('|');
63
+ const filter = `${scaled};${stack}xstack=inputs=${files.length}:layout=${layout}:fill=0x111111[out]`;
64
+ const p = ffmpeg([...inputs, '-filter_complex', filter, '-map', '[out]', '-q:v', '3', sheetPath]);
65
+ await p.done;
66
+ }
67
+ await s.close();
68
+ return { files, sheet: sheetPath, config: s.config, times };
69
+ } finally {
70
+ await browser.close();
71
+ }
72
+ }
73
+
74
+ const FORMATS = {
75
+ mp4: { ext: 'mp4', args: (o) => ['-c:v', 'libx264', '-preset', 'slow', '-crf', String(o.crf ?? 16), '-x264-params', 'aq-mode=3', '-pix_fmt', 'yuv420p', ...bt709, '-movflags', '+faststart'], vf: yuv },
76
+ hevc: { ext: 'mp4', args: (o) => ['-c:v', 'libx265', '-preset', 'slow', '-crf', String(o.crf ?? 18), '-pix_fmt', 'yuv420p10le', '-tag:v', 'hvc1', ...bt709, '-movflags', '+faststart'], vf: yuv },
77
+ prores: { ext: 'mov', args: () => ['-c:v', 'prores_ks', '-profile:v', '3', '-pix_fmt', 'yuv422p10le', '-vendor', 'apl0', ...bt709], vf: yuv },
78
+ webm: { ext: 'webm', args: (o) => ['-c:v', 'libvpx-vp9', '-crf', String(o.crf ?? 20), '-b:v', '0', '-row-mt', '1', '-pix_fmt', 'yuv420p', ...bt709], vf: yuv },
79
+ gif: { ext: 'gif', args: () => [], gif: true },
80
+ png: { ext: 'png', args: () => [], seq: true },
81
+ };
82
+ const bt709 = ['-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709'];
83
+ function yuv() { return 'scale=out_color_matrix=bt709:out_range=tv'; }
84
+
85
+ /** Render a scene to video. */
86
+ /** Synthesize the scene's sfx cues to a WAV file. Returns the path, or null when there are none. */
87
+ export async function renderSfx({ url, out, from = 0, to }) {
88
+ const browser = await launch();
89
+ try {
90
+ const s = await openScene(browser, url);
91
+ const r = await sfxFromPage(s, { from, to, out });
92
+ await s.close();
93
+ return r;
94
+ } finally { await browser.close(); }
95
+ }
96
+
97
+ async function sfxFromPage(s, { from = 0, to, out }) {
98
+ const { cues, audio } = await s.page.evaluate(() => ({ cues: window.__pm.cues ?? [], audio: window.__pm.audio ?? {} }));
99
+ if (!cues.length) return null;
100
+ const end = to ?? s.config.duration;
101
+ const shifted = cues.filter((c) => c.t < end).map((c) => ({ ...c, t: c.t - from }));
102
+ writeWav(out, synthesize(shifted, { duration: end - from, ...audio }));
103
+ return { out, cues: cues.length };
104
+ }
105
+
106
+ /** Subframe times for frame f: k samples spread over the shutter, centered on the frame (After Effects-style). */
107
+ function subframes(f, fps, k, shutter, duration) {
108
+ if (k <= 1) return [f / fps];
109
+ const open = shutter / 360;
110
+ return Array.from({ length: k }, (_, j) => Math.min(duration - 1e-4, Math.max(0, (f + ((j + 0.5) / k - 0.5) * open) / fps)));
111
+ }
112
+
113
+ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1, from, to, fps: fpsOverride, crf, audio, sfx = true, motionBlur = 1, shutter = 180, gifWidth = 720, gifFps = 24, onProgress }) {
114
+ const fmt = FORMATS[format];
115
+ if (!fmt) throw new Error(`Unknown format "${format}". Use one of: ${Object.keys(FORMATS).join(', ')}`);
116
+ const browser = await launch();
117
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'paper-motion-'));
118
+ const t0 = Date.now();
119
+ try {
120
+ const first = await openScene(browser, url, { dpr });
121
+ const cfg = first.config;
122
+ const fps = fpsOverride ?? cfg.fps;
123
+ const f0 = Math.round((from ?? 0) * fps);
124
+ const f1 = Math.round((to ?? cfg.duration) * fps);
125
+ const total = f1 - f0;
126
+ if (total <= 0) throw new Error('Nothing to render (check --from/--to).');
127
+ const n = Math.max(1, Math.min(workers ?? Math.min(4, Math.max(1, Math.floor(os.cpus().length / 2))), Math.ceil(total / 15)));
128
+ const chunk = Math.ceil(total / n);
129
+ let done = 0;
130
+ const tick = () => onProgress?.({ done, total, elapsed: (Date.now() - t0) / 1000 });
131
+
132
+ let sfxWav = null;
133
+ if (sfx && !fmt.gif && !fmt.seq) {
134
+ const r = await sfxFromPage(first, { from: f0 / fps, to: f1 / fps, out: path.join(tmp, 'sfx.wav') });
135
+ sfxWav = r?.out ?? null;
136
+ }
137
+
138
+ const sessions = [first];
139
+ for (let i = 1; i < n; i++) sessions.push(await openScene(browser, url, { dpr }));
140
+
141
+ const segments = await Promise.all(sessions.map(async (s, i) => {
142
+ const a = f0 + i * chunk, b = Math.min(f1, a + chunk);
143
+ if (a >= b) return null;
144
+ const seg = path.join(tmp, `seg${String(i).padStart(3, '0')}.mkv`);
145
+ // Lossless RGB intermediate; the final encode happens once, after concat.
146
+ const k = Math.max(1, Math.round(motionBlur));
147
+ // Motion blur: k subframes per frame are averaged (tmix) and one frame is kept per group.
148
+ const blur = k > 1 ? ['-vf', `tmix=frames=${k},select='eq(mod(n\\,${k})\\,${k - 1})',setpts=N/(${fps}*TB)`, '-r', String(fps)] : [];
149
+ const p = ffmpeg(['-f', 'image2pipe', '-framerate', String(fps * k), '-c:v', 'png', '-i', '-', ...blur, '-c:v', 'libx264rgb', '-preset', 'ultrafast', '-crf', '0', seg], { stdin: true });
150
+ for (let f = a; f < b; f++) {
151
+ for (const tt of subframes(f, fps, k, shutter, cfg.duration)) {
152
+ await s.seek(tt);
153
+ await write(p, await s.capture());
154
+ }
155
+ done++; tick();
156
+ }
157
+ p.stdin.end();
158
+ await p.done;
159
+ await s.close();
160
+ return seg;
161
+ }));
162
+
163
+ const list = path.join(tmp, 'list.txt');
164
+ fs.writeFileSync(list, segments.filter(Boolean).map((s) => `file '${s.replace(/'/g, "'\\''")}'`).join('\n'));
165
+ const W = cfg.width, H = cfg.height;
166
+ const scale = dpr !== 1 ? `scale=${W}:${H}:flags=lanczos` : null;
167
+ out = out ?? `render.${fmt.ext}`;
168
+ fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
169
+ const input = ['-f', 'concat', '-safe', '0', '-i', list];
170
+
171
+ if (fmt.seq) {
172
+ const dir = out.replace(/\.png$/, '');
173
+ fs.mkdirSync(dir, { recursive: true });
174
+ await ffmpeg([...input, ...(scale ? ['-vf', scale] : []), path.join(dir, 'frame_%05d.png')]).done;
175
+ out = dir;
176
+ } else if (fmt.gif) {
177
+ const vf = `fps=${gifFps},scale=${gifWidth}:-2:flags=lanczos,split[a][b];[a]palettegen=max_colors=256:stats_mode=diff[p];[b][p]paletteuse=dither=sierra2_4a`;
178
+ await ffmpeg([...input, '-vf', vf, '-loop', '0', out]).done;
179
+ } else {
180
+ const vf = [scale, fmt.vf?.()].filter(Boolean).join(',');
181
+ const codec = ['-c:a', format === 'webm' ? 'libopus' : 'aac', '-b:a', '320k'];
182
+ const audios = [audio, sfxWav].filter(Boolean);
183
+ const audioArgs = audios.length === 0 ? []
184
+ : audios.length === 1 ? ['-i', audios[0], '-map', '0:v', '-map', '1:a', ...codec, '-shortest']
185
+ : ['-i', audios[0], '-i', audios[1], '-filter_complex', '[1:a][2:a]amix=inputs=2:normalize=0[a]', '-map', '0:v', '-map', '[a]', ...codec, '-shortest'];
186
+ await ffmpeg([...input, ...audioArgs, ...(vf ? ['-vf', vf] : []), '-r', String(fps), ...fmt.args({ crf }), out]).done;
187
+ }
188
+ return { out, frames: total, fps, seconds: (Date.now() - t0) / 1000, workers: n, config: cfg };
189
+ } finally {
190
+ await browser.close();
191
+ fs.rmSync(tmp, { recursive: true, force: true });
192
+ }
193
+ }
package/lib/server.mjs ADDED
@@ -0,0 +1,88 @@
1
+ // Static server for scenes. Injects an import map so scenes can
2
+ // `import { scene } from 'paper-motion'` with no bundler, and live-reloads
3
+ // previews when files change.
4
+ import http from 'node:http';
5
+ import fs from 'node:fs';
6
+ import path from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+ import { moduleDir } from './modules.mjs';
9
+
10
+ const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
11
+
12
+ const MIME = {
13
+ '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
14
+ '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
15
+ '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.avif': 'image/avif',
16
+ '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
17
+ '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.map': 'application/json',
18
+ };
19
+
20
+ const IMPORT_MAP = {
21
+ imports: {
22
+ 'paper-motion': '/__pm/runtime/index.js',
23
+ 'paper-motion/moves': '/__pm/runtime/moves.js',
24
+ 'paper-motion/brand': '/__pm/runtime/brand.js',
25
+ '@paper-design/shaders': '/__pm/node_modules/@paper-design/shaders/dist/index.js',
26
+ '@paper-design/shaders-react': '/__pm/node_modules/@paper-design/shaders-react/dist/index.js',
27
+ react: '/__pm/runtime/react-shim.js',
28
+ 'react/jsx-runtime': '/__pm/runtime/jsx-shim.js',
29
+ },
30
+ };
31
+
32
+ const RELOAD_CLIENT = `<script>(()=>{if(location.search.includes('render'))return;
33
+ const es=new EventSource('/__pm/events');es.onmessage=()=>location.reload();})();</script>`;
34
+
35
+ export function startServer({ root, port = 0, watch = false }) {
36
+ const clients = new Set();
37
+ const server = http.createServer((req, res) => {
38
+ const url = new URL(req.url, 'http://x');
39
+ let p = decodeURIComponent(url.pathname);
40
+ if (p === '/__pm/events') {
41
+ res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
42
+ res.write(': ok\n\n');
43
+ clients.add(res);
44
+ req.on('close', () => clients.delete(res));
45
+ return;
46
+ }
47
+ if (p === '/favicon.ico') { res.writeHead(204).end(); return; }
48
+ let file;
49
+ if (p.startsWith('/__pm/runtime/')) file = path.join(ENGINE, 'runtime', p.slice('/__pm/runtime/'.length));
50
+ let base = p.startsWith('/__pm/') ? ENGINE : root;
51
+ if (p.startsWith('/__pm/node_modules/')) {
52
+ // '/__pm/node_modules/@scope/pkg/dist/x.js' → wherever npm put @scope/pkg
53
+ const rest = p.slice('/__pm/node_modules/'.length).split('/'), n = rest[0].startsWith('@') ? 2 : 1;
54
+ base = moduleDir(rest.slice(0, n).join('/')) ?? path.join(ENGINE, 'node_modules', ...rest.slice(0, n));
55
+ file = path.join(base, ...rest.slice(n));
56
+ } else if (!file) file = path.join(root, p);
57
+ if (!path.resolve(file).startsWith(path.resolve(base))) { res.writeHead(403).end(); return; }
58
+ fs.stat(file, (err, st) => {
59
+ if (!err && st.isDirectory()) { file = path.join(file, 'index.html'); }
60
+ fs.readFile(file, (e, buf) => {
61
+ if (e) { res.writeHead(404, { 'content-type': 'text/plain' }).end(`not found: ${p}`); return; }
62
+ const ext = path.extname(file).toLowerCase();
63
+ const headers = { 'content-type': MIME[ext] ?? 'application/octet-stream', 'cache-control': 'no-store', 'access-control-allow-origin': '*' };
64
+ if (ext === '.html') {
65
+ let html = buf.toString('utf8');
66
+ const inject = `<script type="importmap">${JSON.stringify(IMPORT_MAP)}</script>${watch ? RELOAD_CLIENT : ''}`;
67
+ html = /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + inject) : inject + html;
68
+ res.writeHead(200, headers).end(html);
69
+ } else res.writeHead(200, headers).end(buf);
70
+ });
71
+ });
72
+ });
73
+
74
+ if (watch) {
75
+ let timer;
76
+ try {
77
+ fs.watch(root, { recursive: true }, (_e, f) => {
78
+ if (!f || /(^|[\\/])(node_modules|renders|stills|\.git)([\\/]|$)/.test(f) || /\.(mp4|mov|webm|gif)$/.test(f)) return;
79
+ clearTimeout(timer);
80
+ timer = setTimeout(() => { for (const c of clients) c.write('data: reload\n\n'); }, 120);
81
+ });
82
+ } catch { /* recursive watch unsupported: no live reload */ }
83
+ }
84
+
85
+ return new Promise((resolve) => {
86
+ server.listen(port, '127.0.0.1', () => resolve({ server, port: server.address().port, close: () => new Promise((r) => { for (const c of clients) c.end(); server.close(r); }) }));
87
+ });
88
+ }
package/lib/sfx.mjs ADDED
@@ -0,0 +1,285 @@
1
+ // Deterministic sound-effects synthesizer. Scenes declare cues with
2
+ // s.sfx(t, type, opts); the renderer synthesizes them into a WAV and muxes it.
3
+ // Everything is generated from code (no samples) and seeded, so the same scene
4
+ // always produces the same audio.
5
+ import fs from 'node:fs';
6
+ import { loadBank } from './keys.mjs';
7
+
8
+ const SR = 48000;
9
+
10
+ function mulberry32(seed) {
11
+ let a = seed >>> 0;
12
+ return () => {
13
+ a |= 0; a = (a + 0x6d2b79f5) | 0;
14
+ let t = Math.imul(a ^ (a >>> 15), 1 | a);
15
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
16
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
17
+ };
18
+ }
19
+
20
+ // RBJ biquad
21
+ class Biquad {
22
+ constructor(type, freq, q = 0.707, gainDb = 0) {
23
+ const w = (2 * Math.PI * Math.min(freq, SR * 0.45)) / SR, cos = Math.cos(w), alpha = Math.sin(w) / (2 * q);
24
+ const A = 10 ** (gainDb / 40);
25
+ let b0, b1, b2, a0, a1, a2;
26
+ a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
27
+ if (type === 'lowpass') { b0 = (1 - cos) / 2; b1 = 1 - cos; b2 = b0; }
28
+ else if (type === 'highpass') { b0 = (1 + cos) / 2; b1 = -(1 + cos); b2 = b0; }
29
+ else if (type === 'peak') { b0 = 1 + alpha * A; b1 = -2 * cos; b2 = 1 - alpha * A; a0 = 1 + alpha / A; a2 = 1 - alpha / A; }
30
+ else if (type === 'highshelf') {
31
+ const sq = 2 * Math.sqrt(A) * alpha;
32
+ b0 = A * ((A + 1) + (A - 1) * cos + sq); b1 = -2 * A * ((A - 1) + (A + 1) * cos); b2 = A * ((A + 1) + (A - 1) * cos - sq);
33
+ a0 = (A + 1) - (A - 1) * cos + sq; a1 = 2 * ((A - 1) - (A + 1) * cos); a2 = (A + 1) - (A - 1) * cos - sq;
34
+ }
35
+ else { b0 = alpha; b1 = 0; b2 = -alpha; } // bandpass, 0 dB peak
36
+ this.b = [b0 / a0, b1 / a0, b2 / a0]; this.a = [a1 / a0, a2 / a0];
37
+ this.x1 = this.x2 = this.y1 = this.y2 = 0;
38
+ }
39
+ process(x) {
40
+ const y = this.b[0] * x + this.b[1] * this.x1 + this.b[2] * this.x2 - this.a[0] * this.y1 - this.a[1] * this.y2;
41
+ this.x2 = this.x1; this.x1 = x; this.y2 = this.y1; this.y1 = y;
42
+ return y;
43
+ }
44
+ }
45
+
46
+ const TAU = Math.PI * 2;
47
+ const smooth = (x) => (x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x));
48
+
49
+ /**
50
+ * Voices. Each returns { len (s), fn(i, sr) -> sample } — mono; panning is applied by the mixer.
51
+ * All of them are dark by design; the master low-pass (default 2 kHz) guarantees no harsh highs.
52
+ */
53
+ const VOICES = {
54
+ // Continuous low bed. { dur, freq=55, gain=0.05, attack=3, release=4 }
55
+ drone({ dur = 10, freq = 55, gain = 0.05, attack = 3, release = 4 }, rnd) {
56
+ const lp = new Biquad('lowpass', 260), ph = [rnd(), rnd(), rnd(), rnd()].map((p) => p * TAU);
57
+ return { len: dur, fn: (i) => {
58
+ const t = i / SR;
59
+ const env = smooth(t / attack) * smooth((dur - t) / release);
60
+ const am = 1 + 0.18 * Math.sin(TAU * 0.07 * t + ph[0]);
61
+ const tone = Math.sin(TAU * freq * t + ph[1]) + 0.5 * Math.sin(TAU * freq * 1.5 * t + ph[2]) + 0.3 * Math.sin(TAU * freq * 2 * t + ph[3]);
62
+ const air = lp.process(rnd() * 2 - 1) * 0.9;
63
+ return gain * env * (tone * 0.6 * am + air);
64
+ } };
65
+ },
66
+ // Slow chord pad: root, fifth, octave. { dur=4, freq=73.4, gain=0.1 }
67
+ swell({ dur = 4, freq = 73.4, gain = 0.1 }) {
68
+ const parts = [[1, 1], [1.5, 0.55], [2, 0.4], [1.003, 0.6], [1.497, 0.3]];
69
+ return { len: dur, fn: (i) => {
70
+ const t = i / SR, p = t / dur;
71
+ const env = p < 0.45 ? Math.sin((p / 0.45) * Math.PI / 2) ** 2 : Math.cos(((p - 0.45) / 0.55) * Math.PI / 2) ** 2;
72
+ let s = 0; for (const [r, a] of parts) s += a * Math.sin(TAU * freq * r * t);
73
+ return gain * env * s * 0.35;
74
+ } };
75
+ },
76
+ // Pen / pencil writing on paper: band-limited noise with stroke rhythm. { dur=1, gain=0.12, rate=7 }
77
+ pen({ dur = 1, gain = 0.12, rate = 7, tone = 520 }, rnd) {
78
+ const bp = new Biquad('bandpass', tone, 0.7), lp = new Biquad('lowpass', 1100);
79
+ const r = rate * (0.85 + 0.3 * rnd()), ph = rnd() * TAU;
80
+ return { len: dur, fn: (i) => {
81
+ const t = i / SR;
82
+ const env = smooth(t / 0.025) * smooth((dur - t) / 0.05);
83
+ const stroke = 0.35 + 0.65 * Math.abs(Math.sin(TAU * r * t + ph + 0.6 * Math.sin(TAU * 1.3 * t))) ** 1.6;
84
+ return gain * env * stroke * lp.process(bp.process(rnd() * 2 - 1)) * 2.2;
85
+ } };
86
+ },
87
+ // Paper movement / whoosh. { dur=0.8, gain=0.14 }
88
+ paper({ dur = 0.8, gain = 0.14 }, rnd) {
89
+ const lp = new Biquad('lowpass', 650), hp = new Biquad('highpass', 90), lp2 = new Biquad('lowpass', 900);
90
+ return { len: dur, fn: (i) => {
91
+ const t = i / SR, p = t / dur;
92
+ const env = Math.sin(Math.PI * Math.min(1, p)) ** 2;
93
+ const crackle = rnd() < 0.002 ? (rnd() * 2 - 1) * 3 : 0;
94
+ return gain * (env * hp.process(lp.process(rnd() * 2 - 1)) * 1.8 + env * lp2.process(crackle) * 0.6);
95
+ } };
96
+ },
97
+ // Soft low stamp / body hit. { freq=62, gain=0.5, decay=0.45 }
98
+ thud({ freq = 62, gain = 0.5, decay = 0.45 }, rnd) {
99
+ const lp = new Biquad('lowpass', 320);
100
+ let phase = 0;
101
+ return { len: decay * 5, fn: (i) => {
102
+ const t = i / SR;
103
+ const f = freq * (1 + 0.8 * Math.exp(-t / 0.035));
104
+ phase += (TAU * f) / SR;
105
+ const env = smooth(t / 0.004) * Math.exp(-t / decay);
106
+ const click = lp.process((rnd() * 2 - 1) * Math.exp(-t / 0.012));
107
+ return gain * (env * Math.sin(phase) + click * 0.5);
108
+ } };
109
+ },
110
+ // Wooden knock, low. { freq=140, gain=0.3, decay=0.16 }
111
+ knock({ freq = 140, gain = 0.3, decay = 0.16 }, rnd) {
112
+ const lp = new Biquad('lowpass', 520);
113
+ return { len: decay * 6, fn: (i) => {
114
+ const t = i / SR;
115
+ const a = smooth(t / 0.002);
116
+ const body = Math.sin(TAU * freq * t) * Math.exp(-t / decay) + 0.35 * Math.sin(TAU * freq * 2.31 * t) * Math.exp(-t / (decay * 0.4));
117
+ const n = lp.process((rnd() * 2 - 1) * Math.exp(-t / 0.008));
118
+ return gain * a * (body + n * 0.6);
119
+ } };
120
+ },
121
+ // Tiny low tick (UI-ish but dull). { freq=200, gain=0.1, decay=0.05 }
122
+ tick({ freq = 200, gain = 0.1, decay = 0.05 }) {
123
+ return { len: decay * 6, fn: (i) => { const t = i / SR; return gain * smooth(t / 0.0015) * Math.exp(-t / decay) * Math.sin(TAU * freq * t); } };
124
+ },
125
+ // A keystroke, modeled like a real one: the bottom-out impact excites a few inharmonic keycap/plate
126
+ // resonances plus a low case "thock"; a softer, higher upstroke follows; a hint of room around it.
127
+ // { gain=0.3, kind='letter'|'space'|'enter', vel=1, style='creamy'|'thock'|'clack' }. Seeded variation.
128
+ key({ gain = 0.3, kind = 'letter', vel = 1, style = 'creamy', bank }, rnd) {
129
+ if (bank) {
130
+ // Real keystrokes: pick a hit from the bank, vary level and pitch slightly so no two repeat exactly.
131
+ const pool = (kind === 'space' || kind === 'enter') ? bank.heavy : bank.letter;
132
+ const src = pool[Math.floor(rnd() * pool.length) % pool.length];
133
+ const rate = 0.98 + 0.04 * rnd(), g = gain * vel * (0.82 + 0.3 * rnd()) * (kind === 'enter' ? 1.15 : 1);
134
+ const len = src.length / rate / SR;
135
+ return { len, bright: true, fn: (i) => {
136
+ const p = i * rate, j = Math.floor(p), x = p - j;
137
+ const y0 = src[j - 1] ?? 0, y1 = src[j] ?? 0, y2 = src[j + 1] ?? 0, y3 = src[j + 2] ?? 0;
138
+ const soft = Math.min(1, i / (0.0035 * SR)); // a 3.5 ms rise rounds off the hardest edge of the click
139
+ return g * soft * (y1 + 0.5 * x * (y2 - y0 + x * (2 * y0 - 5 * y1 + 4 * y2 - y3 + x * (3 * (y1 - y2) + y3 - y0))));
140
+ } };
141
+ }
142
+ const S = {
143
+ thock: { modes: [[620, 0.016, 1], [1040, 0.011, 0.7], [1580, 0.008, 0.45], [2350, 0.006, 0.25]], body: [170, 0.026, 1.1], burst: 0.0009, up: 0.32 },
144
+ creamy: { modes: [[780, 0.013, 1], [1290, 0.010, 0.75], [1960, 0.007, 0.5], [2900, 0.005, 0.3]], body: [210, 0.020, 0.8], burst: 0.0007, up: 0.4 },
145
+ clack: { modes: [[1150, 0.010, 0.8], [1850, 0.008, 1], [2750, 0.006, 0.7], [3900, 0.004, 0.4]], body: [260, 0.014, 0.5], burst: 0.0005, up: 0.5 },
146
+ }[style] ?? null;
147
+ if (!S) throw new Error(`key style "${style}": use creamy, thock or clack`);
148
+ const heavy = kind === 'space' || kind === 'enter';
149
+ const pitch = (heavy ? (kind === 'space' ? 0.72 : 0.84) : 1) * (0.93 + 0.14 * rnd());
150
+ const len = 0.26, N = Math.ceil(len * SR), buf = new Float32Array(N);
151
+ // one strike: noise burst + click into a bank of ringing band-passes (Q from the decay time)
152
+ const strike = (at, amp, fMul) => {
153
+ const bank = S.modes.map(([f, tau, g]) => {
154
+ const fr = f * pitch * fMul * (0.96 + 0.08 * rnd());
155
+ return { bq: new Biquad('bandpass', fr, Math.max(2, Math.PI * fr * tau * (heavy ? 1.3 : 1))), g: g * (0.8 + 0.4 * rnd()) };
156
+ });
157
+ const [bf, btau, bg] = S.body;
158
+ const body = new Biquad('bandpass', bf * pitch * (0.95 + 0.1 * rnd()), Math.PI * bf * btau * (heavy ? 1.5 : 1));
159
+ const hp = new Biquad('highpass', 400);
160
+ const i0 = Math.round(at * SR), burst = S.burst * (heavy ? 1.6 : 1);
161
+ for (let i = i0; i < N; i++) {
162
+ const t = (i - i0) / SR;
163
+ const ex = t < burst * 6 ? (rnd() * 2 - 1) * Math.exp(-t / burst) + (i === i0 ? 3 : 0) : 0;
164
+ let y = 0;
165
+ for (const m of bank) y += m.bq.process(ex) * m.g;
166
+ y += body.process(ex) * bg * 1.6;
167
+ y += hp.process(ex) * 0.12; // the contact "tick" itself
168
+ buf[i] += amp * y;
169
+ }
170
+ };
171
+ const pre = 0.004 + 0.008 * rnd(); // finger meets the cap
172
+ strike(0, 0.08, 1.35);
173
+ strike(pre, 1, 1); // bottom-out
174
+ if (kind === 'space') strike(pre + 0.007 + 0.005 * rnd(), 0.35, 1.25); // stabilizer rattle
175
+ strike(pre + (heavy ? 0.11 : 0.075) + 0.035 * rnd(), S.up * (0.8 + 0.4 * rnd()), 1.18); // upstroke
176
+ // a little room: two early reflections
177
+ for (const [d, k] of [[0.0071, 0.16], [0.0133, 0.09]]) { const o = Math.round(d * SR); for (let i = N - 1; i >= o; i--) buf[i] += buf[i - o] * k; }
178
+ let peak = 1e-9; for (let i = 0; i < N; i++) peak = Math.max(peak, Math.abs(buf[i]));
179
+ const g = (gain * vel * (0.8 + 0.3 * rnd()) * (heavy ? 1.2 : 1)) / peak;
180
+ return { len, bright: true, fn: (i) => buf[i] * g };
181
+ },
182
+ // Air moving past: a pass-by whoosh. The band sweeps from→to→back while the level peaks at `peak`.
183
+ // { dur=0.7, gain=0.2, from=320, to=1200, peak=0.6, body=0 (low weight under it, 0..1) }
184
+ whoosh({ dur = 0.7, gain = 0.2, from = 320, to = 1200, peak = 0.6, body = 0 }, rnd) {
185
+ // state-variable filters so the centre frequency can move every sample
186
+ const svf = () => { let low = 0, band = 0; return (x, fc, q) => { const f = 2 * Math.sin(Math.PI * Math.min(fc, SR / 6) / SR); low += f * band; const high = x - low - q * band; band += f * high; return band; }; };
187
+ const A = svf(), B = svf();
188
+ let pink = 0, flut = 0;
189
+ const ph = rnd() * TAU, bf = 52 + 14 * rnd();
190
+ return { len: dur, fn: (i) => {
191
+ const t = i / SR, p = t / dur;
192
+ const env = p < peak ? smooth(p / peak) ** 1.6 : Math.cos(((p - peak) / (1 - peak)) * Math.PI / 2) ** 2;
193
+ const fc = p < peak ? from * (to / from) ** smooth(p / peak) : to * ((from * 0.8) / to) ** ((p - peak) / (1 - peak));
194
+ const w = rnd() * 2 - 1;
195
+ pink = 0.8 * pink + 0.2 * w; // gentle tilt, still airy
196
+ flut = 0.9995 * flut + 0.0005 * (rnd() * 2 - 1);
197
+ const n = pink * 1.6;
198
+ const air = A(n, fc, 0.9) + 0.5 * B(n, fc * 1.6, 1.1);
199
+ const low = body * Math.sin(TAU * bf * t + ph) * env * 0.5;
200
+ return gain * env * (air * (1 + flut * 60) * 1.4 + low);
201
+ } };
202
+ },
203
+ // A small card/paper flick (something light landing). { gain=0.12 }
204
+ flick({ gain = 0.12 }, rnd) {
205
+ const bp = new Biquad('bandpass', 700 + 500 * rnd(), 0.9), lp = new Biquad('lowpass', 1600);
206
+ const f = 160 + 80 * rnd();
207
+ return { len: 0.12, fn: (i) => {
208
+ const t = i / SR;
209
+ const n = lp.process(bp.process(rnd() * 2 - 1)) * Math.exp(-t / 0.012) * 2.4;
210
+ const k = Math.sin(TAU * f * t) * Math.exp(-t / 0.02) * smooth(t / 0.001) * 0.5;
211
+ return gain * (0.75 + 0.5 * rnd()) * (n + k);
212
+ } };
213
+ },
214
+ // Pitch glide. { dur=0.6, from=160, to=80, gain=0.08 }
215
+ sweep({ dur = 0.6, from = 160, to = 80, gain = 0.08 }) {
216
+ let phase = 0;
217
+ return { len: dur, fn: (i) => {
218
+ const t = i / SR, p = t / dur;
219
+ phase += (TAU * (from + (to - from) * p)) / SR;
220
+ return gain * Math.sin(Math.PI * p) ** 2 * Math.sin(phase);
221
+ } };
222
+ },
223
+ };
224
+
225
+ export const SFX_TYPES = Object.keys(VOICES);
226
+
227
+ /**
228
+ * @param cues [{ t, type, pan?, seed?, ...voiceOpts }]
229
+ * @param options { duration, lowpass=2000, highpass=30, gain=1, peak=0.8 }
230
+ * @returns { left: Float32Array, right: Float32Array, sampleRate }
231
+ */
232
+ export function synthesize(cues, { duration, lowpass = 2000, highpass = 30, gain = 1, peak = 0.8 } = {}) {
233
+ const n = Math.ceil(duration * SR);
234
+ const L = new Float32Array(n), R = new Float32Array(n);
235
+ // Voices marked `bright` (keys) go through their own, gentler low-pass: a keystroke's click lives at 1–4 kHz.
236
+ const BL = new Float32Array(n), BR = new Float32Array(n);
237
+ cues.forEach((c, k) => {
238
+ const voice = VOICES[c.type];
239
+ if (!voice) throw new Error(`Unknown sfx type "${c.type}". Use: ${SFX_TYPES.join(', ')}`);
240
+ const rnd = mulberry32((c.seed ?? k * 7919 + 13) >>> 0);
241
+ const v = voice(typeof c.bank === 'string' ? { ...c, bank: loadBank(c.bank) } : c, rnd);
242
+ const start = Math.round(c.t * SR), len = Math.ceil(v.len * SR);
243
+ const pan = Math.max(-1, Math.min(1, c.pan ?? 0)), gl = Math.cos(((pan + 1) * Math.PI) / 4), gr = Math.sin(((pan + 1) * Math.PI) / 4);
244
+ for (let i = 0; i < len; i++) {
245
+ const j = start + i;
246
+ if (j < 0) continue; if (j >= n) break;
247
+ const s = v.fn(i);
248
+ if (v.bright) { BL[j] += s * gl; BR[j] += s * gr; } else { L[j] += s * gl; R[j] += s * gr; }
249
+ }
250
+ });
251
+ // Master: 24 dB/oct low-pass (no harsh highs), high-pass rumble, normalize, soft clip.
252
+ for (const ch of [L, R]) {
253
+ const f = [new Biquad('lowpass', lowpass), new Biquad('lowpass', lowpass), new Biquad('highpass', highpass)];
254
+ for (let i = 0; i < n; i++) ch[i] = f[2].process(f[1].process(f[0].process(ch[i])));
255
+ }
256
+ // Keys bus: open on top (no low-pass), a little less box (~450 Hz), more presence and air above 4 kHz.
257
+ [[BL, L], [BR, R]].forEach(([b, ch]) => {
258
+ const f = [new Biquad('highpass', 110), new Biquad('peak', 450, 1.0, -3.5), new Biquad('highshelf', 4200, 0.7, 3.5)];
259
+ for (let i = 0; i < n; i++) ch[i] += f[2].process(f[1].process(f[0].process(b[i])));
260
+ });
261
+ let max = 1e-9;
262
+ for (let i = 0; i < n; i++) max = Math.max(max, Math.abs(L[i]), Math.abs(R[i]));
263
+ const k = (peak / max) * gain;
264
+ const fadeOut = Math.min(n, Math.round(0.05 * SR));
265
+ for (let i = 0; i < n; i++) {
266
+ const f = i > n - fadeOut ? (n - i) / fadeOut : 1;
267
+ L[i] = Math.tanh(L[i] * k * 1.1) * f; R[i] = Math.tanh(R[i] * k * 1.1) * f;
268
+ }
269
+ return { left: L, right: R, sampleRate: SR };
270
+ }
271
+
272
+ export function writeWav(file, { left, right, sampleRate }) {
273
+ const n = left.length, buf = Buffer.alloc(44 + n * 4);
274
+ buf.write('RIFF', 0); buf.writeUInt32LE(36 + n * 4, 4); buf.write('WAVE', 8);
275
+ buf.write('fmt ', 12); buf.writeUInt32LE(16, 16); buf.writeUInt16LE(1, 20); buf.writeUInt16LE(2, 22);
276
+ buf.writeUInt32LE(sampleRate, 24); buf.writeUInt32LE(sampleRate * 4, 28); buf.writeUInt16LE(4, 32); buf.writeUInt16LE(16, 34);
277
+ buf.write('data', 36); buf.writeUInt32LE(n * 4, 40);
278
+ const rnd = mulberry32(1);
279
+ for (let i = 0; i < n; i++) {
280
+ const d = (rnd() - rnd()) / 32768; // TPDF dither
281
+ buf.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round((left[i] + d) * 32767))), 44 + i * 4);
282
+ buf.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round((right[i] + d) * 32767))), 46 + i * 4);
283
+ }
284
+ fs.writeFileSync(file, buf);
285
+ }