@onda-lang/webaudio 0.6.0 → 0.7.0

package/README.md

@@ -90,9 +90,29 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.6.0",
+  "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.6.0"
+    "@onda-lang/processor-abi": "0.7.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -22,6 +22,10 @@ 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;

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
       : [];
@@ -607,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)
@@ -632,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`);
@@ -655,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