@libraz/libsonare 1.5.4 → 1.6.0

package/src/worklet/engine-capture-facade.ts

@@ -15,11 +15,17 @@ type CaptureConfig = Omit<SonareEngineSyncCaptureMessage, 'type'>;
 export interface EngineCaptureContext {
   readonly offlineEngine: RealtimeEngine;
   readonly realtimeNode: SonareRealtimeEngineNode;
+  sendCommand(command: {
+    type: SonareEngineCommandType;
+    targetId?: number;
+    sampleTime?: number;
+    argFloat?: number;
+    argInt?: number;
+  }): boolean;
   readonly offlineChannelCount: number;
   postSync(message: SonareEngineSyncMessage): void;
   getCaptureConfig(): CaptureConfig | undefined;
   setCaptureConfig(config: CaptureConfig): void;
-  resolveTargetId(target: string | number): number;
 }
 
 export function configureCapture(ctx: EngineCaptureContext, options: CaptureOptions): void {
@@ -37,13 +43,16 @@ export function armRecord(
   trackId: string | number,
   enabled: boolean,
 ): boolean {
+  if (trackId !== 0) {
+    throw new RangeError('Capture is global; armRecord only accepts trackId 0');
+  }
   if (enabled && !ctx.getCaptureConfig()) {
     throw new Error('Capture buffer is not configured');
   }
   ctx.offlineEngine.armCapture(enabled);
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.ArmRecord,
-    targetId: ctx.resolveTargetId(trackId),
+    targetId: 0,
     sampleTime: -1,
     argInt: enabled ? 1 : 0,
   });
@@ -58,7 +67,7 @@ export function punch(ctx: EngineCaptureContext, inPpq: number, outPpq: number):
   // point and let the consumer multiply by sampleRate (treating PPQ as
   // seconds), which ignored tempo and produced a punch-out ~2x too large at
   // 120 BPM. argInt = in sample, argFloat = out sample (full-precision double).
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.Punch,
     sampleTime: -1,
     argInt: inSample,

package/src/worklet/engine-clips.ts

@@ -1,4 +1,5 @@
 import type { EngineClip, EngineMidiClipSchedule, RealtimeEngine } from '../index';
+import type { ClipPageProvider } from '../realtime_engine';
 import type { SonareEngineSyncMessage } from './messages';
 
 /**
@@ -14,6 +15,8 @@ export interface EngineClipContext {
   postSync(message: SonareEngineSyncMessage, transfer?: Transferable[]): void;
   resolveTargetId(target: string | number): number;
   ensureTrackLane(target: string | number): number;
+  /** Commits a provider already primed through the worklet's OPFS pull bridge. */
+  commitWorkletClipPageProvider(clip: EngineClip): boolean;
 }
 
 // Keep control-message work bounded even for long tempo-synced clips. The
@@ -25,15 +28,15 @@ const PREBAKED_CLIP_PAGE_FRAMES = 4_096;
 export function addClip(
   ctx: EngineClipContext,
   trackId: string | number,
-  buffer: Float32Array[],
+  buffer: Float32Array[] | ClipPageProvider,
   startPpq: number,
-  opts: Partial<Omit<EngineClip, 'channels' | 'startPpq'>> = {},
+  opts: Partial<Omit<EngineClip, 'channels' | 'pageProvider' | 'startPpq'>> = {},
 ): number {
   const id = opts.id ?? ctx.allocateClipId();
   const clip: EngineClip = {
     ...opts,
     id,
-    channels: buffer,
+    ...(Array.isArray(buffer) ? { channels: buffer } : { pageProvider: buffer }),
     startPpq,
     trackId: ctx.resolveTargetId(trackId),
   };
@@ -88,6 +91,12 @@ function syncClipsDelta(ctx: EngineClipContext, upserts: EngineClip[], removeIds
   for (const clip of upserts) {
     const prepared = clip.id === undefined ? clip : (preparedById.get(clip.id) ?? clip);
     const channels = prepared.channels;
+    if (!channels && prepared.pageProvider !== undefined) {
+      if (ctx.commitWorkletClipPageProvider(prepared)) {
+        continue;
+      }
+      throw new Error('A pageProvider on SonareEngine must be created by attachOpfsClipStream().');
+    }
     if (
       prepared.id === undefined ||
       prepared.warpMode !== 'off' ||

package/src/worklet/engine-node.ts

@@ -1,6 +1,7 @@
 import type { EngineCaptureStatus, EngineTransportState } from '../index';
 import { engineCapabilities } from '../index';
 import {
+  isClipPageRequestMessage,
   isEngineCaptureResponseMessage,
   isEngineTelemetryRecord,
   isEngineTransportResponseMessage,
@@ -10,6 +11,8 @@ import {
 import type {
   SonareEngineCaptureRequestMessage,
   SonareEngineCaptureResponseMessage,
+  SonareEngineClipPageRequestMessage,
+  SonareEngineSyncErrorMessage,
   SonareEngineTransportResponseMessage,
   SonareRealtimeEngineNodeCapabilities,
   SonareRealtimeEngineNodeOptions,
@@ -17,26 +20,68 @@ import type {
   SonareWorkletExternalMidiEvent,
 } from './messages';
 import {
+  createSonareClipPageRequestRingBuffer,
   createSonareEngineCommandRingBuffer,
   createSonareEngineTelemetryRingBuffer,
+  createSonareExternalMidiRingBuffer,
   createSonareMeterRingBuffer,
   createSonareScopeRingBuffer,
   isRecord,
   pushSonareEngineCommandRingBuffer,
+  readSonareClipPageRequestRingBuffer,
   readSonareEngineTelemetryRingBuffer,
+  readSonareExternalMidiRingBuffer,
   readSonareMeterRingBuffer,
   readSonareScopeRingBuffer,
+  type SonareClipPageRequestRingBuffer,
   type SonareEngineCommandRecord,
   type SonareEngineCommandRingBuffer,
   SonareEngineCommandType,
   type SonareEngineTelemetryRecord,
   type SonareEngineTelemetryRingBuffer,
+  type SonareExternalMidiRingBuffer,
   type SonareMeterRingBuffer,
   type SonareScopeRingBuffer,
   type SonareWorkletMeterSnapshot,
   type SonareWorkletScopeSnapshot,
 } from './protocol';
 
+function isFiniteInteger(value: number | bigint | undefined): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  return typeof value === 'bigint' || (Number.isFinite(value) && Number.isSafeInteger(value));
+}
+
+function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
+  const type = Number(command.type);
+  if (
+    !Number.isSafeInteger(type) ||
+    type < SonareEngineCommandType.SetParam ||
+    type > SonareEngineCommandType.SeekMarker
+  ) {
+    return false;
+  }
+  return (
+    (command.targetId === undefined || Number.isSafeInteger(command.targetId)) &&
+    (command.argFloat === undefined || Number.isFinite(command.argFloat)) &&
+    isFiniteInteger(command.argInt) &&
+    isFiniteInteger(command.sampleTime)
+  );
+}
+
+const AUDIO_WORKLET_RENDER_QUANTUM = 128;
+
+function workletBlockSize(blockSize: number | undefined): number {
+  const resolved = blockSize ?? AUDIO_WORKLET_RENDER_QUANTUM;
+  if (!Number.isSafeInteger(resolved) || resolved < AUDIO_WORKLET_RENDER_QUANTUM) {
+    throw new RangeError(
+      `blockSize must be an integer of at least ${AUDIO_WORKLET_RENDER_QUANTUM} frames`,
+    );
+  }
+  return resolved;
+}
+
 export class SonareRealtimeEngineNode {
   readonly node: AudioWorkletNode;
   readonly capabilities: SonareRealtimeEngineNodeCapabilities;
@@ -44,14 +89,22 @@ export class SonareRealtimeEngineNode {
   readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
   readonly meterRing?: SonareMeterRingBuffer;
   readonly scopeRing?: SonareScopeRingBuffer;
+  readonly clipPageRequestRing?: SonareClipPageRequestRingBuffer;
+  readonly externalMidiRing?: SonareExternalMidiRingBuffer;
   readonly ready: Promise<void>;
   private telemetryReadIndex = 0;
   private meterReadIndex = 0;
   private scopeReadIndex = 0;
+  private clipPageRequestDroppedRead = 0;
+  private ringPollTimer: ReturnType<typeof setInterval> | undefined;
   private telemetryListeners = new Set<(telemetry: SonareEngineTelemetryRecord) => void>();
   private meterListeners = new Set<(meter: SonareWorkletMeterSnapshot) => void>();
   private scopeListeners = new Set<(scope: SonareWorkletScopeSnapshot) => void>();
   private midiOutListeners = new Set<(events: SonareWorkletExternalMidiEvent[]) => void>();
+  private clipPageRequestListeners = new Set<
+    (message: SonareEngineClipPageRequestMessage) => void
+  >();
+  private syncErrorListeners = new Set<(message: SonareEngineSyncErrorMessage) => void>();
   private captureRequestId = 1;
   private readonly captureRequests = new Map<
     number,
@@ -79,6 +132,8 @@ export class SonareRealtimeEngineNode {
     telemetryRing?: SonareEngineTelemetryRingBuffer,
     meterRing?: SonareMeterRingBuffer,
     scopeRing?: SonareScopeRingBuffer,
+    clipPageRequestRing?: SonareClipPageRequestRingBuffer,
+    externalMidiRing?: SonareExternalMidiRingBuffer,
   ) {
     this.node = node;
     this.capabilities = capabilities;
@@ -86,6 +141,8 @@ export class SonareRealtimeEngineNode {
     this.telemetryRing = telemetryRing;
     this.meterRing = meterRing;
     this.scopeRing = scopeRing;
+    this.clipPageRequestRing = clipPageRequestRing;
+    this.externalMidiRing = externalMidiRing;
     this.ready = new Promise((resolve, reject) => {
       this.resolveReady = resolve;
       this.rejectReady = reject;
@@ -120,6 +177,17 @@ export class SonareRealtimeEngineNode {
         this.emitMeter(event.data);
       } else if (isExternalMidiBatchMessage(event.data)) {
         this.emitMidiOut(event.data.events);
+      } else if (isClipPageRequestMessage(event.data)) {
+        this.emitClipPageRequests(event.data);
+      } else if (isRecord(event.data) && event.data.type === 'syncError') {
+        const syncError: SonareEngineSyncErrorMessage = {
+          type: 'syncError',
+          syncType: String(event.data.syncType) as SonareEngineSyncErrorMessage['syncType'],
+          message: String(event.data.message ?? 'AudioWorklet sync failed'),
+        };
+        for (const listener of this.syncErrorListeners) {
+          listener(syncError);
+        }
       } else if (isRecord(event.data) && event.data.type === 'ready') {
         this.resolveReady();
       } else if (isRecord(event.data) && event.data.type === 'error') {
@@ -128,10 +196,17 @@ export class SonareRealtimeEngineNode {
     };
   }
 
+  /** Subscribes to control-plane sync rejections reported by the worklet. */
+  onSyncError(listener: (message: SonareEngineSyncErrorMessage) => void): () => void {
+    this.syncErrorListeners.add(listener);
+    return () => this.syncErrorListeners.delete(listener);
+  }
+
   static async create(
     context: BaseAudioContext,
     options: SonareRealtimeEngineNodeOptions = {},
   ): Promise<SonareRealtimeEngineNode> {
+    const blockSize = workletBlockSize(options.blockSize);
     const processorName = options.processorName ?? 'sonare-realtime-engine-processor';
     const moduleUrl = options.moduleUrl;
     if (moduleUrl && context.audioWorklet?.addModule) {
@@ -188,10 +263,21 @@ export class SonareRealtimeEngineNode {
       mode === 'sab' && scopeIntervalFrames > 0
         ? createSonareScopeRingBuffer(options.scopeRingCapacity ?? 64, options.scopeBands ?? 48)
         : undefined;
+    // Paged-clip cache misses are a worklet-to-main-thread control signal. A
+    // dedicated SPSC SAB ring keeps process() free of both embind request
+    // objects and postMessage structured cloning.
+    const clipPageRequestRing =
+      mode === 'sab'
+        ? createSonareClipPageRequestRingBuffer(options.clipPageRequestRingCapacity ?? 128)
+        : undefined;
+    const externalMidiRing =
+      mode === 'sab'
+        ? createSonareExternalMidiRingBuffer(options.externalMidiRingCapacity ?? 256)
+        : undefined;
     const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
     const processorOptions: SonareRealtimeEngineWorkletProcessorOptions = {
       sampleRate: options.sampleRate ?? context.sampleRate,
-      blockSize: options.blockSize,
+      blockSize,
       channelCount,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
@@ -203,6 +289,10 @@ export class SonareRealtimeEngineNode {
       scopeRingCapacity: scopeRing?.capacity,
       scopeBands: scopeRing?.bands,
       scopeIntervalFrames: scopeRing ? scopeIntervalFrames : undefined,
+      clipPageRequestSharedBuffer: clipPageRequestRing?.sharedBuffer,
+      clipPageRequestRingCapacity: clipPageRequestRing?.capacity,
+      externalMidiSharedBuffer: externalMidiRing?.sharedBuffer,
+      externalMidiRingCapacity: externalMidiRing?.capacity,
       wasmBinary: options.wasmBinary,
       initialSyncMessages: options.initialSyncMessages,
       initialCommands: options.initialCommands,
@@ -225,16 +315,23 @@ export class SonareRealtimeEngineNode {
         sharedArrayBuffer,
         atomics,
         audioWorklet,
+        clipPageRequestsRealtimeSafe: mode === 'sab',
+        externalMidiRealtimeSafe: mode === 'sab',
         engineAbiVersion: detectedCapabilities?.engineAbiVersion,
         expectedEngineAbiVersion: detectedCapabilities?.expectedEngineAbiVersion,
         abiCompatible: detectedCapabilities?.abiCompatible,
         degradedReason,
-        readyMessage: moduleUrl !== undefined && !options.nodeFactory,
+        // A processor posts ready/error irrespective of whether its module was
+        // loaded here or registered by the host beforehand. Waiting in both
+        // cases is the only way to surface a failed worklet-side WASM init.
+        readyMessage: true,
       },
       commandRing,
       telemetryRing,
       meterRing,
       scopeRing,
+      clipPageRequestRing,
+      externalMidiRing,
     );
   }
 
@@ -255,6 +352,9 @@ export class SonareRealtimeEngineNode {
   }
 
   seekPpq(ppq: number, sampleTime = -1): boolean {
+    if (!Number.isFinite(ppq) || !Number.isSafeInteger(sampleTime)) {
+      return false;
+    }
     return this.sendCommand({
       type: SonareEngineCommandType.TransportSeekPpq,
       sampleTime,
@@ -263,7 +363,7 @@ export class SonareRealtimeEngineNode {
   }
 
   sendCommand(command: SonareEngineCommandRecord): boolean {
-    if (this.destroyed) {
+    if (this.destroyed || !isValidCommandRecord(command)) {
       return false;
     }
     if (this.commandRing) {
@@ -345,24 +445,77 @@ export class SonareRealtimeEngineNode {
     return read.scopes;
   }
 
+  /** Drain lowered MIDI-1 records from the SAB ring on the main thread. */
+  pollMidiOut(): SonareWorkletExternalMidiEvent[] {
+    if (!this.externalMidiRing) {
+      return [];
+    }
+    const read = readSonareExternalMidiRingBuffer(this.externalMidiRing);
+    const events = read.events.map((event) => {
+      const bytes: number[] = [];
+      for (let index = 0; index < event.byteCount; index++) {
+        bytes.push((event.byteWord >>> (8 * index)) & 0xff);
+      }
+      return {
+        destinationId: event.destinationId,
+        renderFrame: event.renderFrame,
+        bytes,
+      };
+    });
+    if (events.length > 0) {
+      this.emitMidiOut(events);
+    }
+    return events;
+  }
+
+  /**
+   * Drains bounded paged-clip misses from the SAB ring and forwards one batch
+   * to subscribers. In postMessage mode the legacy handler remains available,
+   * but that degraded path is not realtime-safe for OPFS streaming.
+   */
+  pollClipPageRequests(): SonareEngineClipPageRequestMessage | undefined {
+    if (!this.clipPageRequestRing) {
+      return undefined;
+    }
+    const read = readSonareClipPageRequestRingBuffer(this.clipPageRequestRing);
+    const dropped = (read.dropped - this.clipPageRequestDroppedRead) >>> 0;
+    this.clipPageRequestDroppedRead = read.dropped;
+    if (read.requests.length === 0 && dropped === 0) {
+      return undefined;
+    }
+    const message: SonareEngineClipPageRequestMessage = {
+      type: 'clipPageRequest',
+      requests: read.requests,
+      ...(dropped > 0 ? { dropped } : {}),
+    };
+    this.emitClipPageRequests(message);
+    return message;
+  }
+
   onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void {
     this.telemetryListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.telemetryListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
   onMeter(callback: (meter: SonareWorkletMeterSnapshot) => void): () => void {
     this.meterListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.meterListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
   onScope(callback: (scope: SonareWorkletScopeSnapshot) => void): () => void {
     this.scopeListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.scopeListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
@@ -373,17 +526,33 @@ export class SonareRealtimeEngineNode {
    */
   onMidiOut(callback: (events: SonareWorkletExternalMidiEvent[]) => void): () => void {
     this.midiOutListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.midiOutListeners.delete(callback);
     };
   }
 
+  /**
+   * Subscribe to bounded batches of paged-clip misses from the worklet. The
+   * callback runs on the main thread and may initiate asynchronous OPFS I/O.
+   */
+  onClipPageRequests(callback: (message: SonareEngineClipPageRequestMessage) => void): () => void {
+    this.clipPageRequestListeners.add(callback);
+    return () => {
+      this.clipPageRequestListeners.delete(callback);
+    };
+  }
+
   destroy(): void {
     if (this.destroyed) {
       return;
     }
     this.destroyed = true;
-    this.node.port.postMessage({ type: SonareEngineCommandType.TransportStop, sampleTime: -1 });
+    if (this.ringPollTimer !== undefined) {
+      clearInterval(this.ringPollTimer);
+      this.ringPollTimer = undefined;
+    }
+    this.node.port.postMessage({ type: 'destroy' });
     this.node.disconnect();
     for (const pending of this.captureRequests.values()) {
       pending.reject(new Error('Realtime engine node is destroyed.'));
@@ -397,6 +566,7 @@ export class SonareRealtimeEngineNode {
     this.meterListeners.clear();
     this.scopeListeners.clear();
     this.midiOutListeners.clear();
+    this.clipPageRequestListeners.clear();
   }
 
   private emitTelemetry(telemetry: SonareEngineTelemetryRecord): void {
@@ -405,6 +575,38 @@ export class SonareRealtimeEngineNode {
     }
   }
 
+  private startRingPolling(): void {
+    if (
+      this.ringPollTimer !== undefined ||
+      (!this.telemetryRing && !this.meterRing && !this.scopeRing && !this.externalMidiRing)
+    ) {
+      return;
+    }
+    const poll = () => {
+      if (!this.destroyed) {
+        this.pollTelemetry();
+        this.pollMeters();
+        this.pollScope();
+        this.pollMidiOut();
+      }
+    };
+    poll();
+    this.ringPollTimer = setInterval(poll, 16);
+  }
+
+  private stopRingPollingIfUnused(): void {
+    if (
+      this.ringPollTimer !== undefined &&
+      this.telemetryListeners.size === 0 &&
+      this.meterListeners.size === 0 &&
+      this.scopeListeners.size === 0 &&
+      this.midiOutListeners.size === 0
+    ) {
+      clearInterval(this.ringPollTimer);
+      this.ringPollTimer = undefined;
+    }
+  }
+
   private emitMeter(meter: SonareWorkletMeterSnapshot): void {
     for (const listener of this.meterListeners) {
       listener(meter);
@@ -417,6 +619,12 @@ export class SonareRealtimeEngineNode {
     }
   }
 
+  private emitClipPageRequests(message: SonareEngineClipPageRequestMessage): void {
+    for (const listener of this.clipPageRequestListeners) {
+      listener(message);
+    }
+  }
+
   private emitScope(scope: SonareWorkletScopeSnapshot): void {
     for (const listener of this.scopeListeners) {
       listener(scope);

package/src/worklet/engine-offline.ts

@@ -47,6 +47,7 @@ export interface EngineTransportContext {
     seekSample(timelineSample: number, sampleTime?: number): boolean;
   };
   offlineEngine: RealtimeEngine;
+  flushOfflineMirror(): void;
   setTransportPlaying(playing: boolean): void;
   flushPendingInstrumentSync(): void;
   setTempo(bpm: number): void;
@@ -74,12 +75,16 @@ export function buildTransportFacade(ctx: EngineTransportContext): SonareEngineT
     },
     seekPpq: (ppq, sampleTime = -1) => {
       ctx.offlineEngine.seekPpq(ppq, sampleTime);
-      return ctx.realtimeNode.seekPpq(ppq, sampleTime);
+      const ok = ctx.realtimeNode.seekPpq(ppq, sampleTime);
+      ctx.flushOfflineMirror();
+      return ok;
     },
     seekSeconds: (seconds, sampleTime = -1) => {
       const timelineSample = Math.max(0, Math.round(seconds * ctx.sampleRate));
       ctx.offlineEngine.seekSample(timelineSample, sampleTime);
-      return ctx.realtimeNode.seekSample(timelineSample, sampleTime);
+      const ok = ctx.realtimeNode.seekSample(timelineSample, sampleTime);
+      ctx.flushOfflineMirror();
+      return ok;
     },
     setTempo: (bpm) => ctx.setTempo(bpm),
     setTempoSegments: (segments) => ctx.setTempoSegments(segments),

package/src/worklet/engine-parameter-facade.ts

@@ -1,5 +1,5 @@
-import type { EngineParameterInfo, RealtimeEngine } from '../index';
-import type { SonareRealtimeEngineNode } from './engine-node';
+import type { EngineAutomationPoint, EngineParameterInfo, RealtimeEngine } from '../index';
+import type { SonareEngineSyncMessage } from './messages';
 import {
   ENGINE_MIXER_PARAM_FADER_DB,
   ENGINE_MIXER_PARAM_PAN,
@@ -17,7 +17,15 @@ import {
  */
 export interface EngineParameterContext {
   readonly offlineEngine: RealtimeEngine;
-  readonly realtimeNode: SonareRealtimeEngineNode;
+  sendCommand(command: {
+    type: SonareEngineCommandType;
+    targetId?: number;
+    sampleTime?: number;
+    argFloat?: number;
+    argInt?: number;
+  }): boolean;
+  postSync(message: SonareEngineSyncMessage): void;
+  readonly automationLanes: Map<number, EngineAutomationPoint[]>;
   readonly trackLaneIds: number[];
   resolveParamId(nodeId: string, param: string | number): number;
   ensureTrackLane(target: string | number): number;
@@ -35,7 +43,7 @@ export function setParam(
   // reflects the live value, then push a sample-accurate command to the
   // realtime runtime (mirrors setTempo/setLoop above).
   ctx.offlineEngine.setParameter(paramId, value);
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.SetParam,
     targetId: paramId,
     sampleTime: -1,
@@ -51,7 +59,7 @@ export function setSoloMute(
 ): boolean {
   const laneIndex = ctx.ensureTrackLane(target);
   ctx.offlineEngine.setSoloMute(laneIndex, solo, mute);
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.SetSoloMute,
     targetId: laneIndex,
     sampleTime: -1,
@@ -170,3 +178,16 @@ export function listParameters(ctx: EngineParameterContext): EngineParameterInfo
   }
   return parameters;
 }
+
+/** Registers a parameter on both the offline mirror and live worklet engine. */
+export function addParameter(ctx: EngineParameterContext, info: EngineParameterInfo): void {
+  ctx.offlineEngine.addParameter(info);
+  ctx.postSync({ type: 'syncParameters', parameters: listParameters(ctx) });
+}
+
+/** Clears registered parameters and their automation lanes on both engines. */
+export function clearParameters(ctx: EngineParameterContext): void {
+  ctx.offlineEngine.clearParameters();
+  ctx.automationLanes.clear();
+  ctx.postSync({ type: 'syncParameters', parameters: [] });
+}