@onda-lang/webaudio 0.8.20 → 0.8.22

package/README.md

@@ -50,6 +50,24 @@ adapter clamps ranged scalar values and snaps stepped domains before posting the
 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.
 
+The optional host setting `paramSmoothingSeconds` defaults to `0`. A positive value applies finite
+linear ramps to continuous float parameters and array elements. Values advance once per logical
+block, independently of Web Audio callback sizes; durations at most one block are bypassed.
+Integer, boolean, and stepped controls update directly. Initial parameters and reinitialization
+settle immediately. A new target restarts from the published value, while repeated writes of the
+same target preserve its deadline. Host ramps are excluded from processor snapshots. The browser
+playground defaults to `0.03` seconds (30 ms), with a live **Smooth** control in its Params header
+that remembers the duration in the browser. Explicit DSP smoothing can interpolate within a block.
+
+`setParamSmoothingSeconds(seconds)` changes the duration live without recompilation or
+reinitialization. Active ramps restart from the current published value with the new duration.
+Setting 0 (or a duration at most one block) settles active targets immediately and disables ramps;
+smoothing can be enabled later. The duration must be finite and nonnegative, and affects continuous
+float writes from UI controls and automation alike.
+
+`resetParams()` restores all declared defaults immediately and cancels host ramps without resetting
+DSP state.
+
 `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:

package/api.md

@@ -30,7 +30,7 @@ import {
 const compiler = await createCompiler();
 const { artifact } = await compiler.compileSource(source, {
   sampleRate: audioContext.sampleRate,
-  blockSize: 128,
+  blockSize: 512,
 });
 
 const print = ({ text }) => console.debug(text);
@@ -77,12 +77,8 @@ The returned instance provides:
 - `sendLspMessage(message)` and `setLspAnalysisOptions(options?)` for the embedded language server.
 - `dispose()`, an idempotent terminal release of compiler and worker resources.
 
-Compile options accept `sampleRate`, `blockSize`, `defaultParamSmoothingSeconds`, typed
-compile-constant overrides, and `codegen`. `defaultParamSmoothingSeconds` defaults to `0` and must
-be finite and non-negative. It applies to floating-point top-level parameters that omit `smooth`;
-explicit metadata, including `smooth = 0`, takes precedence. Positive values specify block-rate
-linear ramp durations, rounded up to at least one host sample; the sample count must fit signed
-64-bit storage.
+Compile options accept `sampleRate`, `blockSize`, typed compile-constant overrides, and `codegen`.
+The sample rate defaults to 48000 Hz and the block size to 512 frames.
 Code generation can select optimization level `0..4`, shrink level `0..2`, strict or fast math,
 SIMD, loop-containing inlining, and optional WAT emission. A successful compilation returns an
 `OndaCompilationResult` containing the artifact, resolved source paths, and the exact source graph
@@ -211,12 +207,26 @@ the artifact metadata as the adapter constructor's second argument and
 `processorOptions.executionOutputRing` as its fourth argument. Event encoding and numeric
 unknown-index classification require that metadata.
 
+`paramSmoothingSeconds` is an optional **host** setting on `OndaAudioProcessorOptions`, defaulting
+to `0`. It applies finite linear ramps to continuous floating-point parameters and array elements;
+integer, boolean, and stepped parameters update directly. Ramps publish once per logical compile
+block, independent of Web Audio callback sizes. Durations round up to host samples and are bypassed
+when they fit within one block. A changed target starts a fresh ramp from the published value;
+repeated writes of the same target keep its deadline. Initial values and reinitialization settle
+immediately, and processor snapshots do not contain the host ramps. The browser playground opts
+into `0.03` seconds (30 ms). These block-level updates do not interpolate inside `sample:`.
+
 ### `OndaAudioProcessor`
 
 The adapter exposes its `node` and validated `metadata`, plus these operations:
 
 - `setParam(nameOrIndex, plain)` and `setParamNormalized(nameOrIndex, normalized)` for whole
   parameters.
+- `resetParams()` to restore parameter defaults immediately and cancel host ramps, retaining DSP state.
+- `setParamSmoothingSeconds(seconds)` to change the host duration live without recompiling or
+  reinitializing DSP state. Finite, nonnegative durations are required. Active ramps restart from
+  their current values using the new duration; 0 (or a duration at most one block) settles their
+  targets immediately. Smoothing can be enabled after starting with 0.
 - `setParamElement(nameOrIndex, element, plain)` and
   `setParamElementNormalized(nameOrIndex, element, normalized)` for one scalar or fixed-array
   element.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "type": "module",
   "description": "Optional Web Audio adapter for Onda processor WebAssembly artifacts",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "prepack": "node ../../scripts/stage-web-api-docs.mjs"
   },
   "dependencies": {
-    "@onda-lang/processor-abi": "0.8.20"
+    "@onda-lang/processor-abi": "0.8.22"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -52,6 +52,12 @@ export interface OndaAudioProcessorOptions {
   workletUrl?: string | URL;
   /** Initial plain Onda parameter values, keyed or ordered by descriptor parameter. */
   params?: Record<string, unknown> | unknown[];
+  /**
+   * Host-owned linear ramp duration in seconds for continuous float parameters.
+   * Defaults to 0. Ramps advance once per logical block and are bypassed when
+   * the duration is at most one block. Initial values and reinitialization settle immediately.
+   */
+  paramSmoothingSeconds?: number;
   /**
    * 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.
@@ -126,6 +132,10 @@ export class OndaAudioProcessor {
   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>;
+  /** Restore all parameter defaults immediately, cancelling host ramps and retaining DSP state. */
+  resetParams(): Promise<any>;
+  /** Change host smoothing live, restarting active ramps from their current values; 0 settles them immediately. */
+  setParamSmoothingSeconds(seconds: number): Promise<any>;
   /** Set one scalar or fixed-array parameter element without modifying its siblings. */
   setParamElement(param: string | number, element: number, value: unknown): Promise<any>;
   /** Map a host value in [0, 1] through the descriptor and set the resulting plain value. */

package/src/index.js

@@ -1,4 +1,4 @@
-import { paramAddress, paramElementAddress } from "./param-metadata.js";
+import { paramAddress, paramElementAddress, paramSmoothingSamples } from "./param-metadata.js";
 import {
   PayloadPlan,
   createParamControl,
@@ -86,6 +86,7 @@ function audioWorkletNodeOptionsFromValidated(
   if (options.onPrint !== undefined && typeof options.onPrint !== "function") {
     throw new TypeError("initial print listener must be a function");
   }
+  paramSmoothingSamples(options.paramSmoothingSeconds ?? 0, metadata.compile.sample_rate, metadata.compile.block_size);
   const inputChannels = flattenedAudioChannelCount(metadata.metadata.inputs);
   const outputChannels = flattenedAudioChannelCount(metadata.metadata.outputs);
   if (inputChannels > 32 || outputChannels > 32) {
@@ -133,6 +134,7 @@ function audioWorkletNodeOptionsFromValidated(
         ? { wasmBytes: wasm }
         : { wasmModule: options.compiledModule }),
       metadata,
+      paramSmoothingSeconds: options.paramSmoothingSeconds ?? 0,
       params: constrainInitialParamValues(
         metadata.metadata.params,
         options.params ?? {},
@@ -658,6 +660,20 @@ export class OndaAudioProcessor {
     }
   }
 
+  setParamSmoothingSeconds(seconds) {
+    try {
+      paramSmoothingSamples(seconds, this.metadata?.compile?.sample_rate ?? 1,
+        this.metadata?.compile?.block_size ?? 0);
+      return this.request("set-param-smoothing", { seconds });
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  resetParams() {
+    return this.request("reset-params");
+  }
+
   setParamElement(param, element, value) {
     try {
       if (!Array.isArray(this.paramInfo)) {

package/src/param-metadata.js

@@ -31,3 +31,143 @@ export function paramElementAddress(params, selector, element) {
   }
   return { info: address.info, element };
 }
+
+export function paramSmoothingSamples(seconds, sampleRate, blockSize) {
+  const samples = Math.ceil(seconds * sampleRate);
+  if (!Number.isFinite(seconds) || seconds < 0 || !Number.isSafeInteger(samples)) {
+    throw new Error("paramSmoothingSeconds must be finite, non-negative, and fit the host sample counter");
+  }
+  return samples > blockSize ? samples : 0;
+}
+
+// Private host state: descriptors and processor snapshots contain no ramps.
+export class ParamSmoothing {
+  constructor(params, samples, view, paramsPtr) {
+    this.samples = samples;
+    this.inverseSamples = 1 / Math.max(samples, 1);
+    this.started = false;
+    this.addresses = new Map();
+    this.entries = [];
+    for (const param of params) {
+      if ((param.scalar !== "f32" && param.scalar !== "f64")
+        || param.param_control?.step_count != null) continue;
+      const elements = [];
+      const f32 = param.scalar === "f32";
+      for (let element = 0; element < param.array_len; element += 1) {
+        const offset = Number(param.byte_offset) + element * (f32 ? 4 : 8);
+        const value = f32 ? view.getFloat32(paramsPtr + offset, true)
+          : view.getFloat64(paramsPtr + offset, true);
+        elements.push(this.entries.length);
+        this.entries.push({ offset, f32, current: value, start: value,
+          target: value, elapsed: samples, active: false });
+      }
+      this.addresses.set(param, elements);
+    }
+    this.active = new Uint32Array(this.entries.length);
+    this.activeCount = 0;
+  }
+
+  isEnabledFor(param) {
+    return this.samples > 0 && this.addresses.has(param);
+  }
+
+  setDuration(samples, view, paramsPtr) {
+    if (samples === this.samples) return;
+    // Bulk writes bypass ramp state while disabled; read the actual DSP values.
+    if (this.samples === 0) this.readTargets(view, paramsPtr);
+    const previousSamples = this.samples;
+    this.samples = samples;
+    this.inverseSamples = 1 / Math.max(samples, 1);
+    for (let cursor = 0; cursor < this.activeCount; cursor += 1) {
+      const entry = this.entries[this.active[cursor]];
+      if (samples === 0) {
+        this.write(entry, entry.target, view, paramsPtr);
+        entry.active = false;
+      }
+      entry.start = entry.current;
+      entry.elapsed = entry.elapsed === previousSamples ? samples : 0;
+    }
+    if (samples === 0) this.activeCount = 0;
+  }
+
+  readTargets(view, paramsPtr) {
+    for (const entry of this.entries) {
+      entry.current = entry.target = entry.f32
+        ? view.getFloat32(paramsPtr + entry.offset, true)
+        : view.getFloat64(paramsPtr + entry.offset, true);
+      entry.start = entry.current;
+    }
+  }
+
+  setTarget(param, element, value, initialized) {
+    const id = this.addresses.get(param)?.[element];
+    if (id === undefined) return false;
+    const entry = this.entries[id];
+    const target = entry.f32 ? Math.fround(Number(value)) : Number(value);
+    if (this.samples === 0 || !initialized || !this.started || !Number.isFinite(target) || !Number.isFinite(entry.current)) {
+      entry.current = target;
+      entry.target = target;
+      entry.elapsed = this.samples;
+      return false;
+    }
+    if (target === entry.target) return true;
+    entry.start = entry.current;
+    entry.target = target;
+    entry.elapsed = target === entry.current ? this.samples : 0;
+    if (!entry.active) {
+      entry.active = true;
+      this.active[this.activeCount++] = id;
+    }
+    return true;
+  }
+
+  beginBlock(frames, view, paramsPtr) {
+    this.started = true;
+    let cursor = 0;
+    while (cursor < this.activeCount) {
+      const entry = this.entries[this.active[cursor]];
+      entry.elapsed += Math.min(frames, this.samples - entry.elapsed);
+      let value = entry.target;
+      if (entry.elapsed !== this.samples) {
+        const weight = entry.elapsed * this.inverseSamples;
+        if ((entry.start < 0) !== (entry.target < 0)) {
+          value = entry.start * (1 - weight) + entry.target * weight;
+        } else if (weight <= 0.5) {
+          value = entry.start + (entry.target - entry.start) * weight;
+        } else {
+          value = entry.target + (entry.start - entry.target) * (1 - weight);
+        }
+      }
+      this.write(entry, value, view, paramsPtr);
+      if (entry.elapsed === this.samples) {
+        entry.active = false;
+        this.active[cursor] = this.active[--this.activeCount];
+      } else {
+        cursor += 1;
+      }
+    }
+  }
+
+  settle(view, paramsPtr) {
+    if (this.samples === 0) this.readTargets(view, paramsPtr);
+    this.activeCount = 0;
+    this.started = false;
+    for (const entry of this.entries) {
+      this.write(entry, entry.target, view, paramsPtr);
+      entry.start = entry.target;
+      entry.elapsed = this.samples;
+      entry.active = false;
+    }
+  }
+
+  reset(view, paramsPtr) {
+    this.readTargets(view, paramsPtr);
+    this.settle(view, paramsPtr);
+  }
+
+  write(entry, value, view, paramsPtr) {
+    entry.current = entry.f32 ? Math.fround(value) : value;
+    if (entry.f32) view.setFloat32(paramsPtr + entry.offset, entry.current, true);
+    else view.setFloat64(paramsPtr + entry.offset, entry.current, true);
+  }
+}

package/src/worklet.js

@@ -1,4 +1,4 @@
-import { paramAddress, paramElementAddress } from "./param-metadata.js";
+import { paramAddress, paramElementAddress, paramSmoothingSamples, ParamSmoothing } from "./param-metadata.js";
 import {
   EXECUTION_OPERATION_EVENT,
   EXECUTION_OPERATION_INIT,
@@ -144,7 +144,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         "the Onda Web Audio processor requires at least one audio input or output",
       );
     }
-    this.blockSize = Number(metadata.compile?.block_size ?? 128);
+    this.blockSize = Number(metadata.compile?.block_size ?? 512);
     this.compileSampleRate = Number(metadata.compile?.sample_rate ?? sampleRate);
     if (!Number.isInteger(this.blockSize) || this.blockSize <= 0) {
       throw new Error(`invalid compile-time block size: ${this.blockSize}`);
@@ -292,6 +292,12 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     };
     this.writeParamDefaults();
     this.writeInitialParams(processorOptions.params ?? {});
+    this.paramSmoothing = new ParamSmoothing(
+      this.paramInfo,
+      paramSmoothingSamples(processorOptions.paramSmoothingSeconds ?? 0, this.compileSampleRate, this.blockSize),
+      this.memoryView(),
+      this.paramsPtr,
+    );
     this.ensureInputCapacity(this.blockSize);
     this.ensureOutputCapacity(this.blockSize);
     this.viewsReady = true;
@@ -517,14 +523,26 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       throw new Error(`Onda parameter '${param.name}' has invalid storage metadata`);
     }
     if (element !== null) {
-      this.writeScalar(this.paramsPtr + offset + element * this.scalarByteSize(param.scalar), param.scalar, value, this.memoryView());
+      this.setParamScalar(param, element, value);
       return;
     }
-    this.writeStorage(
-      this.paramsPtr + offset,
-      param,
-      value,
-    );
+    if (!this.paramSmoothing?.isEnabledFor(param)) {
+      this.writeStorage(this.paramsPtr + offset, param, value);
+      return;
+    }
+    this.validateStorageValue(param, value);
+    if (this.isFixedArray(param)) {
+      for (let index = 0; index < length; index += 1) {
+        this.setParamScalar(param, index, value[index]);
+      }
+    } else {
+      this.setParamScalar(param, 0, value);
+    }
+  }
+
+  setParamScalar(param, element, value) {
+    if (this.paramSmoothing?.setTarget(param, element, value, this.initialized)) return;
+    this.writeScalar(this.paramsPtr + Number(param.byte_offset) + element * this.scalarByteSize(param.scalar), param.scalar, value);
   }
 
   init(mode) {
@@ -560,6 +578,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.invalidateState();
     this.refreshMemoryCache();
     if (collectOutput) this.prepareExecutionOutput();
+    this.paramSmoothing.settle(this.memoryView(), this.paramsPtr);
     const status = this.exports.onda_processor_init(
       this.paramsPtr,
       this.statePtr,
@@ -729,6 +748,14 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
           message.element ?? null,
         );
         this.postResponse(message, { type: "onda-ok", operation: message.type });
+      } else if (message.type === "set-param-smoothing") {
+        const samples = paramSmoothingSamples(message.seconds, this.compileSampleRate, this.blockSize);
+        this.paramSmoothing.setDuration(samples, this.memoryView(), this.paramsPtr);
+        this.postResponse(message, { type: "onda-ok", operation: message.type });
+      } else if (message.type === "reset-params") {
+        this.writeParamDefaults();
+        this.paramSmoothing.reset(this.memoryView(), this.paramsPtr);
+        this.postResponse(message, { type: "onda-ok", operation: message.type });
       } else if (message.type === "init") {
         this.init(message.mode);
         this.postResponse(message, { type: "onda-ok", operation: message.type });
@@ -1587,6 +1614,10 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       const flags = (startFrame === 0 ? PROCESSOR_BEGIN_BLOCK : 0)
         | (endsBlock ? PROCESSOR_END_BLOCK : 0);
 
+      if (startFrame === 0) {
+        this.paramSmoothing.beginBlock(this.blockSize, this.dataViewCache, this.paramsPtr);
+      }
+
       this.marshalInputSegment(
         inputs,
         frames,