@grame/faustwasm 0.18.0 → 0.18.2

package/test/unit/voice-steal-fade.test.mjs

@@ -0,0 +1,139 @@
+/**
+ * The hand-over on a stolen voice fades in as well as out.
+ *
+ * `renderStolenVoices` plays the outgoing note over the first half of the
+ * block and fades that half out through the mixer. The new note then plays
+ * the second half from the DSP's live state -- `keyOn` does not reset a
+ * voice, and an envelope that never reached silence is still up -- so that
+ * half has to be faded in too, or every stolen note starts with a step.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { FaustPolyWebAudioDsp } from '../../dist/esm/index.js';
+
+const BLOCK = 128;
+
+/**
+ * A polyphonic DSP whose single voice renders a constant 1.
+ *
+ * The mixer is inert -- `fadeOut` is the wasm side's business -- so what
+ * ends up in the mixing buffer is the voice's output shaped only by the
+ * JavaScript side of the hand-over.
+ */
+function polyDsp(block = BLOCK) {
+    const memory = new WebAssembly.Memory({ initial: 1 });
+    const meta = {
+        name: 'probe',
+        inputs: 0,
+        outputs: 1,
+        size: 8,
+        ui: [
+            {
+                type: 'vgroup',
+                label: 'probe',
+                items: [
+                    { type: 'hslider', label: 'freq', address: '/probe/freq', index: 0, init: 440, min: 20, max: 2000, step: 1 },
+                    { type: 'hslider', label: 'gain', address: '/probe/gain', index: 4, init: 0.5, min: 0, max: 1, step: 0.01 },
+                    { type: 'button', label: 'gate', address: '/probe/gate', index: 8 }
+                ]
+            }
+        ]
+    };
+    const voiceAPI = {
+        init: () => {},
+        instanceInit: () => {},
+        instanceClear: () => {},
+        instanceConstants: () => {},
+        instanceResetUserInterface: () => {},
+        setParamValue: () => {},
+        getParamValue: () => 0,
+        compute: (dsp, count, $inputs, $outputs) => {
+            const HEAP32 = new Int32Array(memory.buffer);
+            const HEAPF = new Float32Array(memory.buffer);
+            const start = HEAP32[$outputs >> 2] >> 2;
+            for (let i = 0; i < count; i++) HEAPF[start + i] = 1;
+        },
+        getNumInputs: () => 0,
+        getNumOutputs: () => 1
+    };
+    const instance = {
+        memory,
+        voices: 1,
+        voiceAPI,
+        effectAPI: undefined,
+        effectJSON: undefined,
+        mixerAPI: {
+            clearOutput: () => {},
+            mixCheckVoice: () => 1,
+            fadeOut: () => {}
+        },
+        voiceJSON: JSON.stringify(meta)
+    };
+    const dsp = new FaustPolyWebAudioDsp(instance, 48000, 4, block, []);
+    return { dsp, memory };
+}
+
+/** The mixing buffer of channel 0 after a block. */
+function mixing(dsp, memory, block = BLOCK) {
+    const HEAP32 = new Int32Array(memory.buffer);
+    const HEAPF = new Float32Array(memory.buffer);
+    const start = HEAP32[dsp.fAudioMixing >> 2] >> 2;
+    return Array.from(HEAPF.subarray(start, start + block));
+}
+
+test('the second half of a stolen block fades in from 1/count', () => {
+    const { dsp, memory } = polyDsp();
+    dsp.start();
+    const out = [new Float32Array(BLOCK)];
+    dsp.keyOn(0, 60, 100);
+    dsp.compute([], out);
+    // The pool has one voice, so the next note steals it.
+    dsp.keyOn(0, 67, 100);
+    dsp.compute([], out);
+
+    const half = BLOCK >> 1;
+    const buf = mixing(dsp, memory);
+    // First half: the outgoing note, left to the mixer's fadeOut (inert here).
+    assert.ok(buf.slice(0, half).every((v) => v === 1), 'first half untouched by the JS side');
+    // Second half: a ramp from 1/64 to 1, the mirror of fadeOut.
+    const ramp = buf.slice(half);
+    assert.equal(ramp.length, BLOCK - half);
+    assert.ok(Math.abs(ramp[0] - 1 / ramp.length) < 1e-6, `starts at 1/count, got ${ramp[0]}`);
+    assert.equal(ramp[ramp.length - 1], 1, 'ends at 1');
+    for (let i = 1; i < ramp.length; i++) {
+        assert.ok(ramp[i] > ramp[i - 1], `rises at frame ${i}`);
+    }
+});
+
+test('an odd block gives the extra frame to the second half, and the ramp covers it', () => {
+    const block = 127;
+    const { dsp, memory } = polyDsp(block);
+    dsp.start();
+    const out = [new Float32Array(block)];
+    dsp.keyOn(0, 60, 100);
+    dsp.compute([], out);
+    dsp.keyOn(0, 67, 100);
+    dsp.compute([], out);
+
+    // computeLegato splits at count >> 1 = 63 and renders the remaining 64
+    // frames as the second half; the fade-in is measured from the split.
+    const half = block >> 1;
+    const buf = mixing(dsp, memory, block);
+    assert.ok(buf.slice(0, half).every((v) => v === 1), 'first half untouched by the JS side');
+    const ramp = buf.slice(half);
+    assert.equal(ramp.length, block - half);
+    assert.ok(Math.abs(ramp[0] - 1 / ramp.length) < 1e-6, `starts at 1/count, got ${ramp[0]}`);
+    assert.equal(ramp[ramp.length - 1], 1, 'ends at 1 on the last frame of the block');
+    for (let i = 1; i < ramp.length; i++) {
+        assert.ok(ramp[i] > ramp[i - 1], `rises at frame ${i}`);
+    }
+});
+
+test('a note on a free voice is not faded', () => {
+    const { dsp, memory } = polyDsp();
+    dsp.start();
+    const out = [new Float32Array(BLOCK)];
+    dsp.keyOn(0, 60, 100);
+    dsp.compute([], out);
+    assert.ok(mixing(dsp, memory).every((v) => v === 1), 'no ramp on a fresh voice');
+});

package/test/web/poly-schedule.html

@@ -0,0 +1,97 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8">
+        <title>Sample-accurate scheduling test</title>
+        <script src="../../dist/cjs-bundle/index.js"></script>
+    </head>
+    <body style="font-family: sans-serif; margin: 1.5rem">
+        <h1>Sample-accurate scheduling</h1>
+        <p>
+            Compares the same arpeggio played twice: first scheduled with
+            <code>setTimeout</code> (the pre-timestamp way, jitter of up to a
+            block plus whatever the main thread is doing), then with
+            <code>keyOn(channel, pitch, velocity, time)</code> against the
+            AudioContext clock (each note lands on its exact sample). A gate
+            retrigger inside a single block, inaudible before, closes the demo.
+        </p>
+        <button id="start">Start</button>
+        <pre id="log" style="background: #f6f6f6; padding: 1rem; border-radius: 4px"></pre>
+    </body>
+    <script>
+        const polycode = `
+import("stdfaust.lib");
+process = ba.pulsen(1, ba.hz2midikey(freq) * 1000) : pm.marimba(freq, 0, 7000, 0.5, 0.8) * gate * gain with {
+freq = hslider("freq", 440, 40, 8000, 1);
+gain = hslider("gain", 0.5, 0, 1, 0.01);
+gate = button("gate");
+};
+effect = dm.freeverb_demo;`;
+
+        const PATTERN = [60, 64, 67, 71, 72, 71, 67, 64];
+        const STEP = 0.125; // seconds between notes
+        const log = (msg) => {
+            document.getElementById("log").textContent += msg + "\n";
+            console.log(msg);
+        };
+
+        // The old way: the main thread fires each note when its timer
+        // happens to run.
+        const playWithTimeouts = (node) => {
+            log("Pattern 1: setTimeout scheduling (jitter audible on a busy page)");
+            PATTERN.forEach((pitch, i) => {
+                setTimeout(() => {
+                    node.keyOn(0, pitch, 100);
+                    setTimeout(() => node.keyOff(0, pitch, 0), STEP * 900);
+                }, i * STEP * 1000);
+            });
+        };
+
+        // The new way: everything is scheduled up front against the
+        // AudioContext clock, and each note lands on its exact sample.
+        const playWithTimestamps = (node, audioCtx) => {
+            log("Pattern 2: keyOn(..., time) scheduling (sample-accurate)");
+            const t0 = audioCtx.currentTime + 0.1;
+            PATTERN.forEach((pitch, i) => {
+                node.keyOn(0, pitch, 100, t0 + i * STEP);
+                node.keyOff(0, pitch, 0, t0 + (i + 0.9) * STEP);
+            });
+            return t0 + PATTERN.length * STEP;
+        };
+
+        // A 1 -> 0 -> 1 gate retrigger inside one 128-frame block: both
+        // edges land, so the note audibly restarts. Before timestamps the
+        // whole excursion was lost.
+        const retriggerInsideOneBlock = (node, audioCtx) => {
+            const gatePath = node.getParams().find((p) => p.endsWith("/gate"));
+            log(`Retrigger: ${gatePath} 1 -> 0 -> 1 within a single block`);
+            const t0 = audioCtx.currentTime + 0.1;
+            const frame = 1 / audioCtx.sampleRate;
+            node.keyOn(0, 55, 100, t0);
+            node.keyOff(0, 55, 0, t0 + 1.0);
+            node.setParamValue(gatePath, 0, t0 + 0.5);
+            node.setParamValue(gatePath, 1, t0 + 0.5 + 32 * frame);
+        };
+
+        const { instantiateFaustModule, LibFaust, FaustCompiler, FaustPolyDspGenerator } = faustwasm;
+        document.getElementById("start").onclick = async () => {
+            const audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+            await audioCtx.resume();
+            const faustModule = await instantiateFaustModule();
+            const libFaust = new LibFaust(faustModule);
+            const compiler = new FaustCompiler(libFaust);
+            const generator = new FaustPolyDspGenerator();
+            await generator.compile(compiler, "dsp", polycode, "");
+            const node = await generator.createNode(audioCtx, 4);
+            node.connect(audioCtx.destination);
+            log("Node ready");
+
+            playWithTimeouts(node);
+            setTimeout(() => {
+                const end = playWithTimestamps(node, audioCtx);
+                const msLeft = (end - audioCtx.currentTime) * 1000 + 500;
+                setTimeout(() => retriggerInsideOneBlock(node, audioCtx), msLeft);
+            }, PATTERN.length * STEP * 1000 + 500);
+        };
+    </script>
+</html>