@grame/faustwasm 0.8.0 → 0.9.0

package/assets/standalone/index-pwa.js

@@ -29,120 +29,155 @@ const audioContext = new AudioCtx({ latencyHint: 0.00001 });
 audioContext.destination.channelInterpretation = "discrete";
 audioContext.suspend();
 
+// Declare faustNode as a global variable
+let faustNode;
+
+// Called at load time
 (async () => {
 
-    const { createFaustNode, createFaustUI, connectToAudioInput } = await import("./create-node.js");
+    // Import the create-node module
+    const { createFaustNode, createFaustUI } = await import("./create-node.js");
 
     // To test the ScriptProcessorNode mode
-    //const { faustNode, dspMeta: { name } } = await createFaustNode(audioContext, "osc", FAUST_DSP_VOICES, true, 512);
-    const { faustNode, dspMeta: { name } } = await createFaustNode(audioContext, "osc", FAUST_DSP_VOICES);
+    // const result = await createFaustNode(audioContext, "osc", FAUST_DSP_VOICES, true, 512);
+    const result = await createFaustNode(audioContext, "osc", FAUST_DSP_VOICES);
+    faustNode = result.faustNode;  // Assign to the global variable
     if (!faustNode) throw new Error("Faust DSP not compiled");
 
     // Create the Faust UI
     await createFaustUI($divFaustUI, faustNode);
 
-    // Function to start MIDI
-    function startMIDI() {
-        // Check if the browser supports the Web MIDI API
-        if (navigator.requestMIDIAccess) {
-            navigator.requestMIDIAccess().then(
-                midiAccess => {
-                    console.log("MIDI Access obtained.");
-                    for (let input of midiAccess.inputs.values()) {
-                        input.onmidimessage = (event) => faustNode.midiMessage(event.data);
-                        console.log(`Connected to input: ${input.name}`);
-                    }
-                },
-                () => console.error("Failed to access MIDI devices.")
-            );
-        } else {
-            console.log("Web MIDI API is not supported in this browser.");
-        }
+})();
+
+// Synchronous function to resume AudioContext, to be called first in the synchronous event listener
+function resumeAudioContext() {
+    if (audioContext.state === 'suspended') {
+        audioContext.resume().then(() => {
+            console.log('AudioContext resumed successfully');
+        }).catch(error => {
+            console.error('Error when resuming AudioContext:', error);
+        });
     }
+}
+
+// Function to start MIDI
+function startMIDI() {
+    // Check if the browser supports the Web MIDI API
+    if (navigator.requestMIDIAccess) {
+        navigator.requestMIDIAccess().then(
+            midiAccess => {
+                console.log("MIDI Access obtained.");
+                for (let input of midiAccess.inputs.values()) {
+                    input.onmidimessage = (event) => faustNode.midiMessage(event.data);
+                    console.log(`Connected to input: ${input.name}`);
+                }
+            },
+            () => console.error("Failed to access MIDI devices.")
+        );
+    } else {
+        console.log("Web MIDI API is not supported in this browser.");
+    }
+}
+
+// Function to stop MIDI
+function stopMIDI() {
+    // Check if the browser supports the Web MIDI API
+    if (navigator.requestMIDIAccess) {
+        navigator.requestMIDIAccess().then(
+            midiAccess => {
+                console.log("MIDI Access obtained.");
+                for (let input of midiAccess.inputs.values()) {
+                    input.onmidimessage = null;
+                    console.log(`Disconnected from input: ${input.name}`);
+                }
+            },
+            () => console.error("Failed to access MIDI devices.")
+        );
+    } else {
+        console.log("Web MIDI API is not supported in this browser.");
+    }
+}
+
+let sensorHandlersBound = false;
+let midiHandlersBound = false;
+
+// Function to activate MIDI and Sensors on user interaction
+async function activateMIDISensors() {
+
+    // Import the create-node module
+    const { connectToAudioInput, requestPermissions } = await import("./create-node.js");
 
-    // Function to stop MIDI
-    function stopMIDI() {
-        // Check if the browser supports the Web MIDI API
-        if (navigator.requestMIDIAccess) {
-            navigator.requestMIDIAccess().then(
-                midiAccess => {
-                    console.log("MIDI Access obtained.");
-                    for (let input of midiAccess.inputs.values()) {
-                        input.onmidimessage = null;
-                        console.log(`Disconnected from input: ${input.name}`);
-                    }
-                },
-                () => console.error("Failed to access MIDI devices.")
-            );
-        } else {
-            console.log("Web MIDI API is not supported in this browser.");
-        }
+    // Request permission for sensors
+    await requestPermissions();
+
+    // Activate sensor listeners
+    if (!sensorHandlersBound) {
+        await faustNode.startSensors();
+        sensorHandlersBound = true;
     }
 
-    let sensorHandlersBound = false;
-    let midiHandlersBound = false;
+    // Initialize the MIDI setup
+    if (!midiHandlersBound) {
+        startMIDI();
+        midiHandlersBound = true;
+    }
 
-    // Function to resume AudioContext, activate MIDI and Sensors on user interaction
-    async function activateAudioMIDISensors() {
+    // Connect the Faust node to the audio output
+    faustNode.connect(audioContext.destination);
 
-        // Activate sensor listeners
-        if (!sensorHandlersBound) {
-            await faustNode.startSensors();
-            sensorHandlersBound = true;
-        }
+    // Connect the Faust node to the audio input
+    if (faustNode.numberOfInputs > 0) {
+        await connectToAudioInput(audioContext, null, faustNode, null);
+    }
 
-        // Initialize the MIDI setup
-        if (!midiHandlersBound && FAUST_DSP_VOICES > 0) {
-            startMIDI();
-            midiHandlersBound = true;
-        }
+    // Resume the AudioContext
+    if (audioContext.state === 'suspended') {
+        await audioContext.resume();
+    }
+}
 
-        // Connect the Faust node to the audio output
-        faustNode.connect(audioContext.destination);
+// Function to suspend AudioContext, deactivate MIDI and Sensors on user interaction
+async function deactivateAudioMIDISensors() {
 
-        // Connect the Faust node to the audio input
-        if (faustNode.numberOfInputs > 0) {
-            await connectToAudioInput(audioContext, null, faustNode, null);
-        }
+    // Suspend the AudioContext
+    if (audioContext.state === 'running') {
+        await audioContext.suspend();
+    }
 
-        // Resume the AudioContext
-        if (audioContext.state === 'suspended') {
-            await audioContext.resume();
-        }
+    // Deactivate sensor listeners
+    if (sensorHandlersBound) {
+        faustNode.stopSensors();
+        sensorHandlersBound = false;
     }
 
-    // Function to suspend AudioContext, deactivate MIDI and Sensors on user interaction
-    async function deactivateAudioMIDISensors() {
-
-        // Suspend the AudioContext
-        if (audioContext.state === 'running') {
-            await audioContext.suspend();
-        }
-
-        // Deactivate sensor listeners
-        if (sensorHandlersBound) {
-            faustNode.stopSensors();
-            sensorHandlersBound = false;
-        }
-
-        // Deactivate the MIDI setup
-        if (midiHandlersBound && FAUST_DSP_VOICES > 0) {
-            stopMIDI();
-            midiHandlersBound = false;
-        }
+    // Deactivate the MIDI setup
+    if (midiHandlersBound && FAUST_DSP_VOICES > 0) {
+        stopMIDI();
+        midiHandlersBound = false;
     }
+}
 
-    // Add event listeners for user interactions
+// Event listener to handle user interaction
+function handleUserInteraction() {
 
-    // Activate AudioContext, MIDI and Sensors on user interaction
-    window.addEventListener('click', activateAudioMIDISensors);
-    window.addEventListener('touchstart', activateAudioMIDISensors);
+    // Resume AudioContext synchronously
+    resumeAudioContext();
 
-    // Deactivate AudioContext, MIDI and Sensors on user interaction
-    window.addEventListener('visibilitychange', function () {
-        if (window.visibilityState === 'hidden') {
-            deactivateAudioMIDISensors();
-        }
+    // Launch the activation of MIDI and Sensors
+    activateMIDISensors().catch(error => {
+        console.error('Error when activating audio, MIDI and sensors:', error);
     });
+}
+
+// Activate AudioContext, MIDI and Sensors on user interaction
+window.addEventListener('click', handleUserInteraction);
+window.addEventListener('touchstart', handleUserInteraction);
+
+// Deactivate AudioContext, MIDI and Sensors on user interaction
+window.addEventListener('visibilitychange', function () {
+    if (window.visibilityState === 'hidden') {
+        deactivateAudioMIDISensors();
+    }
+});
+
 
-})();

package/assets/standalone/index-template.js

@@ -1,18 +1,49 @@
 // Set to > 0 if the DSP is polyphonic
 const FAUST_DSP_VOICES = 0;
 
-(async () => {
+// Declare faustNode as a global variable
+let faustNode;
 
-    const { createFaustNode, connectToAudioInput } = await import("./create-node.js");
+// Create audio context activation button
+/** @type {HTMLButtonElement} */
+const $buttonDsp = document.getElementById("button-dsp");
+
+// Create audio context
+const AudioCtx = window.AudioContext || window.webkitAudioContext;
+const audioContext = new AudioCtx({ latencyHint: 0.00001 });
+
+// Activate AudioContext and Sensors on user interaction
+$buttonDsp.disabled = true;
+let sensorHandlersBound = false;
+$buttonDsp.onclick = async () => {
+
+    // Import the requestPermissions function
+    const { requestPermissions } = await import("./create-node.js");
+
+    // Request permission for sensors
+    await requestPermissions();
+
+    // Activate sensor listeners
+    if (!sensorHandlersBound) {
+        await faustNode.startSensors();
+        sensorHandlersBound = true;
+    }
 
-    // Create audio context
-    const AudioCtx = window.AudioContext || window.webkitAudioContext;
-    const audioContext = new AudioCtx({ latencyHint: 0.00001 });
-    audioContext.suspend();
+    // Activate or suspend the AudioContext
+    if (audioContext.state === "running") {
+        $buttonDsp.textContent = "Suspended";
+        await audioContext.suspend();
+    } else if (audioContext.state === "suspended") {
+        $buttonDsp.textContent = "Running";
+        await audioContext.resume();
+        if (FAUST_DSP_VOICES) play(faustNode);
+    }
+}
 
-    // Create audio context activation button
-    /** @type {HTMLButtonElement} */
-    const $buttonDsp = document.getElementById("button-dsp");
+// Called at load time
+(async () => {
+
+    const { createFaustNode, connectToAudioInput } = await import("./create-node.js");
 
     const play = (node) => {
         node.keyOn(0, 60, 100);
@@ -21,21 +52,10 @@ const FAUST_DSP_VOICES = 0;
         setTimeout(() => node.allNotesOff(), 5000);
         setTimeout(() => play(node), 7000);
     }
-    // Function to activate audio context
-    $buttonDsp.disabled = true;
-    $buttonDsp.onclick = async () => {
-        if (audioContext.state === "running") {
-            $buttonDsp.textContent = "Suspended";
-            await audioContext.suspend();
-        } else if (audioContext.state === "suspended") {
-            $buttonDsp.textContent = "Running";
-            await audioContext.resume();
-            if (FAUST_DSP_VOICES) play(faustNode);
-        }
-    }
 
     // Create Faust node
-    const { faustNode, dspMeta: { name } } = await createFaustNode(audioContext, "FAUST_DSP_NAME", FAUST_DSP_VOICES);
+    const result = await createFaustNode(audioContext, "FAUST_DSP_NAME", FAUST_DSP_VOICES);
+    faustNode = result.faustNode;  // Assign to the global variable
     if (!faustNode) throw new Error("Faust DSP not compiled");
 
     // Connect the Faust node to the audio output
@@ -51,4 +71,5 @@ const FAUST_DSP_VOICES = 0;
 
     // Set page title to the DSP name
     document.title = name;
+
 })();

package/assets/standalone/index.js

@@ -41,6 +41,10 @@ audioContext.suspend();
 
 $buttonDsp.disabled = true;
 
+// Declare faustNode as a global variable
+let faustNode;
+
+// Called at load time
 (async () => {
 
     const { createFaustNode, connectToAudioInput, createFaustUI } = await import("./create-node.js");
@@ -111,7 +115,8 @@ $buttonDsp.disabled = true;
 
     // To test the ScriptProcessorNode mode
     // const { faustNode, dspMeta: { name } } = await createFaustNode(audioContext, "FAUST_DSP_NAME", FAUST_DSP_VOICES, true);
-    const { faustNode, dspMeta: { name } } = await createFaustNode(audioContext, "FAUST_DSP_NAME", FAUST_DSP_VOICES);
+    const result = await createFaustNode(audioContext, "FAUST_DSP_NAME", FAUST_DSP_VOICES);
+    faustNode = result.faustNode;  // Assign to the global variable
     if (!faustNode) throw new Error("Faust DSP not compiled");
 
     // Create the Faust UI
@@ -128,22 +133,34 @@ $buttonDsp.disabled = true;
     if (navigator.requestMIDIAccess) await buildMidiDeviceMenu(faustNode);
     else $spanMidiInput.hidden = true;
 
-    // Set the title and enable the DSP button
-    $buttonDsp.disabled = false;
-    document.title = name;
-    let sensorHandlersBound = false;
-    $buttonDsp.onclick = async () => {
-        // Activate sensor listeners
-        if (!sensorHandlersBound) {
-            await faustNode.startSensors();
-            sensorHandlersBound = true;
-        }
-        if (audioContext.state === "running") {
-            $buttonDsp.textContent = "Suspended";
-            await audioContext.suspend();
-        } else if (audioContext.state === "suspended") {
-            $buttonDsp.textContent = "Running";
-            await audioContext.resume();
-        }
-    }
 })();
+
+// Set the title and enable the DSP button
+$buttonDsp.disabled = false;
+document.title = name;
+let sensorHandlersBound = false;
+
+// Activate AudioContext and Sensors on user interaction
+$buttonDsp.onclick = async () => {
+
+    // Import the requestPermissions function
+    const { requestPermissions } = await import("./create-node.js");
+
+    // Request permission for sensors
+    await requestPermissions();
+
+    // Activate sensor listeners
+    if (!sensorHandlersBound) {
+        await faustNode.startSensors();
+        sensorHandlersBound = true;
+    }
+
+    // Activate or suspend the AudioContext
+    if (audioContext.state === "running") {
+        $buttonDsp.textContent = "Suspended";
+        await audioContext.suspend();
+    } else if (audioContext.state === "suspended") {
+        $buttonDsp.textContent = "Running";
+        await audioContext.resume();
+    }
+}

package/assets/standalone/service-worker.js

@@ -5,8 +5,15 @@ const FAUST_DSP_VOICES = 0;
 // Set to true if the DSP has an effect
 const FAUST_DSP_HAS_EFFECT = false;
 
-const CACHE_NAME = "FAUST_DSP_NAME-static"; // Cache name without versioning
+const CACHE_NAME = "FAUST_DSP_NAME_VERSION_DATE"; // Cache name with versioning
 
+/**
+ * List of essential resources required for the **Mono DSP** version of the application.
+ * 
+ * - These files are cached to enable offline functionality and improve loading speed.
+ * - Includes the main HTML, JavaScript, and CSS files required for the app.
+ * - Contains Faust-related files needed for DSP processing.
+ */
 const MONO_RESOURCES = [
     "./index.html",
     "./index.js",
@@ -18,11 +25,23 @@ const MONO_RESOURCES = [
     "./dsp-meta.json"
 ];
 
+/**
+ * List of resources for the **Polyphonic DSP** version of the application.
+ * 
+ * - Extends the mono resource list by adding a **mixer module**.
+ * - The mixer module is required to handle multiple simultaneous voices used in a polyphonic instrument.
+ */
 const POLY_RESOURCES = [
     ...MONO_RESOURCES,
     "./mixer-module.wasm",
 ];
 
+/**
+ * List of resources for the **Polyphonic DSP with Effects** version.
+ * 
+ * - Extends the polyphonic resource list by adding an **effect module**.
+ * - The effect module allows applying audio effects to the polyphonic instrument.
+ */
 const POLY_EFFECT_RESOURCES = [
     ...POLY_RESOURCES,
     "./effect-module.wasm",
@@ -33,13 +52,16 @@ const POLY_EFFECT_RESOURCES = [
 const serviceWorkerGlobalScope = self;
 
 /**
- * Install the service worker and cache the resources
+ * Install the service worker, cache essential resources, and prepare for immediate activation.
+ *
+ * - Opens the cache and stores required assets based on the app's configuration.
+ * - Ensures resources are preloaded for offline access.
  */
 serviceWorkerGlobalScope.addEventListener("install", (event) => {
     console.log("Service worker installed");
     event.waitUntil((async () => {
         const cache = await caches.open(CACHE_NAME);
-        const resources = (FAUST_DSP_VOICES && FAUST_DSP_HAS_EFFECT) ? POLY_EFFECT_RESOURCES : FAUST_DSP_VOICES ? POLY_RESOURCES : MONO_RESOURCES;
+        const resources = (FAUST_DSP_VOICES && FAUST_DSP_HAS_EFFECT) ? POLY_EFFECT_RESOURCES : (FAUST_DSP_VOICES ? POLY_RESOURCES : MONO_RESOURCES);
         try {
             return cache.addAll(resources);
         } catch (error) {
@@ -48,6 +70,16 @@ serviceWorkerGlobalScope.addEventListener("install", (event) => {
     })());
 });
 
+/**
+ * Handles the activation of the Service Worker.
+ * 
+ * - Claims control over all clients immediately, bypassing the default behavior that 
+ *   requires a page reload before the new service worker takes effect.
+ * - Once claimed, it finds all active window clients and reloads them to ensure they are
+ *   controlled by the latest version of the service worker.
+ * - This approach ensures that updates to the service worker take effect immediately
+ *   across all open pages, preventing potential inconsistencies.
+ */
 serviceWorkerGlobalScope.addEventListener("activate", (event) => {
     console.log("Service worker activated");
     event.waitUntil(
@@ -61,7 +93,20 @@ serviceWorkerGlobalScope.addEventListener("activate", (event) => {
     );
 });
 
-/** @type {(response: Response) => Response} */
+/**
+ * Adjusts response headers to enforce Cross-Origin Opener Policy (COOP) and Cross-Origin Embedder Policy (COEP).
+ *
+ * - Ensures that the response is served with `Cross-Origin-Opener-Policy: same-origin`
+ *   and `Cross-Origin-Embedder-Policy: require-corp`.
+ * - Required for enabling **cross-origin isolated** environments in web applications.
+ * - Necessary for features like **SharedArrayBuffer**, WebAssembly threads, and 
+ *   high-performance APIs that require isolation.
+ * - Creates a new `Response` object with the modified headers while preserving 
+ *   the original response body and status.
+ * 
+ * @param {Response} response - The original HTTP response object.
+ * @returns {Response} A new response with updated security headers.
+ */
 const getCrossOriginIsolatedResponse = (response) => {
     // Modify headers to include COOP & COEP
     const headers = new Headers(response.headers);
@@ -79,7 +124,15 @@ const getCrossOriginIsolatedResponse = (response) => {
 };
 
 /**
- * Intercept fetch requests to enforce COOP and COEP headers.
+ * Intercepts fetch requests and enforces COOP and COEP headers for security.
+ *
+ * - Checks if the requested resource is available in the cache:
+ *   - If found, returns a cached response with `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers.
+ *   - If not found, fetches the resource from the network, applies COOP/COEP headers, and caches the response (for GET requests).
+ * - Ensures cross-origin isolation, required for APIs like `SharedArrayBuffer` and WebAssembly threading.
+ * - Handles network errors gracefully by returning a 503 "Service Unavailable" response when needed.
+ * 
+ * @param {FetchEvent} event - The fetch event triggered by the browser.
  */
 serviceWorkerGlobalScope.addEventListener("fetch", (event) => {
 

package/dist/cjs/index.d.ts

@@ -618,6 +618,20 @@ export interface IFaustBaseWebAudioDsp {
 	 * @param value - the MIDI controller value (0..16383)
 	 */
 	pitchWheel(chan: number, value: number): void;
+	/**
+	 * Handle MIDI keyOn messages.
+	 * @param channel
+	 * @param pitch
+	 * @param velocity
+	 */
+	keyOn(channel: number, pitch: number, velocity: number): void;
+	/**
+	 * Handle MIDI keyOn messages.
+	 * @param channel
+	 * @param pitch
+	 * @param velocity
+	 */
+	keyOff(channel: number, pitch: number, velocity: number): void;
 	/**
 	 * Set parameter value.
 	 *
@@ -767,6 +781,24 @@ export declare class FaustBaseWebAudioDsp implements IFaustBaseWebAudioDsp {
 		min: number;
 		max: number;
 	}[][];
+	protected fMidiKeyLabel: {
+		path: string;
+		chan: number;
+		min: number;
+		max: number;
+	}[][];
+	protected fMidiKeyOnLabel: {
+		path: string;
+		chan: number;
+		min: number;
+		max: number;
+	}[][];
+	protected fMidiKeyOffLabel: {
+		path: string;
+		chan: number;
+		min: number;
+		max: number;
+	}[][];
 	protected fPathTable: {
 		[address: string]: number;
 	};
@@ -826,6 +858,8 @@ export declare class FaustBaseWebAudioDsp implements IFaustBaseWebAudioDsp {
 	getNumOutputs(): number;
 	midiMessage(data: number[] | Uint8Array): void;
 	ctrlChange(channel: number, ctrl: number, value: number): void;
+	keyOn(channel: number, pitch: number, velocity: number): void;
+	keyOff(channel: number, pitch: number, velocity: number): void;
 	pitchWheel(channel: number, wheel: number): void;
 	setParamValue(path: string, value: number): void;
 	getParamValue(path: string): number;
@@ -835,11 +869,11 @@ export declare class FaustBaseWebAudioDsp implements IFaustBaseWebAudioDsp {
 	getUI(): FaustUIDescriptor;
 	getDescriptors(): FaustUIInputItem[];
 	hasSoundfiles(): boolean;
+	startSensors(): void;
+	stopSensors(): void;
 	start(): void;
 	stop(): void;
 	destroy(): void;
-	startSensors(): void;
-	stopSensors(): void;
 }
 export declare class FaustMonoWebAudioDsp extends FaustBaseWebAudioDsp implements IFaustMonoWebAudioDsp {
 	private fInstance;
@@ -1180,6 +1214,8 @@ export declare class FaustOfflineProcessor<Poly extends boolean = false> {
 	midiMessage(data: number[] | Uint8Array): void;
 	ctrlChange(chan: number, ctrl: number, value: number): void;
 	pitchWheel(chan: number, value: number): void;
+	keyOn(channel: number, pitch: number, velocity: number): void;
+	keyOff(channel: number, pitch: number, velocity: number): void;
 	setParamValue(path: string, value: number): void;
 	getParamValue(path: string): number;
 	getParams(): string[];
@@ -1374,6 +1410,8 @@ export declare class FaustAudioWorkletNode<Poly extends boolean = false> extends
 	midiMessage(data: number[] | Uint8Array): void;
 	ctrlChange(channel: number, ctrl: number, value: number): void;
 	pitchWheel(channel: number, wheel: number): void;
+	keyOn(channel: number, pitch: number, velocity: number): void;
+	keyOff(channel: number, pitch: number, velocity: number): void;
 	get hasAccInput(): boolean;
 	propagateAcc(accelerationIncludingGravity: NonNullable<DeviceMotionEvent["accelerationIncludingGravity"]>, invert?: boolean): void;
 	get hasGyrInput(): boolean;
@@ -1441,6 +1479,8 @@ export declare class FaustScriptProcessorNode<Poly extends boolean = false> exte
 	midiMessage(data: number[] | Uint8Array): void;
 	ctrlChange(chan: number, ctrl: number, value: number): void;
 	pitchWheel(chan: number, value: number): void;
+	keyOn(channel: number, pitch: number, velocity: number): void;
+	keyOff(channel: number, pitch: number, velocity: number): void;
 	setParamValue(path: string, value: number): void;
 	getParamValue(path: string): number;
 	getParams(): string[];