@onda-lang/webaudio 0.5.4 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@ const processor = await createOndaAudioProcessor(audioContext, artifact, {
 });
 processor.node.connect(audioContext.destination);
 await processor.setParam("gain", 0.75);
+await processor.setParamNormalized("cutoff", 0.5);
 const snapshot = await processor.snapshot();
 ```
 
@@ -21,6 +22,46 @@ metadata, marshals declared scalar widths, schedules arbitrary render quanta acr
 blocks, and provides request/response helpers for parameters, events, buffers, control outputs,
 reset, and portable snapshots.
 
+## Parameters
+
+`params` passed during construction and values passed to `setParam()` are plain Onda values. The
+adapter clamps ranged scalar values and snaps stepped domains before posting them; the real-time
+worklet only writes the resulting canonical value in the declared scalar representation. Unknown
+initial parameter names or indices are rejected before the worklet node is constructed.
+
+`setParamNormalized()` accepts a host value in `[0, 1]`. The adapter uses the artifact descriptor's
+linear or logarithmic scale and step metadata to convert it to a plain value before posting the
+write to the worklet. Boolean normalized values use the `0.5` threshold. For example:
+
+```js
+await processor.setParam("cutoff", 440);          // exactly 440 Hz
+await processor.setParamNormalized("cutoff", 0.5); // midpoint in its declared control scale
+```
+
+The same synchronous conversion helpers are re-exported for UI display and typed entry:
+
+```js
+import {
+  paramNormalizedToPlain,
+  paramPlainToNormalized,
+} from "@onda-lang/webaudio";
+
+const cutoff = processor.metadata.metadata.params.find(
+  (param) => param.name === "cutoff",
+);
+const displayValue = paramNormalizedToPlain(cutoff, sliderValue);
+const sliderValueFor440Hz = paramPlainToNormalized(cutoff, 440);
+```
+
+The helpers preserve exact endpoints, clamp and snap consistently with adapter writes, and reject
+arrays or numeric parameters without a host-control domain. `scale`, `curve`, `unit`, `step_repr`,
+and `step_count` remain available on each parameter's descriptor metadata for control construction
+and formatting. For repeated UI conversion, `createParamControl(param)` prepares and validates the
+descriptor once and returns bound conversion methods.
+
+Controlled `i64` domains use the descriptor's exact binary64 integer range. Full-width unranged
+`i64` values continue to use `bigint` when written directly.
+
 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
@@ -49,12 +90,35 @@ After construction, the normal f32 render callback reuses cached Wasm-memory vie
 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. Every declared external buffer must
-be supplied with nonempty data; the adapter rejects missing or empty bindings before creating the
-rendering node.
+into Wasm with typed-array bulk operations during construction. Missing or `null` bindings install
+neutral one-frame descriptors: reads return zero, writes are discarded, exact channel counts are
+retained, and dynamic-channel buffers report one channel. Supplied bindings must still contain
+nonempty, correctly shaped data.
+
+Fixed buffer arrays may be supplied under their logical group name. Each slot is independent:
+
+```js
+const processor = await createOndaAudioProcessor(context, artifact, {
+  buffers: {
+    impulse: { data: impulseSamples, channels: 1, sampleRate: 48_000 },
+    bank: [
+      null,
+      { data: secondSamples, channels: 1, sampleRate: 48_000 },
+      // Remaining slots are neutral.
+    ],
+  },
+});
+```
+
+Hosts may instead pass a flat array in physical descriptor order or key individual physical names
+such as `"bank[1]"`. Logical group metadata determines the contiguous slot range; no sample data is
+copied when Onda selects a slot while processing.
 
 Artifact descriptors and module exports are validated by the shared, compiler-free
 `@onda-lang/processor-abi` package before anything reaches the rendering thread.
+If generated init, event, or process code returns a nonzero execution status, the adapter reports
+an `onda-error`, latches the failed state, and emits silence without re-entering processing. A
+successful reset clears the latch after reinitializing state.
 
 Dynamic event storage is also allocated before rendering. Its default capacity is 64 KiB per
 processor with dynamic events and can be changed explicitly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "type": "module",
   "description": "Optional Web Audio adapter for Onda processor WebAssembly artifacts",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@onda-lang/processor-abi": "0.5.4"
+    "@onda-lang/processor-abi": "0.7.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -1,11 +1,31 @@
 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 type {
+  OndaParamDomain,
+  OndaPreparedParamControl,
+  OndaProcessorArtifact,
+  OndaProcessorMetadata,
+} from "@onda-lang/processor-abi";
+export {
+  createParamDomain,
+  createParamControl,
+  constrainParamPlain,
+  paramNormalizedToPlain,
+  paramPlainToNormalized,
+} from "@onda-lang/processor-abi";
+import type {
+  OndaProcessorArtifact,
+  OndaProcessorMetadata,
+} from "@onda-lang/processor-abi";
 
 export interface OndaAudioProcessorOptions {
   workletUrl?: string | URL;
+  /** Initial plain Onda parameter values, keyed or ordered by descriptor parameter. */
   params?: Record<string, unknown> | unknown[];
+  /**
+   * Initial external-buffer bindings keyed by physical name, grouped by logical array name, or
+   * ordered by physical descriptor slot. Missing and null slots use neutral one-frame storage.
+   */
   buffers?: Record<string, unknown> | unknown[];
   /** Preallocated capacity for dynamic event payloads. Defaults to 64 KiB. */
   eventPayloadCapacityBytes?: number;
@@ -34,10 +54,14 @@ export function compileOndaProcessorModule(
 ): Promise<WebAssembly.Module>;
 
 export class OndaAudioProcessor {
-  constructor(node: AudioWorkletNode);
+  constructor(node: AudioWorkletNode, metadata?: OndaProcessorMetadata | null);
   readonly node: AudioWorkletNode;
+  readonly metadata: OndaProcessorMetadata | null;
   request(type: string, fields?: Record<string, unknown>, transfer?: Transferable[]): Promise<any>;
+  /** Set a plain Onda value; ranged scalar values are clamped and snapped. */
   setParam(param: string | number, value: unknown): Promise<any>;
+  /** Map a host value in [0, 1] through the descriptor and set the resulting plain value. */
+  setParamNormalized(param: string | number, value: number): Promise<any>;
   trigger(event: string | number, values?: Record<string, unknown> | unknown[]): Promise<any>;
   reset(): Promise<any>;
   snapshot(): Promise<Uint8Array>;

package/src/index.js

@@ -1,8 +1,17 @@
 import {
+  createParamControl,
   validateProcessorArtifact,
   validateProcessorModule,
 } from "@onda-lang/processor-abi";
 
+export {
+  createParamDomain,
+  createParamControl,
+  constrainParamPlain,
+  paramNormalizedToPlain,
+  paramPlainToNormalized,
+} from "@onda-lang/processor-abi";
+
 export const ONDA_AUDIO_WORKLET_PROCESSOR_NAME = "onda-wasm-processor";
 
 const registrationByContext = new WeakMap();
@@ -65,7 +74,10 @@ function audioWorkletNodeOptionsFromValidated(
         ? { wasmBytes: wasm }
         : { wasmModule: options.compiledModule }),
       metadata,
-      params: options.params ?? {},
+      params: constrainInitialParamValues(
+        metadata.metadata.params,
+        options.params ?? {},
+      ),
       buffers: options.buffers ?? {},
       eventPayloadCapacityBytes: options.eventPayloadCapacityBytes,
     },
@@ -78,6 +90,50 @@ function audioWorkletNodeOptionsFromValidated(
   return nodeOptions;
 }
 
+function paramInfoFor(paramInfo, selector) {
+  const info = Number.isInteger(selector)
+    ? paramInfo[selector]
+    : paramInfo.find((candidate) => candidate.name === selector);
+  if (!info) {
+    throw new Error(`unknown Onda parameter '${String(selector)}'`);
+  }
+  return info;
+}
+
+function preparedParamControl(info, cache = null) {
+  if (Number(info.array_len) !== 1) return null;
+  if (info.scalar !== "bool" && info.param_control === null) return null;
+  let control = cache?.get(info);
+  if (!control) {
+    control = createParamControl(info);
+    cache?.set(info, control);
+  }
+  return control;
+}
+
+function constrainParamValue(info, value, cache = null) {
+  return preparedParamControl(info, cache)?.constrainPlain(value) ?? value;
+}
+
+function constrainInitialParamValues(paramInfo, values) {
+  if (Array.isArray(values)) {
+    return values.map((value, index) => (
+      value === undefined
+        ? value
+        : constrainParamValue(paramInfoFor(paramInfo, index), value)
+    ));
+  }
+  if (values && typeof values === "object") {
+    return Object.fromEntries(
+      Object.entries(values).map(([name, value]) => [
+        name,
+        constrainParamValue(paramInfoFor(paramInfo, name), value),
+      ]),
+    );
+  }
+  throw new Error("params must be an array or object");
+}
+
 export async function registerOndaAudioWorklet(
   context,
   workletUrl = new URL("./worklet.js", import.meta.url),
@@ -123,7 +179,7 @@ export async function createOndaAudioProcessor(context, artifact, options = {})
       false,
     ),
   );
-  return new OndaAudioProcessor(node);
+  return new OndaAudioProcessor(node, validated.metadata);
 }
 
 export async function compileOndaProcessorModule(artifact) {
@@ -139,8 +195,11 @@ async function compileValidatedProcessorModule({ wasm, metadata }) {
 }
 
 export class OndaAudioProcessor {
-  constructor(node) {
+  constructor(node, metadata = null) {
     this.node = node;
+    this.metadata = metadata;
+    this.paramInfo = metadata?.metadata?.params ?? null;
+    this.paramControls = new WeakMap();
     this.nextRequestId = 1;
     this.pending = new Map();
     this.handleMessage = (event) => {
@@ -173,7 +232,39 @@ export class OndaAudioProcessor {
   }
 
   setParam(param, value) {
-    return this.request("set-param", { param, value });
+    try {
+      if (!Array.isArray(this.paramInfo)) {
+        return this.request("set-param", { param, value });
+      }
+      const info = paramInfoFor(this.paramInfo ?? [], param);
+      return this.request("set-param", {
+        param,
+        value: constrainParamValue(info, value, this.paramControls),
+      });
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  setParamNormalized(param, value) {
+    try {
+      if (!Array.isArray(this.paramInfo)) {
+        throw new Error(
+          "setParamNormalized requires processor metadata; construct the adapter with createOndaAudioProcessor()",
+        );
+      }
+      const info = paramInfoFor(this.paramInfo, param);
+      const control = preparedParamControl(info, this.paramControls);
+      if (!control) {
+        throw new Error(`Onda parameter '${info.name}' has no scalar host-control domain`);
+      }
+      return this.request("set-param", {
+        param,
+        value: control.normalizedToPlain(value),
+      });
+    } catch (error) {
+      return Promise.reject(error);
+    }
   }
 
   trigger(event, values = {}) {

package/src/worklet.js

@@ -70,6 +70,9 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.bufferInfo = Array.isArray(metadata.metadata?.buffers)
       ? metadata.metadata.buffers
       : [];
+    this.bufferArrayInfo = Array.isArray(metadata.metadata?.buffer_arrays)
+      ? metadata.metadata.buffer_arrays
+      : [];
     this.inputInfo = Array.isArray(metadata.metadata?.inputs)
       ? metadata.metadata.inputs
       : [];
@@ -112,6 +115,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.outputPtrs = [];
     this.outputCapacityFrames = 0;
     this.blockCursor = 0;
+    this.executionFailed = false;
 
     const paramBytes = Number(metadata.runtime?.param_size_bytes ?? 0);
     if (!Number.isInteger(paramBytes) || paramBytes < 0) {
@@ -338,14 +342,28 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     ) {
       throw new Error(`Onda parameter '${param.name}' has invalid storage metadata`);
     }
-    this.writeStorage(this.paramsPtr + offset, param, value);
+    this.writeStorage(
+      this.paramsPtr + offset,
+      param,
+      value,
+    );
   }
 
   reset() {
     this.refreshMemoryCache();
     this.stateBytes.fill(0);
     this.blockCursor = 0;
-    this.exports.onda_init(this.paramsPtr, this.statePtr);
+    this.executionFailed = false;
+    this.checkExecutionStatus(
+      this.exports.onda_init(this.paramsPtr, this.statePtr),
+      "processor init",
+    );
+  }
+
+  checkExecutionStatus(status, operation) {
+    if (status === 0) return;
+    this.executionFailed = true;
+    throw new Error(`${operation} failed with Onda execution status ${String(status)}`);
   }
 
   createSnapshot() {
@@ -536,14 +554,17 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     if (typeof handler !== "function") {
       throw new Error(`missing WebAssembly export '${event.export}'`);
     }
-    handler(
-      this.eventPayloadPtr,
-      this.paramsPtr,
-      this.statePtr,
-      this.bufferPointersPtr,
-      this.bufferFramesPtr,
-      this.bufferChannelsPtr,
-      this.bufferSampleRatesPtr,
+    this.checkExecutionStatus(
+      handler(
+        this.eventPayloadPtr,
+        this.paramsPtr,
+        this.statePtr,
+        this.bufferPointersPtr,
+        this.bufferFramesPtr,
+        this.bufferChannelsPtr,
+        this.bufferSampleRatesPtr,
+      ),
+      `event '${event.name}'`,
     );
   }
 
@@ -589,11 +610,21 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
 
   bindInitialBuffers(options) {
     this.bufferInfo.forEach((buffer, bufferId) => {
-      const supplied = Array.isArray(options)
-        ? options[bufferId]
-        : options[buffer.name];
-      if (supplied === undefined) {
-        throw new Error(`Onda buffer '${buffer.name}' is not bound`);
+      const supplied = this.initialBufferOption(options, buffer, bufferId);
+      const declaredChannels = Number(buffer.static_channels ?? 0);
+      const fallbackChannels = declaredChannels || 1;
+      if (supplied === undefined || supplied === null) {
+        const sampleRate = Math.fround(this.compileSampleRate);
+        this.writeBufferDescriptor(bufferId, 0, 1, fallbackChannels, sampleRate);
+        this.bufferBindings[bufferId] = {
+          ...buffer,
+          pointer: 0,
+          frames: 1,
+          channels: fallbackChannels,
+          sampleRate,
+          bound: false,
+        };
+        return;
       }
       const descriptor =
         Array.isArray(supplied) || ArrayBuffer.isView(supplied)
@@ -614,7 +645,6 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
           `Onda buffer '${buffer.name}' requires non-empty bound data`,
         );
       }
-      const declaredChannels = Number(buffer.static_channels ?? 0);
       const channels = Number(descriptor.channels ?? declaredChannels);
       if (!Number.isInteger(channels) || channels <= 0) {
         throw new Error(`Onda buffer '${buffer.name}' requires channels > 0`);
@@ -637,25 +667,54 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       const elementSize = this.scalarByteSize(buffer.scalar);
       const pointer = this.alloc(length * elementSize, elementSize);
       this.writeScalarValues(pointer, buffer.scalar, data, length);
-      const view = this.memoryView();
-      view.setUint32(this.bufferPointersPtr + bufferId * 4, pointer, true);
-      view.setInt32(this.bufferFramesPtr + bufferId * 4, frames, true);
-      view.setInt32(this.bufferChannelsPtr + bufferId * 4, channels, true);
-      view.setFloat32(
-        this.bufferSampleRatesPtr + bufferId * 4,
-        sampleRate,
-        true,
-      );
+      this.writeBufferDescriptor(bufferId, pointer, frames, channels, sampleRate);
       this.bufferBindings[bufferId] = {
         ...buffer,
         pointer,
         frames,
         channels,
         sampleRate,
+        bound: true,
       };
     });
   }
 
+  writeBufferDescriptor(bufferId, pointer, frames, channels, sampleRate) {
+    const view = this.memoryView();
+    view.setUint32(this.bufferPointersPtr + bufferId * 4, pointer, true);
+    view.setInt32(this.bufferFramesPtr + bufferId * 4, frames, true);
+    view.setInt32(this.bufferChannelsPtr + bufferId * 4, channels, true);
+    view.setFloat32(this.bufferSampleRatesPtr + bufferId * 4, sampleRate, true);
+  }
+
+  initialBufferOption(options, buffer, bufferId) {
+    if (Array.isArray(options)) {
+      return options[bufferId];
+    }
+    if (!options || typeof options !== "object") {
+      throw new Error("processorOptions.buffers must be an array or object");
+    }
+    if (Object.prototype.hasOwnProperty.call(options, buffer.name)) {
+      return options[buffer.name];
+    }
+    const group = this.bufferArrayInfo.find((candidate) => {
+      const first = Number(candidate.first_buffer);
+      const len = Number(candidate.len);
+      return bufferId >= first && bufferId < first + len;
+    });
+    if (!group || !Object.prototype.hasOwnProperty.call(options, group.name)) {
+      return undefined;
+    }
+    const supplied = options[group.name];
+    if (supplied === undefined || supplied === null) {
+      return undefined;
+    }
+    if (!Array.isArray(supplied)) {
+      throw new Error(`Onda buffer array '${group.name}' must be an array`);
+    }
+    return supplied[bufferId - Number(group.first_buffer)];
+  }
+
   readBuffer(selector) {
     const bufferId = Number.isInteger(selector)
       ? selector
@@ -1110,8 +1169,18 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     );
   }
 
+  clearOutputs(outputs) {
+    for (const bus of outputs) {
+      for (const channel of bus) channel.fill(0);
+    }
+  }
+
   process(inputs, outputs) {
     this.refreshMemoryCache();
+    if (this.executionFailed) {
+      this.clearOutputs(outputs);
+      return true;
+    }
     const frames = this.audioFrameCount(inputs, outputs);
 
     let callbackOffset = 0;
@@ -1132,11 +1201,21 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         startFrame,
         segmentFrames,
       );
-      this.invokeProcessSegment(
+      const status = this.invokeProcessSegment(
         startFrame,
         segmentFrames,
         flags,
       );
+      if (status !== 0) {
+        this.executionFailed = true;
+        this.clearOutputs(outputs);
+        this.port.postMessage({
+          type: "onda-error",
+          operation: "process",
+          error: `processor process failed with Onda execution status ${String(status)}`,
+        });
+        return true;
+      }
       this.marshalOutputSegment(
         outputs,
         frames,