@grame/faustwasm 0.18.0 → 0.18.2

package/README.md

@@ -1,6 +1,6 @@
 # FaustWasm
 
-The FaustWasm library presents a convenient, high-level API that wraps around [Faust](https://faust.grame.fr) compiler. This library's interface is primarily designed for [TypeScript](https://www.typescriptlang.org/) usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both [Node.js](https://nodejs.org) and web browsers, has been compiled using [Emscripten](https://emscripten.org/) 3.1.31.
+The FaustWasm library presents a convenient, high-level API that wraps around [Faust](https://faust.grame.fr) compiler. This library's interface is primarily designed for [TypeScript](https://www.typescriptlang.org/) usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both [Node.js](https://nodejs.org) and web browsers, has been compiled using [Emscripten](https://emscripten.org/) 6.0.3.
 
 The library offers functionality for compiling Faust DSP code into WebAssembly, enabling its utilization as WebAudio nodes within a standard WebAudio node graph. Moreover, it supports offline rendering scenarios. Furthermore, supplementary tools can be employed for generating SVGs from Faust DSP programs.
 
@@ -281,6 +281,33 @@ process = ba.pulsen(1, 10000) : pm.djembe(60, 0.3, 0.4, 1);
 })();
 ```
 
+### Sample-accurate scheduling
+
+Every control method on a Faust AudioWorklet node takes an optional `time` argument as its last parameter: `setParamValue(path, value, time)`, `keyOn(channel, pitch, velocity, time)`, `keyOff(channel, pitch, velocity, time)`, `midiMessage(data, time)`, `ctrlChange(channel, ctrl, value, time)`, `pitchWheel(channel, wheel, time)`. `time` is in AudioContext seconds — the same clock as `audioCtx.currentTime` and `AudioParam.setValueAtTime` — and the action lands on the exact sample that instant names, inside the audio block that contains it. The unit is the second (a JavaScript double), the granularity is the sample: the processor converts it with `Math.round(time * sampleRate)` to a frame on the audio clock, so an instant is honoured to the nearest sample (about 21 µs at 48 kHz):
+
+```JavaScript
+const t0 = audioCtx.currentTime + 0.1;
+
+// A parameter change on the exact sample
+node.setParamValue("/mydsp/gate", 1, t0);
+node.setParamValue("/mydsp/gate", 0, t0 + 0.05);
+
+// A polyphonic pattern scheduled ahead of time
+node.keyOn(0, 60, 100, t0);
+node.keyOff(0, 60, 0, t0 + 0.5);
+node.keyOn(0, 63, 100, t0 + 0.25);
+```
+
+Regular `AudioParam` automation on the node's parameters (`setValueAtTime`, `linearRampToValueAtTime`, ...) is followed sample-accurately as well, so a note and a parameter ramp can be scheduled against one another. Timestamps carried by Web Audio Modules (WAM) events are honoured the same way.
+
+Left out, `time` behaves as before: the message is applied on arrival, at the start of the next audio block. A `time` already in the past is applied as soon as possible, in order. Notes:
+
+- the FFT processor honours `time` at block granularity rather than sample granularity;
+- ScriptProcessor nodes (`sp: true`) accept the argument and apply the message on arrival;
+- `setParamValue` with a negative `time` throws (it is refused by `AudioParam.setValueAtTime`).
+
+The page `test/web/poly-schedule.html` demonstrates the API, and `test/timing/measure.mjs` measures the sample accuracy (see below).
+
 ### Running the tests
 
 Unit tests live in `test/unit` and run in plain Node (no browser needed). This builds the ESM bundle first, then runs every `*.test.mjs` file with Node's built-in test runner:

package/assets/standalone/faustwasm/index.d.ts

@@ -1099,6 +1099,8 @@ export declare class FaustPolyWebAudioDsp extends FaustBaseWebAudioDsp implement
 	private fAudioMixing;
 	private fAudioMixingHalf;
 	private fMixingBase;
+	/** Float view of the memory, kept from `initMemory` like `fHEAP32`. */
+	private fHEAPF;
 	private fVoiceTable;
 	private fSampleRate;
 	/** Voices whose crossfade this block already rendered in full. */
@@ -1123,14 +1125,29 @@ export declare class FaustPolyWebAudioDsp extends FaustBaseWebAudioDsp implement
 	/**
 	 * Render the stolen voices, each across the whole block.
 	 *
-	 * A steal is a crossfade: the voice plays the note it is losing over the
+	 * A steal is a hand-over: the voice plays the note it is losing over the
 	 * first half of the buffer, that half fades out, and the new note plays
-	 * the second half. The fade has to be half a block -- 64 frames -- rather
-	 * than half a slice, which late in the block would be a frame or two, or
-	 * nothing at all. So this runs before the slicing, and `fRenderSlice`
-	 * skips these voices.
+	 * the second half, faded in. Both fades are needed. `fadeOut` scales the
+	 * buffer, not the voice: after `keyOn` the DSP carries on from its live
+	 * state -- an envelope that never reached silence is still up -- so
+	 * without the fade-in the second half started at full level, a step on
+	 * every stolen note. On a monophonic patch whose voice never falls
+	 * silent that is a click on every note after the first (measured on a
+	 * long-release bass: 0, 0, 0, 0.1485, 0.2618 across the split).
+	 *
+	 * The fades have to be half a block -- 64 frames -- rather than half a
+	 * slice, which late in the block would be a frame or two, or nothing at
+	 * all. So this runs before the slicing, and `fRenderSlice` skips these
+	 * voices.
 	 */
 	private renderStolenVoices;
+	/**
+	 * Scale `count` frames of each channel at `$tables` from 1/count up to 1.
+	 *
+	 * The mixer has `fadeOut` in wasm; this is its counterpart on the JS
+	 * side, over the channel-pointer table the same way the mixer reads it.
+	 */
+	private fadeIn;
 	/**
 	 * Move the mixing tables along with the input and output ones.
 	 *

package/assets/standalone/faustwasm/index.js

@@ -3960,12 +3960,20 @@ var FaustPolyWebAudioDsp = class _FaustPolyWebAudioDsp extends FaustBaseWebAudio
   /**
    * Render the stolen voices, each across the whole block.
    *
-   * A steal is a crossfade: the voice plays the note it is losing over the
+   * A steal is a hand-over: the voice plays the note it is losing over the
    * first half of the buffer, that half fades out, and the new note plays
-   * the second half. The fade has to be half a block -- 64 frames -- rather
-   * than half a slice, which late in the block would be a frame or two, or
-   * nothing at all. So this runs before the slicing, and `fRenderSlice`
-   * skips these voices.
+   * the second half, faded in. Both fades are needed. `fadeOut` scales the
+   * buffer, not the voice: after `keyOn` the DSP carries on from its live
+   * state -- an envelope that never reached silence is still up -- so
+   * without the fade-in the second half started at full level, a step on
+   * every stolen note. On a monophonic patch whose voice never falls
+   * silent that is a click on every note after the first (measured on a
+   * long-release bass: 0, 0, 0, 0.1485, 0.2618 across the split).
+   *
+   * The fades have to be half a block -- 64 frames -- rather than half a
+   * slice, which late in the block would be a frame or two, or nothing at
+   * all. So this runs before the slicing, and `fRenderSlice` skips these
+   * voices.
    */
   renderStolenVoices() {
     const stolen = this.fStolen;
@@ -3984,6 +3992,11 @@ var FaustPolyWebAudioDsp = class _FaustPolyWebAudioDsp extends FaustBaseWebAudio
         this.getNumOutputs(),
         this.fAudioMixing
       );
+      this.fadeIn(
+        this.fBufferSize - (this.fBufferSize >> 1),
+        this.getNumOutputs(),
+        this.fAudioMixingHalf
+      );
       voice.fLevel = this.fInstance.mixerAPI.mixCheckVoice(
         this.fBufferSize,
         this.getNumOutputs(),
@@ -3992,6 +4005,22 @@ var FaustPolyWebAudioDsp = class _FaustPolyWebAudioDsp extends FaustBaseWebAudio
       );
     });
   }
+  /**
+   * Scale `count` frames of each channel at `$tables` from 1/count up to 1.
+   *
+   * The mixer has `fadeOut` in wasm; this is its counterpart on the JS
+   * side, over the channel-pointer table the same way the mixer reads it.
+   */
+  fadeIn(count, chans, $tables) {
+    const shift = Math.log2(this.fSampleSize);
+    const HEAPF = this.fHEAPF;
+    for (let chan = 0; chan < chans; chan++) {
+      const start = this.fHEAP32[($tables >> 2) + chan] >> shift;
+      for (let i = 0; i < count; i++) {
+        HEAPF[start + i] *= (i + 1) / count;
+      }
+    }
+  }
   /**
    * Move the mixing tables along with the input and output ones.
    *
@@ -4090,6 +4119,7 @@ var FaustPolyWebAudioDsp = class _FaustPolyWebAudioDsp extends FaustBaseWebAudio
     for (let chan = 0; chan < this.getNumInputs(); chan++) {
       this.fInBase[chan] = HEAP32[(this.fAudioInputs >> 2) + chan];
     }
+    this.fHEAPF = HEAPF;
     this.fOutBase = [];
     this.fMixingBase = [];
     for (let chan = 0; chan < this.getNumOutputs(); chan++) {