@libraz/libsonare 1.4.1 → 1.5.1

package/src/realtime_engine.ts

@@ -24,9 +24,12 @@ import type {
   WasmEngineTempoSegment,
   WasmEngineTimeSignatureSegment,
   WasmEngineTransportState,
+  WasmExternalMidiEvent,
   WasmRealtimeEngine,
 } from './sonare.js';
 
+export type ExternalMidiEvent = WasmExternalMidiEvent;
+
 export type EngineClip = WasmEngineClip;
 export type ClipPageRequest = WasmClipPageRequest;
 export type EngineParameterInfo = WasmEngineParameterInfo;
@@ -193,6 +196,15 @@ export class RealtimeEngine {
     this.native.setParameterSmoothed(paramId, value, renderFrame);
   }
 
+  /**
+   * Set the default ramp time (ms) for engine-level smoothed parameters —
+   * fader/pan glides, insert-parameter automation, and MIDI-CC mappings. The
+   * default is 20 ms; pass `0` for instant (un-ramped) changes.
+   */
+  setParamSmoothingMs(smoothingMs: number): void {
+    this.native.setParamSmoothingMs(smoothingMs);
+  }
+
   setSoloMute(laneIndex: number, solo: boolean, mute: boolean, renderFrame = -1): void {
     this.native.setSoloMute(laneIndex, solo, mute, renderFrame);
   }
@@ -308,6 +320,39 @@ export class RealtimeEngine {
     return this.native.midiInputPendingCount();
   }
 
+  /**
+   * Route a destination's (track lane's) MIDI to the external output queue
+   * instead of the internal instrument rack, so the track plays an external
+   * device. Clearing it restores internal-synth playback.
+   */
+  setMidiDestinationExternal(destinationId: number, external: boolean): void {
+    this.native.setMidiDestinationExternal(destinationId, external);
+  }
+
+  /**
+   * Enable/disable forwarding MIDI clock + transport (start/continue/stop) to
+   * the external output queue so external gear tracks the transport tempo.
+   */
+  setExternalMidiClockEnabled(enabled: boolean): void {
+    this.native.setExternalMidiClockEnabled(enabled);
+  }
+
+  /** Count of external-MIDI events dropped because the output queue was full. */
+  externalMidiDroppedCount(): number {
+    return this.native.externalMidiDroppedCount();
+  }
+
+  /**
+   * Drain queued external-MIDI events, already lowered to MIDI 1.0 byte
+   * messages ready to write to a Web MIDI output port. Call once per audio
+   * block / animation frame. `maxRecords` caps the number of output events
+   * returned — the shared unit across every surface. Events past the cap stay
+   * queued for the next call (lossless); call again to drain the rest.
+   */
+  drainExternalMidi(maxRecords = 1024): WasmExternalMidiEvent[] {
+    return this.native.drainExternalMidi(maxRecords);
+  }
+
   pushMidiInputNoteOn(
     group: number,
     channel: number,
@@ -377,6 +422,16 @@ export class RealtimeEngine {
     this.native.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
   }
 
+  /**
+   * Queue an immediate (live) MIDI SysEx frame to a MIDI destination. `data` is
+   * the full message including the leading 0xF0 and trailing 0xF7 (1..512
+   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Mirrors
+   * the Node/Python/C-ABI `pushMidiSysex`.
+   */
+  pushMidiSysex(destinationId: number, data: Uint8Array, renderFrame = -1): void {
+    this.native.pushMidiSysex(destinationId, data, renderFrame);
+  }
+
   /**
    * Queue a MIDI panic (all-notes-off) releasing every sounding note at
    * `renderFrame` (-1 = immediate). Mirrors the C-ABI `pushMidiPanic`.
@@ -662,6 +717,45 @@ export class RealtimeEngine {
     this.native.setMasterStripInsertParamByName(insertIndex, paramName, value);
   }
 
+  /** Bus-strip counterpart of {@link setTrackStripInsertParamByName}. */
+  setBusStripInsertParamByName(
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): void {
+    this.native.setBusStripInsertParamByName(busId, insertIndex, paramName, value);
+  }
+
+  /** Bus-strip counterpart of {@link setTrackStripInsertBypassed}. */
+  setBusStripInsertBypassed(
+    busId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass = false,
+  ): void {
+    this.native.setBusStripInsertBypassed(busId, insertIndex, bypassed, resetOnBypass);
+  }
+
+  /**
+   * Resolves a track-lane insert parameter (by its JSON-key name) to the
+   * reserved automation id usable with `setAutomationLane` / `setParameter`.
+   * Returns `-1` when the track, insert, or name is unknown. (The Python binding
+   * raises a `SonareError` for an unknown id where Node/WASM return the `-1`
+   * sentinel.)
+   */
+  resolveTrackInsertAutomationId(trackId: number, insertIndex: number, paramName: string): number {
+    return this.native.resolveTrackInsertAutomationId(trackId, insertIndex, paramName);
+  }
+
+  resolveMasterInsertAutomationId(insertIndex: number, paramName: string): number {
+    return this.native.resolveMasterInsertAutomationId(insertIndex, paramName);
+  }
+
+  resolveBusInsertAutomationId(busId: number, insertIndex: number, paramName: string): number {
+    return this.native.resolveBusInsertAutomationId(busId, insertIndex, paramName);
+  }
+
   /** Sets a track lane strip's pan position in realtime (glitch-free). */
   setTrackStripPan(trackId: number, pan: number): void {
     this.native.setTrackStripPan(trackId, pan);

package/src/sonare.js.d.ts

@@ -26,45 +26,45 @@ export interface WasmKeyCandidateResult {
   correlation: number;
 }
 
-// Flat POD mirror of SonareRealtimeVoiceChangerConfig. Field names match the
-// C ABI / Python POD exactly (snake_case).
+// Flat POD mirror of SonareRealtimeVoiceChangerConfig. Keys are camelCase to
+// match the Node addon getter (the underlying C ABI / Python POD is snake_case).
 export interface WasmRealtimeVoiceChangerPodConfig {
-  input_gain_db: number;
-  output_gain_db: number;
-  wet_mix: number;
-  retune_semitones: number;
-  retune_mix: number;
-  retune_grain_size: number;
-  formant_factor: number;
-  formant_amount: number;
-  formant_body: number;
-  formant_brightness: number;
-  formant_nasal: number;
-  eq_highpass_hz: number;
-  eq_body_db: number;
-  eq_presence_db: number;
-  eq_air_db: number;
-  gate_threshold_db: number;
-  gate_attack_ms: number;
-  gate_release_ms: number;
-  gate_range_db: number;
-  compressor_threshold_db: number;
-  compressor_ratio: number;
-  compressor_attack_ms: number;
-  compressor_release_ms: number;
-  compressor_makeup_gain_db: number;
-  deesser_frequency_hz: number;
-  deesser_threshold_db: number;
-  deesser_ratio: number;
-  deesser_range_db: number;
-  reverb_mix: number;
-  reverb_time_ms: number;
-  reverb_damping: number;
-  reverb_seed: number;
-  limiter_ceiling_db: number;
-  limiter_release_ms: number;
-  limiter_enable_isp_limiter: boolean;
-  limiter_isp_ceiling_dbtp: number;
+  inputGainDb: number;
+  outputGainDb: number;
+  wetMix: number;
+  retuneSemitones: number;
+  retuneMix: number;
+  retuneGrainSize: number;
+  formantFactor: number;
+  formantAmount: number;
+  formantBody: number;
+  formantBrightness: number;
+  formantNasal: number;
+  eqHighpassHz: number;
+  eqBodyDb: number;
+  eqPresenceDb: number;
+  eqAirDb: number;
+  gateThresholdDb: number;
+  gateAttackMs: number;
+  gateReleaseMs: number;
+  gateRangeDb: number;
+  compressorThresholdDb: number;
+  compressorRatio: number;
+  compressorAttackMs: number;
+  compressorReleaseMs: number;
+  compressorMakeupGainDb: number;
+  deesserFrequencyHz: number;
+  deesserThresholdDb: number;
+  deesserRatio: number;
+  deesserRangeDb: number;
+  reverbMix: number;
+  reverbTimeMs: number;
+  reverbDamping: number;
+  reverbSeed: number;
+  limiterCeilingDb: number;
+  limiterReleaseMs: number;
+  limiterEnableIspLimiter: boolean;
+  limiterIspCeilingDbtp: number;
 }
 
 export interface WasmBeatResult {
@@ -194,6 +194,7 @@ export interface WasmStreamConfigDefaults {
   computeSpectral: boolean;
   emitEveryNFrames: number;
   magnitudeDownsample: number;
+  maxPendingFrames: number;
   keyUpdateIntervalSec: number;
   bpmUpdateIntervalSec: number;
   window: number;
@@ -510,6 +511,10 @@ export interface WasmMixMeterSnapshot {
   truePeakDbR: number;
   maxTruePeakDb: number;
   seq: number;
+  channelCount: number;
+  peakDb: number[];
+  rmsDb: number[];
+  truePeakDb: number[];
 }
 
 export interface WasmMixResult {
@@ -783,6 +788,23 @@ export interface WasmEngineTimeSignatureSegment {
   denominator: number;
 }
 
+/**
+ * One external-MIDI event drained from the engine, already lowered to MIDI 1.0
+ * bytes ready to write to a Web MIDI output port.
+ */
+export interface WasmExternalMidiEvent {
+  /**
+   * Originating track lane (Track.midi_destination_id), or the transport
+   * sentinel 0xFFFFFFFF for clock / start / continue / stop bytes meant for
+   * every external port.
+   */
+  destinationId: number;
+  /** Sample position within the producing block at which the event fires. */
+  renderFrame: number;
+  /** MIDI 1.0 status + data bytes (1..3 entries). */
+  bytes: number[];
+}
+
 export interface WasmRealtimeEngine {
   prepare: (
     sampleRate: number,
@@ -792,6 +814,7 @@ export interface WasmRealtimeEngine {
   ) => void;
   setParameter: (paramId: number, value: number, renderFrame: number) => void;
   setParameterSmoothed: (paramId: number, value: number, renderFrame: number) => void;
+  setParamSmoothingMs: (smoothingMs: number) => void;
   setSoloMute: (laneIndex: number, solo: boolean, mute: boolean, renderFrame: number) => void;
   getTransportState: () => WasmEngineTransportState;
   play: (renderFrame: number) => void;
@@ -851,6 +874,25 @@ export interface WasmRealtimeEngine {
     value: number,
   ) => void;
   setMasterStripInsertParamByName: (insertIndex: number, paramName: string, value: number) => void;
+  setBusStripInsertParamByName: (
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ) => void;
+  setBusStripInsertBypassed: (
+    busId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass: boolean,
+  ) => void;
+  resolveTrackInsertAutomationId: (
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+  ) => number;
+  resolveMasterInsertAutomationId: (insertIndex: number, paramName: string) => number;
+  resolveBusInsertAutomationId: (busId: number, insertIndex: number, paramName: string) => number;
   setTrackStripPan: (trackId: number, pan: number) => void;
   setTrackStripPanLaw: (trackId: number, panLaw: number) => void;
   setTrackStripPanMode: (trackId: number, panMode: number) => void;
@@ -936,7 +978,12 @@ export interface WasmRealtimeEngine {
     value: number,
     renderFrame: number,
   ) => void;
+  pushMidiSysex: (destinationId: number, data: Uint8Array, renderFrame: number) => void;
   pushMidiPanic: (renderFrame: number) => void;
+  setMidiDestinationExternal: (destinationId: number, external: boolean) => void;
+  setExternalMidiClockEnabled: (enabled: boolean) => void;
+  externalMidiDroppedCount: () => number;
+  drainExternalMidi: (maxRecords: number) => WasmExternalMidiEvent[];
   clearParameters: () => void;
   process: (channels: Float32Array[]) => Float32Array[];
   prepareChannels: (numChannels: number, maxFrames: number) => void;
@@ -1110,6 +1157,7 @@ export interface SonareModule {
   detectKeyCandidates: (samples: Float32Array, sampleRate: number) => WasmKeyCandidateResult[];
   hasFfmpegSupport: () => boolean;
   version: () => string;
+  abiVersion: () => number;
   engineAbiVersion: () => number;
   voiceChangerAbiVersion: () => number;
   voiceCharacterPresetId: (preset: number) => string | null;
@@ -1337,6 +1385,25 @@ export interface SonareModule {
     voiced?: Float32Array,
     voicedProb?: Float32Array,
   ) => Float32Array;
+  pitchCorrectTimevarying: (
+    samples: Float32Array,
+    sampleRate: number,
+    f0Hz: Float32Array,
+    hopLength: number,
+    options: {
+      mode?: string;
+      targetMidi?: number;
+      scaleRoot?: number;
+      scaleModeMask?: number;
+      referenceMidi?: number;
+      retuneAmount?: number;
+      maxCorrectionSemitones?: number;
+      retuneSpeedMs?: number;
+      vibratoThresholdCents?: number;
+      voiced?: Float32Array;
+      voicedProb?: Float32Array;
+    },
+  ) => Float32Array;
   noteStretch: (
     samples: Float32Array,
     sampleRate: number,
@@ -1567,6 +1634,7 @@ export interface SonareModule {
     fmin: number,
     fmax: number,
     htk: boolean,
+    lifter: number,
   ) => WasmMfccResult;
 
   // Features - Inverse reconstruction
@@ -1792,6 +1860,12 @@ export interface SonareModule {
     hopLength: number,
     nChroma: number,
   ) => WasmChromaResult;
+  chromaCqt: (
+    samples: Float32Array,
+    sampleRate: number,
+    hopLength: number,
+    nChroma: number,
+  ) => WasmChromaResult;
   bassChroma: (
     samples: Float32Array,
     sampleRate: number,
@@ -1876,6 +1950,7 @@ export interface SonareModule {
     winLength: number,
     sampleRate: number,
     hopLength: number,
+    factors?: Float32Array | number[],
   ) => Float32Array;
   lufs: (samples: Float32Array, sampleRate: number) => WasmLufsResult;
   momentaryLufs: (samples: Float32Array, sampleRate: number) => Float32Array;
@@ -1952,6 +2027,7 @@ export interface SonareModule {
     computeSpectral: boolean,
     emitEveryNFrames: number,
     magnitudeDownsample: number,
+    maxPendingFrames: number,
     keyUpdateIntervalSec: number,
     bpmUpdateIntervalSec: number,
     window: number,
@@ -2162,6 +2238,7 @@ export interface WasmMixer {
   vcaGroupCount: () => number;
   toSceneJson: () => string;
   tailSamples: () => number;
+  latencySamples: () => number;
   drainTailStereo: (numSamples: number) => {
     left: Float32Array;
     right: Float32Array;
@@ -2225,6 +2302,8 @@ export interface WasmAnalyzerStats {
   totalFrames: number;
   totalSamples: number;
   durationSeconds: number;
+  pendingFrames: number;
+  droppedOutputFrames: number;
   estimate: WasmProgressiveEstimate;
 }
 

package/src/stream_analyzer.ts

@@ -71,6 +71,7 @@ export class StreamAnalyzer {
       config.computeSpectral ?? defaults.computeSpectral,
       config.emitEveryNFrames ?? defaults.emitEveryNFrames,
       config.magnitudeDownsample ?? defaults.magnitudeDownsample,
+      config.maxPendingFrames ?? defaults.maxPendingFrames,
       config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
       config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
       config.window ?? defaults.window,
@@ -163,6 +164,8 @@ export class StreamAnalyzer {
       totalFrames: s.totalFrames,
       totalSamples: s.totalSamples,
       durationSeconds: s.durationSeconds,
+      pendingFrames: s.pendingFrames,
+      droppedOutputFrames: s.droppedOutputFrames,
       estimate: {
         bpm: s.estimate.bpm,
         bpmConfidence: s.estimate.bpmConfidence,

package/src/stream_types.ts

@@ -64,6 +64,8 @@ export interface AnalyzerStats {
   totalFrames: number;
   totalSamples: number;
   durationSeconds: number;
+  pendingFrames: number;
+  droppedOutputFrames: number;
   estimate: ProgressiveEstimate;
 }
 
@@ -159,6 +161,8 @@ export interface StreamConfig {
   computeSpectral?: boolean;
   emitEveryNFrames?: number;
   magnitudeDownsample?: number;
+  /** Maximum unread frames; overflow drops the oldest frame. */
+  maxPendingFrames?: number;
   keyUpdateIntervalSec?: number;
   bpmUpdateIntervalSec?: number;
   window?: number;

package/src/worklet/engine-automation.ts

@@ -0,0 +1,73 @@
+import type { EngineAutomationPoint, RealtimeEngine } from '../index';
+import { curveCode } from './engine-sync';
+import type { SonareEngineSyncMessage } from './messages';
+
+/**
+ * Collaborator surface the automation-lane helpers need from the owning
+ * {@link SonareEngine}: the lane store they mutate, the offline engine they
+ * mirror into, the sync poster, and the parameter-id resolver.
+ */
+export interface EngineAutomationContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly automationLanes: Map<number, EngineAutomationPoint[]>;
+  postSync(message: SonareEngineSyncMessage): void;
+  resolveParamId(nodeId: string, param: string | number): number;
+}
+
+export function scheduleParam(
+  ctx: EngineAutomationContext,
+  nodeId: string,
+  param: string | number,
+  ppq: number,
+  value: number,
+  curve: number | 'linear' | 'exponential' = 'linear',
+): void {
+  const paramId = ctx.resolveParamId(nodeId, param);
+  const lane = ctx.automationLanes.get(paramId) ?? [];
+  lane.push({ ppq, value, curveToNext: curveCode(curve) });
+  lane.sort((a, b) => a.ppq - b.ppq);
+  ctx.automationLanes.set(paramId, lane);
+  ctx.offlineEngine.setAutomationLane(paramId, lane);
+  // Mirror the lane to the live worklet engine so scheduled automation plays
+  // back in real time, not just in renderOffline(). Lanes can exceed the
+  // fixed-size SAB command record, so they ride an out-of-band 'syncAutomation'
+  // message applied outside process() (like syncClips/syncMarkers).
+  ctx.postSync({ type: 'syncAutomation', paramId, points: lane });
+}
+
+export function addAutomationPoint(
+  ctx: EngineAutomationContext,
+  laneId: string | number,
+  ppq: number,
+  value: number,
+  curve: number | 'linear' | 'exponential' = 'linear',
+): void {
+  scheduleParam(ctx, '', laneId, ppq, value, curve);
+}
+
+/**
+ * Replaces the automation lane for `paramId` with the given breakpoints.
+ *
+ * Unlike scheduleParam (which appends a single point), this sets the whole
+ * lane at once; an empty array clears the lane. The points are defensively
+ * copied and sorted by ppq before being mirrored to the offline engine and
+ * the live worklet engine.
+ *
+ * @param paramId Automation target id (registered parameter or a reserved
+ *   engine mixer target from automationParamId/busAutomationParamId).
+ * @param points Lane breakpoints; order does not matter.
+ */
+export function setAutomationLane(
+  ctx: EngineAutomationContext,
+  paramId: number,
+  points: ReadonlyArray<EngineAutomationPoint>,
+): void {
+  const sorted = points.map((point) => ({ ...point })).sort((a, b) => a.ppq - b.ppq);
+  if (sorted.length === 0) {
+    ctx.automationLanes.delete(paramId);
+  } else {
+    ctx.automationLanes.set(paramId, sorted);
+  }
+  ctx.offlineEngine.setAutomationLane(paramId, sorted);
+  ctx.postSync({ type: 'syncAutomation', paramId, points: sorted });
+}

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

@@ -0,0 +1,80 @@
+import type { EngineCaptureStatus, RealtimeEngine } from '../index';
+import type { SonareRealtimeEngineNode } from './engine-node';
+import { buildCaptureConfig, type CaptureOptions } from './engine-offline';
+import type { SonareEngineSyncCaptureMessage, SonareEngineSyncMessage } from './messages';
+import { SonareEngineCommandType } from './protocol';
+
+type CaptureConfig = Omit<SonareEngineSyncCaptureMessage, 'type'>;
+
+/**
+ * Collaborator surface the capture/record/punch setters need from the owning
+ * {@link SonareEngine}: the offline engine they mirror into, the realtime node
+ * they command and query, the channel count, the out-of-band sync poster, the
+ * capture-config accessor, and the target-id resolver.
+ */
+export interface EngineCaptureContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly realtimeNode: SonareRealtimeEngineNode;
+  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 {
+  const config = buildCaptureConfig(options, ctx.offlineChannelCount);
+  ctx.offlineEngine.setCaptureBuffer(config.channels, config.bufferFrames);
+  ctx.offlineEngine.setCaptureSource(config.source);
+  ctx.offlineEngine.setRecordOffsetSamples(config.recordOffsetSamples);
+  ctx.offlineEngine.setInputMonitor(config.inputMonitor.enabled, config.inputMonitor.gain);
+  ctx.setCaptureConfig(config);
+  ctx.postSync({ type: 'syncCapture', ...config });
+}
+
+export function armRecord(
+  ctx: EngineCaptureContext,
+  trackId: string | number,
+  enabled: boolean,
+): boolean {
+  if (enabled && !ctx.getCaptureConfig()) {
+    throw new Error('Capture buffer is not configured');
+  }
+  ctx.offlineEngine.armCapture(enabled);
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.ArmRecord,
+    targetId: ctx.resolveTargetId(trackId),
+    sampleTime: -1,
+    argInt: enabled ? 1 : 0,
+  });
+}
+
+export function punch(ctx: EngineCaptureContext, inPpq: number, outPpq: number): boolean {
+  const inSample = ctx.offlineEngine.sampleAtPpq(inPpq);
+  const outSample = ctx.offlineEngine.sampleAtPpq(outPpq);
+  ctx.offlineEngine.setCapturePunch(inSample, outSample, true);
+  // Carry BOTH endpoints as already-converted SAMPLES so the realtime engine
+  // agrees with the offline engine. The previous code sent the raw PPQ out
+  // 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({
+    type: SonareEngineCommandType.Punch,
+    sampleTime: -1,
+    argInt: inSample,
+    argFloat: outSample,
+  });
+}
+
+export function captureStatus(ctx: EngineCaptureContext): Promise<EngineCaptureStatus> {
+  return ctx.realtimeNode.requestCaptureStatus();
+}
+
+export function capturedAudio(ctx: EngineCaptureContext): Promise<Float32Array[]> {
+  return ctx.realtimeNode.requestCapturedAudio();
+}
+
+export async function resetCapture(ctx: EngineCaptureContext): Promise<void> {
+  ctx.offlineEngine.resetCapture();
+  await ctx.realtimeNode.requestCaptureReset();
+}

package/src/worklet/engine-clips.ts

@@ -0,0 +1,71 @@
+import type { EngineClip, EngineMidiClipSchedule, RealtimeEngine } from '../index';
+import type { SonareEngineSyncMessage } from './messages';
+
+/**
+ * Collaborator surface the audio/MIDI clip scheduling helpers need from the
+ * owning {@link SonareEngine}: the clip stores they mutate, the offline engine
+ * they mirror into, the sync poster, and the clip-id allocator / lane resolvers.
+ */
+export interface EngineClipContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly clips: Map<number, EngineClip>;
+  readonly midiClips: Map<number, EngineMidiClipSchedule>;
+  allocateClipId(): number;
+  postSync(message: SonareEngineSyncMessage): void;
+  resolveTargetId(target: string | number): number;
+  ensureTrackLane(target: string | number): number;
+}
+
+export function addClip(
+  ctx: EngineClipContext,
+  trackId: string | number,
+  buffer: Float32Array[],
+  startPpq: number,
+  opts: Partial<Omit<EngineClip, 'channels' | 'startPpq'>> = {},
+): number {
+  const id = opts.id ?? ctx.allocateClipId();
+  const clip: EngineClip = {
+    ...opts,
+    id,
+    channels: buffer,
+    startPpq,
+    trackId: ctx.resolveTargetId(trackId),
+  };
+  ctx.ensureTrackLane(trackId);
+  ctx.clips.set(id, clip);
+  syncClipsDelta(ctx, [clip], []);
+  return id;
+}
+
+export function removeClip(ctx: EngineClipContext, clipId: number): void {
+  ctx.clips.delete(clipId);
+  syncClipsDelta(ctx, [], [clipId]);
+}
+
+export function setMidiClips(
+  ctx: EngineClipContext,
+  clips: readonly EngineMidiClipSchedule[],
+): void {
+  ctx.midiClips.clear();
+  for (const clip of clips) {
+    const id = clip.id ?? ctx.allocateClipId();
+    ctx.midiClips.set(id, { ...clip, id, events: clip.events.map((event) => ({ ...event })) });
+  }
+  syncMidiClips(ctx);
+}
+
+function syncClipsDelta(ctx: EngineClipContext, upserts: EngineClip[], removeIds: number[]): void {
+  const clips = Array.from(ctx.clips.values());
+  ctx.offlineEngine.setClips(clips);
+  ctx.postSync({
+    type: 'syncClipsDelta',
+    upserts,
+    removeIds,
+  });
+}
+
+function syncMidiClips(ctx: EngineClipContext): void {
+  const clips = Array.from(ctx.midiClips.values());
+  ctx.offlineEngine.setMidiClips(clips);
+  ctx.postSync({ type: 'syncMidiClips', clips });
+}