@onda-lang/webaudio 0.5.3 → 0.6.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
@@ -55,6 +96,9 @@ rendering node.
 
 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.3",
+  "version": "0.6.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.3"
+    "@onda-lang/processor-abi": "0.6.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -1,10 +1,26 @@
 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[];
   buffers?: Record<string, unknown> | unknown[];
   /** Preallocated capacity for dynamic event payloads. Defaults to 64 KiB. */
@@ -34,10 +50,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

@@ -112,6 +112,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 +339,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 +551,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}'`,
     );
   }
 
@@ -1110,8 +1128,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 +1160,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,