@onda-lang/webaudio 0.5.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Cameli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Onda Web Audio adapter
+
+This optional package hosts a complete wasm32 Onda processor artifact in an `AudioWorklet`. It is a
+reference adapter for the generic Onda processor ABI; Web Audio is not required by the compiler or
+by native and relocatable-WebAssembly object consumers.
+
+```js
+import { createOndaAudioProcessor } from "@onda-lang/webaudio";
+
+const processor = await createOndaAudioProcessor(audioContext, artifact, {
+  params: { gain: 0.5 },
+  buffers: {},
+});
+processor.node.connect(audioContext.destination);
+await processor.setParam("gain", 0.75);
+const snapshot = await processor.snapshot();
+```
+
+The adapter registers `onda-wasm-processor`, derives Web Audio channel options from artifact
+metadata, marshals declared scalar widths, schedules arbitrary render quanta across Onda compile
+blocks, and provides request/response helpers for parameters, events, buffers, control outputs,
+reset, and portable snapshots.
+
+The artifact must be compiled for exactly `audioContext.sampleRate`; the adapter rejects a mismatch
+before registering the node so sample-rate-derived language semantics cannot silently drift. A Web
+Audio processor must expose at least one audio input or output, because an empty callback surface
+does not carry a render-quantum frame count. Control-only artifacts remain usable through the generic
+processor ABI in a non-Web-Audio host.
+
+## Real-time behavior
+
+`createOndaAudioProcessor` compiles the processor's `WebAssembly.Module` concurrently with worklet
+registration, before constructing the `AudioWorkletNode`. The module is structured-cloned into the
+worklet, so processor construction only instantiates it. Applications creating several instances can
+compile once and reuse the module:
+
+```js
+import {
+  compileOndaProcessorModule,
+  createOndaAudioProcessor,
+} from "@onda-lang/webaudio";
+
+const compiledModule = await compileOndaProcessorModule(artifact);
+const left = await createOndaAudioProcessor(context, artifact, { compiledModule });
+const right = await createOndaAudioProcessor(context, artifact, { compiledModule });
+```
+
+After construction, the normal f32 render callback reuses cached Wasm-memory views and performs no
+host-side allocation or memory growth. Full-block f32 inputs and outputs use typed-array bulk copies;
+segmented callbacks and other ABI scalar widths use preallocated typed views with conversion loops
+(i64 input conversion necessarily creates JavaScript `BigInt` values). External buffers are copied
+into Wasm with typed-array bulk operations during construction.
+
+Artifact descriptors and module exports are validated by the shared, compiler-free
+`@onda-lang/processor-abi` package before anything reaches the rendering thread.
+
+Dynamic event storage is also allocated before rendering. Its default capacity is 64 KiB per
+processor with dynamic events and can be changed explicitly:
+
+```js
+const processor = await createOndaAudioProcessor(context, artifact, {
+  eventPayloadCapacityBytes: 256 * 1024,
+});
+```
+
+An event exceeding the configured capacity is rejected instead of growing memory on the rendering
+thread. Parameters and ordinary events are lightweight control operations. Snapshot creation,
+snapshot restore, control-output reads, and especially complete external-buffer reads necessarily
+copy data; suspend or disconnect real-time playback before requesting large transfers.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@onda-lang/webaudio",
+  "version": "0.5.0-rc.0",
+  "type": "module",
+  "description": "Optional Web Audio adapter for Onda processor WebAssembly artifacts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onda-lang/onda.git",
+    "directory": "packages/onda_webaudio"
+  },
+  "homepage": "https://onda-lang.github.io/onda/",
+  "bugs": {
+    "url": "https://github.com/onda-lang/onda/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./worklet": {
+      "types": "./src/worklet.d.ts",
+      "default": "./src/worklet.js"
+    }
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@onda-lang/processor-abi": "0.5.0-rc.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,48 @@
+export const ONDA_AUDIO_WORKLET_PROCESSOR_NAME: "onda-wasm-processor";
+
+export type { OndaProcessorArtifact, OndaProcessorMetadata } from "@onda-lang/processor-abi";
+import type { OndaProcessorArtifact } from "@onda-lang/processor-abi";
+
+export interface OndaAudioProcessorOptions {
+  workletUrl?: string | URL;
+  params?: Record<string, unknown> | unknown[];
+  buffers?: Record<string, unknown> | unknown[];
+  /** Preallocated capacity for dynamic event payloads. Defaults to 64 KiB. */
+  eventPayloadCapacityBytes?: number;
+  /** Reusable module compiled outside the audio rendering thread. */
+  compiledModule?: WebAssembly.Module;
+  nodeOptions?: AudioWorkletNodeOptions;
+  AudioWorkletNode?: typeof AudioWorkletNode;
+}
+
+export function flattenedAudioChannelCount(ports?: unknown[]): number;
+export function ondaAudioWorkletNodeOptions(
+  artifact: OndaProcessorArtifact,
+  options?: OndaAudioProcessorOptions,
+): AudioWorkletNodeOptions;
+export function registerOndaAudioWorklet(
+  context: BaseAudioContext,
+  workletUrl?: string | URL,
+): Promise<void>;
+export function createOndaAudioProcessor(
+  context: BaseAudioContext,
+  artifact: OndaProcessorArtifact,
+  options?: OndaAudioProcessorOptions,
+): Promise<OndaAudioProcessor>;
+export function compileOndaProcessorModule(
+  artifact: OndaProcessorArtifact,
+): Promise<WebAssembly.Module>;
+
+export class OndaAudioProcessor {
+  constructor(node: AudioWorkletNode);
+  readonly node: AudioWorkletNode;
+  request(type: string, fields?: Record<string, unknown>, transfer?: Transferable[]): Promise<any>;
+  setParam(param: string | number, value: unknown): Promise<any>;
+  trigger(event: string | number, values?: Record<string, unknown> | unknown[]): Promise<any>;
+  reset(): Promise<any>;
+  snapshot(): Promise<Uint8Array>;
+  restoreSnapshot(snapshot: Uint8Array | ArrayBuffer): Promise<any>;
+  readControlOutputs(): Promise<Record<string, unknown>>;
+  readBuffer(buffer: string | number): Promise<any>;
+  close(reason?: Error): void;
+}

package/src/index.js

@@ -0,0 +1,241 @@
+import {
+  validateProcessorArtifact,
+  validateProcessorModule,
+} from "@onda-lang/processor-abi";
+
+export const ONDA_AUDIO_WORKLET_PROCESSOR_NAME = "onda-wasm-processor";
+
+const registrationByContext = new WeakMap();
+
+export function flattenedAudioChannelCount(ports = []) {
+  if (!Array.isArray(ports)) {
+    throw new Error("processor audio ports must be an array");
+  }
+  return ports.reduce((count, port, index) => {
+    const channels = Number(port?.array_len);
+    if (!Number.isSafeInteger(channels) || channels <= 0) {
+      throw new Error(
+        `processor audio port ${index} has invalid array_len '${String(port?.array_len)}'`,
+      );
+    }
+    return count + channels;
+  }, 0);
+}
+
+export function ondaAudioWorkletNodeOptions(artifact, options = {}) {
+  const validated = validateExecutableArtifact(
+    artifact,
+    options.compiledModule === undefined,
+  );
+  return audioWorkletNodeOptionsFromValidated(
+    validated,
+    options,
+    options.compiledModule !== undefined,
+  );
+}
+
+function audioWorkletNodeOptionsFromValidated(
+  { wasm, metadata },
+  options,
+  validateCompiledModule,
+) {
+  const inputChannels = flattenedAudioChannelCount(metadata.metadata.inputs);
+  const outputChannels = flattenedAudioChannelCount(metadata.metadata.outputs);
+  if (inputChannels > 32 || outputChannels > 32) {
+    throw new Error("Web Audio supports at most 32 flattened channels per Onda node");
+  }
+  if (inputChannels === 0 && outputChannels === 0) {
+    throw new Error(
+      "the Web Audio adapter requires at least one audio input or output to establish the render quantum",
+    );
+  }
+  if (validateCompiledModule) {
+    validateProcessorModule(options.compiledModule, metadata);
+  }
+  const nodeOptions = {
+    ...options.nodeOptions,
+    numberOfInputs: inputChannels ? 1 : 0,
+    numberOfOutputs: outputChannels ? 1 : 0,
+    channelCount: Math.max(inputChannels, 1),
+    channelCountMode: "explicit",
+    channelInterpretation: "discrete",
+    processorOptions: {
+      ...options.nodeOptions?.processorOptions,
+      ...(options.compiledModule === undefined
+        ? { wasmBytes: wasm }
+        : { wasmModule: options.compiledModule }),
+      metadata,
+      params: options.params ?? {},
+      buffers: options.buffers ?? {},
+      eventPayloadCapacityBytes: options.eventPayloadCapacityBytes,
+    },
+  };
+  if (outputChannels) {
+    nodeOptions.outputChannelCount = [outputChannels];
+  } else {
+    delete nodeOptions.outputChannelCount;
+  }
+  return nodeOptions;
+}
+
+export async function registerOndaAudioWorklet(
+  context,
+  workletUrl = new URL("./worklet.js", import.meta.url),
+) {
+  if (!context?.audioWorklet?.addModule) {
+    throw new Error("an AudioContext with AudioWorklet support is required");
+  }
+  let registration = registrationByContext.get(context);
+  if (!registration) {
+    registration = context.audioWorklet.addModule(workletUrl);
+    registrationByContext.set(context, registration);
+  }
+  try {
+    await registration;
+  } catch (error) {
+    registrationByContext.delete(context);
+    throw error;
+  }
+}
+
+export async function createOndaAudioProcessor(context, artifact, options = {}) {
+  const validated = validateExecutableArtifact(artifact, false);
+  validateContextSampleRate(context, validated.metadata);
+  if (options.compiledModule !== undefined) {
+    validateProcessorModule(options.compiledModule, validated.metadata);
+  }
+  const [, compiledModule] = await Promise.all([
+    registerOndaAudioWorklet(context, options.workletUrl),
+    options.compiledModule === undefined
+      ? compileValidatedProcessorModule(validated)
+      : Promise.resolve(options.compiledModule),
+  ]);
+  const NodeConstructor = options.AudioWorkletNode ?? globalThis.AudioWorkletNode;
+  if (typeof NodeConstructor !== "function") {
+    throw new Error("AudioWorkletNode is not available in this environment");
+  }
+  const node = new NodeConstructor(
+    context,
+    ONDA_AUDIO_WORKLET_PROCESSOR_NAME,
+    audioWorkletNodeOptionsFromValidated(
+      validated,
+      { ...options, compiledModule },
+      false,
+    ),
+  );
+  return new OndaAudioProcessor(node);
+}
+
+export async function compileOndaProcessorModule(artifact) {
+  return compileValidatedProcessorModule(
+    validateExecutableArtifact(artifact, false),
+  );
+}
+
+async function compileValidatedProcessorModule({ wasm, metadata }) {
+  const module = await WebAssembly.compile(wasm);
+  validateProcessorModule(module, metadata);
+  return module;
+}
+
+export class OndaAudioProcessor {
+  constructor(node) {
+    this.node = node;
+    this.nextRequestId = 1;
+    this.pending = new Map();
+    this.handleMessage = (event) => {
+      const message = event.data ?? {};
+      if (message.requestId === undefined) return;
+      const pending = this.pending.get(message.requestId);
+      if (!pending) return;
+      this.pending.delete(message.requestId);
+      if (message.type === "onda-error") {
+        pending.reject(new Error(message.error));
+      } else {
+        pending.resolve(message);
+      }
+    };
+    node.port.addEventListener("message", this.handleMessage);
+    node.port.start?.();
+  }
+
+  request(type, fields = {}, transfer = []) {
+    const requestId = this.nextRequestId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject });
+      try {
+        this.node.port.postMessage({ type, ...fields, requestId }, transfer);
+      } catch (error) {
+        this.pending.delete(requestId);
+        reject(error);
+      }
+    });
+  }
+
+  setParam(param, value) {
+    return this.request("set-param", { param, value });
+  }
+
+  trigger(event, values = {}) {
+    return this.request("event", { event, values });
+  }
+
+  reset() {
+    return this.request("reset");
+  }
+
+  async snapshot() {
+    return (await this.request("snapshot")).bytes;
+  }
+
+  restoreSnapshot(snapshot) {
+    const bytes = snapshot instanceof Uint8Array
+      ? snapshot.slice()
+      : new Uint8Array(snapshot.slice(0));
+    return this.request("restore-snapshot", { snapshot: bytes }, [bytes.buffer]);
+  }
+
+  async readControlOutputs() {
+    return (await this.request("read-control-outputs")).values;
+  }
+
+  async readBuffer(buffer) {
+    return this.request("read-buffer", { buffer });
+  }
+
+  close(reason = new Error("Onda AudioWorklet processor closed")) {
+    this.node.port.removeEventListener("message", this.handleMessage);
+    for (const pending of this.pending.values()) pending.reject(reason);
+    this.pending.clear();
+  }
+}
+
+function validateExecutableArtifact(artifact, inspectModule = true) {
+  const { wasm, metadata } = validateProcessorArtifact(artifact, { inspectModule });
+  if (
+    metadata.integration?.profile?.kind !== "core_webassembly_module"
+    || metadata?.target?.pointer_model !== "linear_memory_offset"
+    || metadata?.target?.pointer_width_bits !== 32
+  ) {
+    throw new Error("the Web Audio adapter requires an Onda wasm32 module artifact");
+  }
+  for (const field of ["inputs", "outputs"]) {
+    if (!Array.isArray(metadata.metadata?.[field])) {
+      throw new Error(`processor metadata is missing '${field}'`);
+    }
+  }
+  return { wasm, metadata };
+}
+
+function validateContextSampleRate(context, metadata) {
+  const actual = Number(context?.sampleRate);
+  const compiled = Number(metadata.compile.sample_rate);
+  if (!Number.isFinite(actual) || actual <= 0) {
+    throw new Error("an AudioContext with a valid sampleRate is required");
+  }
+  if (actual !== compiled) {
+    throw new Error(
+      `processor was compiled for ${compiled} Hz but the AudioContext runs at ${actual} Hz; recompile for the actual context sample rate`,
+    );
+  }
+}

package/src/worklet.d.ts

@@ -0,0 +1 @@
+export {};