@libraz/libsonare 1.5.4 → 1.6.0

package/dist/worklet.d.ts

@@ -1,71 +1,4 @@
-import { WasmEngineTempoSegment, WasmEngineClip, WasmEngineMarker, WasmEngineMetronomeConfig, WasmEngineAutomationPoint, WasmEngineTimeSignatureSegment, WasmEngineCaptureStatus, WasmExternalMidiEvent, WasmEngineTransportState, WasmEngineParameterInfo, WasmEngineGraphSpec, WasmClipPageRequest, WasmEngineProcessWithMonitorResult, WasmEngineBounceOptions, WasmEngineBounceResult, WasmEngineFreezeOptions, WasmEngineFreezeResult, WasmEngineTelemetry, WasmEngineMeterTelemetry, WasmEngineMeterTelemetryWide, WasmEngineScopeTelemetry, SonareModule } from './sonare.js';
-
-type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
-/**
- * Interpolation curve for scheduled automation events
- * (see {@link Mixer.scheduleInsertAutomation}).
- */
-type AutomationCurve = 'linear' | 'exponential' | 'hold' | 's-curve';
-/**
- * Pan law applied when computing left/right gains from a pan position
- * (see {@link Mixer.setPanLaw}). Maps to the underlying integer code.
- */
-type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';
-/** Pre/post-fader send timing (see {@link Mixer.addSend}). */
-type SendTiming = 'preFader' | 'postFader';
-
-/**
- * Equalizer band type (string union mirroring `sonare::mastering::eq::EqBandType`).
- */
-type EqBandType = 'Peak' | 'LowShelf' | 'HighShelf' | 'LowPass' | 'HighPass' | 'BandPass' | 'Notch' | 'TiltShelf' | 'FlatTilt';
-/** Biquad coefficient design mode. */
-type EqCoeffMode = 'Rbj' | 'Vicanek';
-/** Stereo placement for an EQ band. */
-type EqStereoPlacement = 'Stereo' | 'Left' | 'Right' | 'Mid' | 'Side';
-/** Per-band phase behaviour. */
-type EqBandPhase = 'Inherit' | 'ZeroLatency' | 'NaturalPhase' | 'LinearPhase';
-/**
- * Equalizer band configuration accepted by {@link StreamingEqualizer.setBand}.
- *
- * All fields are optional; omitted values fall back to the C++ band defaults
- * (Peak, 1000 Hz, 0 dB gain, Butterworth Q, disabled).
- */
-interface EqBand {
-    type?: EqBandType;
-    frequencyHz?: number;
-    gainDb?: number;
-    q?: number;
-    enabled?: boolean;
-    coeffMode?: EqCoeffMode;
-    slopeDbOct?: number;
-    placement?: EqStereoPlacement;
-    phase?: EqBandPhase;
-    soloed?: boolean;
-    bypassed?: boolean;
-    proportionalQ?: boolean;
-    proportionalQStrength?: number;
-    dynamic?: boolean;
-    thresholdDb?: number;
-    autoThreshold?: boolean;
-    ratio?: number;
-    rangeDb?: number;
-    attackMs?: number;
-    releaseMs?: number;
-    lookaheadMs?: number;
-    externalSidechain?: boolean;
-    sidechainFreqHz?: number;
-    sidechainQ?: number;
-}
-type VoicePresetId = 'neutral-monitor' | 'bright-idol' | 'soft-whisper' | 'deep-narrator' | 'robot-mascot' | 'dark-villain';
-interface RealtimeVoiceChangerPreset {
-    schemaVersion: 1;
-    id?: string;
-    name?: string;
-    description?: string;
-    macros?: Record<string, number>;
-    dsp?: Record<string, unknown>;
-}
-type RealtimeVoiceChangerConfigInput = VoicePresetId | RealtimeVoiceChangerPreset;
+import { WasmExternalMidiEvent, WasmEngineTransportState, WasmEngineTempoSegment, WasmEngineTimeSignatureSegment, WasmEngineParameterInfo, WasmEngineAutomationPoint, WasmEngineMarker, WasmEngineMetronomeConfig, WasmEngineGraphSpec, WasmEngineClip, WasmClipPageRequest, WasmEngineCaptureStatus, WasmEngineProcessWithMonitorResult, WasmEngineBounceOptions, WasmEngineBounceResult, WasmEngineFreezeOptions, WasmEngineFreezeResult, WasmEngineTelemetry, WasmEngineMeterTelemetry, WasmEngineMeterTelemetryWide, WasmEngineScopeTelemetry, SonareModule } from './sonare.js';
 
 declare const SYNTH_ENGINE_MODES: readonly ["default", "subtractive", "fm", "karplus-strong", "modal", "additive", "percussion", "piano", "pipe-organ", "bowed-string", "reed", "brass", "flute", "plucked-string", "vocal", "free-reed"];
 declare const SYNTH_OSC_WAVEFORMS: readonly ["default", "sine", "saw", "square", "triangle", "noise"];
@@ -166,6 +99,135 @@ interface SynthPatch {
     /** Gain-neutral bus saturation [0, 1]. */
     busDrive?: number;
 }
+type ProjectMidiCcBindingKind = 0 | 1 | 2 | 3;
+/** MIDI CC <-> automation binding descriptor used by CC learn/conversion helpers. */
+interface ProjectMidiCcBinding {
+    ccNumber: number;
+    /** MIDI channel 0..15, or 255 for any channel. */
+    channel: number;
+    /** 0 = 7-bit CC, 1 = 14-bit CC, 2 = RPN, 3 = NRPN. */
+    kind: ProjectMidiCcBindingKind;
+    ccLsbNumber?: number;
+    selectorMsb?: number;
+    selectorLsb?: number;
+    paramId: number;
+    minValue: number;
+    maxValue: number;
+}
+
+type PanMode = 'balance' | 'pan' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
+/**
+ * Interpolation curve for scheduled automation events
+ * (see {@link Mixer.scheduleInsertAutomation}).
+ */
+type AutomationCurve = 'linear' | 'exponential' | 'hold' | 's-curve';
+/**
+ * Pan law applied when computing left/right gains from a pan position
+ * (see {@link Mixer.setPanLaw}). On mono strips it changes the centre gain;
+ * on stereo Balance strips it changes only the far-channel taper, while centre
+ * remains unity. Maps to the underlying integer code.
+ */
+type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';
+/** Pre/post-fader send timing (see {@link Mixer.addSend}). */
+type SendTiming = 'preFader' | 'postFader';
+
+/**
+ * Equalizer band type (string union mirroring `sonare::mastering::eq::EqBandType`).
+ */
+type EqBandType = 'Peak' | 'LowShelf' | 'HighShelf' | 'LowPass' | 'HighPass' | 'BandPass' | 'Notch' | 'TiltShelf' | 'FlatTilt';
+/** Biquad coefficient design mode. */
+type EqCoeffMode = 'Rbj' | 'Vicanek';
+/** Stereo placement for an EQ band. */
+type EqStereoPlacement = 'Stereo' | 'Left' | 'Right' | 'Mid' | 'Side';
+/** Per-band phase behaviour. */
+type EqBandPhase = 'Inherit' | 'ZeroLatency' | 'NaturalPhase' | 'LinearPhase';
+/**
+ * Equalizer band configuration accepted by {@link StreamingEqualizer.setBand}.
+ *
+ * All fields are optional; omitted values fall back to the C++ band defaults
+ * (Peak, 1000 Hz, 0 dB gain, Butterworth Q, disabled).
+ */
+interface EqBand {
+    type?: EqBandType;
+    frequencyHz?: number;
+    gainDb?: number;
+    q?: number;
+    enabled?: boolean;
+    coeffMode?: EqCoeffMode;
+    slopeDbOct?: number;
+    placement?: EqStereoPlacement;
+    phase?: EqBandPhase;
+    soloed?: boolean;
+    bypassed?: boolean;
+    proportionalQ?: boolean;
+    proportionalQStrength?: number;
+    dynamic?: boolean;
+    thresholdDb?: number;
+    autoThreshold?: boolean;
+    ratio?: number;
+    rangeDb?: number;
+    attackMs?: number;
+    releaseMs?: number;
+    lookaheadMs?: number;
+    externalSidechain?: boolean;
+    sidechainFreqHz?: number;
+    sidechainQ?: number;
+}
+type VoicePresetId = 'neutral-monitor' | 'bright-idol' | 'soft-whisper' | 'deep-narrator' | 'robot-mascot' | 'dark-villain';
+interface RealtimeVoiceChangerPreset {
+    schemaVersion: 1;
+    id?: string;
+    name?: string;
+    description?: string;
+    macros?: Record<string, number>;
+    dsp?: Record<string, unknown>;
+}
+type RealtimeVoiceChangerConfigInput = VoicePresetId | RealtimeVoiceChangerPreset;
+/**
+ * Flat (POD) realtime voice-changer configuration. Keys are camelCase to match
+ * the Node addon getter, so a preset config reads identically across both JS
+ * surfaces (the underlying C ABI / Python POD uses the snake_case equivalents).
+ */
+interface RealtimeVoiceChangerPodConfig {
+    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;
+    /** Non-zero enables the 4x-oversampled inter-sample-peak limiter (default enabled). */
+    limiterEnableIspLimiter: boolean;
+    /** True-peak ceiling in dBTP applied by the ISP limiter (default -1.0). */
+    limiterIspCeilingDbtp: number;
+}
 
 type EngineClip = WasmEngineClip;
 type ClipPageRequest = WasmClipPageRequest;
@@ -175,6 +237,7 @@ type EngineMarker = WasmEngineMarker;
 type EngineMetronomeConfig = WasmEngineMetronomeConfig;
 type EngineGraphSpec = WasmEngineGraphSpec;
 type EngineCaptureStatus = WasmEngineCaptureStatus;
+type EngineCaptureSource = EngineCaptureStatus['source'] | number;
 type EngineBounceOptions = WasmEngineBounceOptions;
 type EngineBounceResult = WasmEngineBounceResult;
 type EngineFreezeOptions = WasmEngineFreezeOptions;
@@ -254,8 +317,8 @@ interface MidiCcBindOptions {
 }
 declare class RealtimeEngine {
     private native;
-    constructor(sampleRate?: number, maxBlockSize?: number, commandCapacity?: number, telemetryCapacity?: number);
-    prepare(sampleRate: number, maxBlockSize: number, commandCapacity?: number, telemetryCapacity?: number): void;
+    constructor(sampleRate?: number, maxBlockSize?: number, commandCapacity?: number, telemetryCapacity?: number, maxChannels?: number);
+    prepare(sampleRate: number, maxBlockSize: number, commandCapacity?: number, telemetryCapacity?: number, maxChannels?: number): void;
     /** Queue a sample-accurate parameter change (engine kSetParam). */
     setParameter(paramId: number, value: number, renderFrame?: number): void;
     /** Queue a smoothed parameter change (engine kSetParamSmoothed). */
@@ -301,6 +364,7 @@ declare class RealtimeEngine {
         destinationId?: number;
         gain?: number;
         polyphony?: number;
+        preferModelForModeledFamilies?: boolean;
     }, destinationId?: number): void;
     clearMidiInstrument(destinationId?: number): void;
     midiInstrumentCount(): number;
@@ -310,6 +374,8 @@ declare class RealtimeEngine {
      * mapped into [minValue, maxValue] for `paramId`.
      */
     bindMidiCc(channel: number, controller: number, paramId: number, options?: MidiCcBindOptions): void;
+    /** Bind a 7/14-bit CC, RPN, or NRPN descriptor to a live parameter. */
+    bindMidiCcBinding(binding: ProjectMidiCcBinding): void;
     clearMidiCcBindings(): void;
     midiCcBindingCount(): number;
     /** Install/replace a live non-destructive MIDI-FX insert for one destination. */
@@ -332,6 +398,7 @@ declare class RealtimeEngine {
     setExternalMidiClockEnabled(enabled: boolean): void;
     /** Count of external-MIDI events dropped because the output queue was full. */
     externalMidiDroppedCount(): number;
+    externalMidiPendingCount(): number;
     /**
      * 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
@@ -340,6 +407,13 @@ declare class RealtimeEngine {
      * queued for the next call (lossless); call again to drain the rest.
      */
     drainExternalMidi(maxRecords?: number): WasmExternalMidiEvent[];
+    /** Scalar, allocation-free external-MIDI drain for AudioWorklet SAB output. */
+    popExternalMidiToScratch(): boolean;
+    externalMidiScratchDestinationId(): number;
+    externalMidiScratchRenderFrame(): number;
+    externalMidiScratchByteWord(): number;
+    externalMidiScratchByteCount(): number;
+    consumeExternalMidiScratch(): void;
     pushMidiInputNoteOn(group: number, channel: number, note: number, velocity: number, portTimeSamples?: number): void;
     pushMidiInputNoteOff(group: number, channel: number, note: number, velocity?: number, portTimeSamples?: number): void;
     pushMidiInputCc(group: number, channel: number, controller: number, value: number, portTimeSamples?: number): void;
@@ -352,6 +426,8 @@ declare class RealtimeEngine {
      * immediate. Mirrors the Node/Python/C-ABI `pushMidiCc`.
      */
     pushMidiCc(destinationId: number, group: number, channel: number, controller: number, value: number, renderFrame?: number): void;
+    /** Queue one immediate MIDI 1.0 channel-voice UMP word for a destination. */
+    pushMidiUmp(destinationId: number, word0: number, renderFrame?: number): void;
     /**
      * 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
@@ -381,7 +457,10 @@ declare class RealtimeEngine {
      * settled values instead of ramping in from defaults.
      */
     settleParameters(): void;
+    /** Drains queued commands on an offline/control-only engine immediately. */
+    flushControlCommands(): void;
     seekPpq(ppq: number, renderFrame?: number): void;
+    /** Set a finite tempo in the range (0, 100000] BPM. */
     setTempo(bpm: number): void;
     setTempoSegments(segments: readonly EngineTempoSegment[]): void;
     setTimeSignature(numerator: number, denominator: number): void;
@@ -400,6 +479,7 @@ declare class RealtimeEngine {
     marker(id: number): EngineMarker;
     seekMarker(markerId: number, renderFrame?: number): void;
     setLoopFromMarkers(startMarkerId: number, endMarkerId: number): void;
+    /** Set a metronome config; click lengths are limited to one second. */
     setMetronome(config: EngineMetronomeConfig): void;
     metronome(): Required<EngineMetronomeConfig>;
     countInEndSample(startSample: number, bars: number): number;
@@ -471,15 +551,29 @@ declare class RealtimeEngine {
     clearClipPage(providerId: number, pageIndex: number): void;
     destroyClipPageProvider(providerId: number): void;
     popClipPageRequest(): ClipPageRequest | null;
+    /**
+     * Moves one native request into the binding's persistent scalar scratch.
+     * This avoids creating an embind JS object in AudioWorklet process().
+     */
+    popClipPageRequestToScratch(): boolean;
+    clipPageRequestScratchClipId(): number;
+    clipPageRequestScratchSample(): number;
+    /** Cumulative page misses dropped because the native bounded request queue was full. */
+    clipPageRequestOverflowCount(): number;
     setCaptureBuffer(numChannels: number, capacityFrames: number): void;
     armCapture(armed?: boolean): void;
     setCapturePunch(startSample: number, endSample: number, enabled?: boolean): void;
-    setCaptureSource(source: EngineCaptureStatus['source']): void;
+    setCaptureSource(source: EngineCaptureSource): void;
+    /** Positive values delay capture relative to the punch window. */
     setRecordOffsetSamples(offsetSamples: number): void;
     setInputMonitor(enabled: boolean, gain?: number): void;
     resetCapture(): void;
     captureStatus(): EngineCaptureStatus;
     capturedAudio(): Float32Array[];
+    /**
+     * Renders in place, adding engine output to `channels`. Zero each plane first
+     * when it contains no upstream input.
+     */
     process(channels: Float32Array[]): Float32Array[];
     /**
      * Allocates persistent per-channel WASM-heap scratch for the zero-copy
@@ -496,6 +590,7 @@ declare class RealtimeEngine {
     getChannelBuffer(channel: number, numFrames: number): Float32Array;
     /**
      * Runs the engine in place over the prepared per-channel scratch buffers.
+     * Zero each active span first when it contains no upstream input.
      * Allocation-free: safe to call on the AudioWorklet render thread after
      * `prepareChannels`.
      */
@@ -505,6 +600,18 @@ declare class RealtimeEngine {
     bounceOffline(options: EngineBounceOptions): EngineBounceResult;
     freezeOffline(options: EngineFreezeOptions): EngineFreezeResult;
     drainTelemetry(maxRecords?: number): EngineTelemetry[];
+    popTelemetryToScratch(): boolean;
+    telemetryScratchType(): number;
+    telemetryScratchError(): number;
+    telemetryScratchRenderFrame(): number;
+    telemetryScratchTimelineSample(): number;
+    telemetryScratchAudibleTimelineSample(): number;
+    telemetryScratchGraphLatencySamplesQ8(): number;
+    telemetryScratchValue(): number;
+    popMeterTelemetryToScratch(): boolean;
+    meterScratchTargetId(): number;
+    meterScratchRenderFrame(): number;
+    meterScratchValue(field: number): number;
     drainMeterTelemetry(maxRecords?: number): EngineMeterTelemetry[];
     /**
      * Drains pending meter telemetry as per-plane (wide) records for a surround
@@ -524,6 +631,14 @@ declare class RealtimeEngine {
     configureScopeTelemetry(intervalFrames: number, bandCount: number): number;
     /** Drains pending spectrum + vectorscope snapshots (per mix target). */
     drainScopeTelemetry(maxRecords?: number): EngineScopeTelemetry[];
+    popScopeTelemetryToScratch(): boolean;
+    scopeScratchTargetId(): number;
+    scopeScratchRenderFrame(): number;
+    scopeScratchBandCount(): number;
+    scopeScratchBand(index: number): number;
+    scopeScratchPointCount(): number;
+    scopeScratchPointLeft(index: number): number;
+    scopeScratchPointRight(index: number): number;
     destroy(): void;
 }
 declare class ClipPageProvider {
@@ -536,6 +651,161 @@ declare class ClipPageProvider {
     destroy(): void;
 }
 
+interface OpfsClipPageProviderOptions {
+    path: string;
+    numChannels: number;
+    numSamples: number;
+    pageFrames: number;
+    dataOffsetBytes?: number;
+    worker?: Worker;
+    terminateWorkerOnClose?: boolean;
+    /** Internal bridge hook used to mirror a supplied page into an AudioWorklet. */
+    onPageSupplied?: (pageIndex: number, channels: Float32Array[]) => void;
+    /** Internal bridge hook used to mirror an eviction into an AudioWorklet. */
+    onPageCleared?: (pageIndex: number) => void;
+    /** Internal bridge hook called after the local provider is destroyed. */
+    onClose?: () => void;
+}
+interface OpfsClipPageProviderBinding {
+    provider: ClipPageProvider;
+    supplyPage(pageIndex: number): Promise<boolean>;
+    supplyRequest(request: ClipPageRequest): Promise<boolean>;
+    /** Evict one resident page from every configured consumer. */
+    clearPage?(pageIndex: number): void;
+    close(): void;
+}
+
+/**
+ * Minimal engine surface the streamer drives. {@link RealtimeEngine} satisfies
+ * this structurally; tests can supply a lightweight stand-in.
+ */
+interface ClipPageStreamerEngine {
+    /** Drain one pending audio-thread page-miss request, or `null` when empty. */
+    popClipPageRequest(): ClipPageStreamerRequest | null;
+}
+/**
+ * A page miss reported by either a direct engine (`sample`) or the worklet
+ * bridge (`pageIndex`). Exactly one position form is required.
+ */
+interface ClipPageStreamerRequest {
+    clipId: number;
+    sample?: number;
+    pageIndex?: number;
+}
+/** A paged clip the streamer keeps fed from its backing store. */
+interface ClipPageStreamSource {
+    /** Clip schedule id passed to `setClips` (matches {@link ClipPageRequest.clipId}). */
+    clipId: number;
+    /** OPFS-backed page provider binding for this clip. */
+    binding: OpfsClipPageProviderBinding;
+    /** Page size in frames (must equal the provider's `pageFrames`). */
+    pageFrames: number;
+    /** Total sample count of the clip source. */
+    numSamples: number;
+}
+interface ClipPageStreamerOptions {
+    /**
+     * Pages to prefetch ahead of the page a miss was reported for. Larger values
+     * hide fetch latency at the cost of more resident memory. Default 2.
+     */
+    readAheadPages?: number;
+    /**
+     * Pages to retain behind the playback frontier before eviction, so a small
+     * backward seek does not immediately miss. Default 1.
+     */
+    retainBehindPages?: number;
+    /**
+     * Upper bound on requests drained per {@link ClipPageStreamer.pump} call, so a
+     * burst of misses cannot spin unbounded. Default 256.
+     */
+    maxRequestsPerPump?: number;
+}
+/**
+ * Keeps OPFS-paged clips fed within a bounded sliding window around the live
+ * playback position, so a multitrack arrangement never holds its full PCM in
+ * WASM memory.
+ *
+ * The audio thread reports a page miss whenever the {@link ClipPlayer} reads a
+ * sample whose page is not resident. {@link pump} drains those requests, fetches
+ * the missing page plus a read-ahead window from each clip's backing store, and
+ * evicts pages that fall outside the window via the provider's `clear`. The
+ * resident set per clip is therefore bounded to
+ * `retainBehindPages + readAheadPages + 1` pages regardless of clip length.
+ *
+ * Call {@link pump} on a cadence that keeps up with playback — typically once
+ * per animation frame or per worklet control tick on the main/control thread
+ * (never the audio thread; fetches are asynchronous).
+ */
+declare class ClipPageStreamer {
+    private readonly engine;
+    private readonly readAheadPages;
+    private readonly retainBehindPages;
+    private readonly maxRequestsPerPump;
+    private readonly sources;
+    private closed;
+    constructor(engine: ClipPageStreamerEngine, options?: ClipPageStreamerOptions);
+    /**
+     * Register a paged clip. Pages already supplied to the provider before
+     * registration (for example a primed first page) should be passed in
+     * `initialResidentPages` so they participate in eviction.
+     */
+    addSource(source: ClipPageStreamSource, initialResidentPages?: Iterable<number>): void;
+    /** Stop tracking a clip. Does not close its binding (the caller owns that). */
+    removeSource(clipId: number): void;
+    /**
+     * Explicitly start a new playback generation after a host seek/loop. Resident
+     * pages are evicted and any older in-flight fetch is cleared when it settles.
+     * The next miss establishes the new bounded window.
+     */
+    resetSource(clipId: number): void;
+    /**
+     * Drain pending page-miss requests, fetch the missing pages plus their
+     * read-ahead window, and evict out-of-window pages. Resolves once this round's
+     * fetches settle. Concurrent fetches are serialized inside each binding.
+     */
+    pump(): Promise<void>;
+    /** Close every registered clip's binding and stop tracking. */
+    close(): void;
+    private serviceFrontier;
+    private resetState;
+    private clearPage;
+}
+interface OpfsClipStreamOptions extends OpfsClipPageProviderOptions {
+    /** Clip schedule id used in `setClips` (matches the page-miss request clipId). */
+    clipId: number;
+    /**
+     * Leading pages fetched synchronously before returning, so playback can start
+     * without an immediate miss. Default 1.
+     */
+    primePages?: number;
+}
+interface OpfsClipStream {
+    binding: OpfsClipPageProviderBinding;
+    /** Pass as `addClip`'s buffer argument to schedule the streaming clip. */
+    provider: ClipPageProvider;
+}
+/** Structural seam implemented by the AudioWorklet-backed `SonareEngine`. */
+interface WorkletOpfsClipStreamHost {
+    attachOpfsClipStream(options: OpfsClipStreamOptions): Promise<OpfsClipStream>;
+}
+/**
+ * One-call wiring of an OPFS-backed streaming clip: creates the page provider,
+ * primes the leading pages, and registers it with `streamer` so later misses are
+ * serviced within the bounded window. Returns the binding (for `close`) and the
+ * provider to schedule via `addClip(trackId, provider, startPpq, { id: clipId })`.
+ *
+ * @param streamer Shared streamer pumped on the control thread.
+ * @param engine Engine the provider is created on (the same one `streamer` drives).
+ * @param options Provider options plus `clipId` and optional `primePages`.
+ */
+declare function attachOpfsClipStream(streamer: ClipPageStreamer, engine: RealtimeEngine, options: OpfsClipStreamOptions): Promise<OpfsClipStream>;
+/**
+ * Worklet overload: delegates to `SonareEngine.attachOpfsClipStream`, which
+ * creates the remote provider and drives this same sliding-window policy from
+ * worklet page-miss messages.
+ */
+declare function attachOpfsClipStream(engine: WorkletOpfsClipStreamHost, options: OpfsClipStreamOptions): Promise<OpfsClipStream>;
+
 /**
  * sonare - Audio Analysis Library
  *
@@ -610,6 +880,10 @@ declare function decodeFrame(lo: number, hi: number): number;
 declare const SONARE_ENGINE_RING_HEADER_INTS = 5;
 declare const SONARE_ENGINE_COMMAND_RECORD_BYTES = 32;
 declare const SONARE_ENGINE_TELEMETRY_RECORD_BYTES = 48;
+declare const SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS = 5;
+declare const SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S = 2;
+declare const SONARE_EXTERNAL_MIDI_RING_HEADER_INTS = 5;
+declare const SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S = 4;
 declare enum SonareEngineCommandType {
     SetParam = 0,
     SetParamSmoothed = 1,
@@ -651,7 +925,10 @@ declare enum SonareEngineTelemetryError {
     SmoothedParameterCapacity = 13,
     CommandBacklogDeferred = 14,
     ClipPageUnderrun = 15,
-    InsertAutomationOverflow = 16
+    InsertAutomationOverflow = 16,
+    MidiClockOverflow = 17,
+    MetronomeOverflow = 18,
+    InvalidCommand = 19
 }
 interface SonareMeterRingBuffer {
     sharedBuffer: SharedArrayBuffer;
@@ -702,6 +979,27 @@ interface SonareScopeRingReadResult {
     nextReadIndex: number;
     scopes: SonareWorkletScopeSnapshot[];
 }
+interface SonareExternalMidiRingEvent {
+    destinationId: number;
+    renderFrame: number;
+    byteWord: number;
+    byteCount: number;
+}
+interface SonareExternalMidiRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    records: Uint32Array;
+    capacity: number;
+}
+interface SharedExternalMidiRingWriter {
+    header: Int32Array;
+    records: Uint32Array;
+    capacity: number;
+}
+interface SonareExternalMidiRingReadResult {
+    events: SonareExternalMidiRingEvent[];
+    dropped: number;
+}
 interface SonareEngineCommandRecord {
     type: SonareEngineCommandType | number;
     targetId?: number;
@@ -734,6 +1032,26 @@ interface SonareEngineTelemetryRingReadResult {
     nextReadIndex: number;
     telemetry: SonareEngineTelemetryRecord[];
 }
+interface SonareClipPageRequest {
+    clipId: number;
+    pageIndex: number;
+}
+interface SonareClipPageRequestRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    records: Uint32Array;
+    capacity: number;
+}
+interface SharedClipPageRequestRingWriter {
+    header: Int32Array;
+    records: Uint32Array;
+    capacity: number;
+}
+interface SonareClipPageRequestRingReadResult {
+    requests: SonareClipPageRequest[];
+    /** Cumulative uint32 drop count for native and SAB-ring overflows. */
+    dropped: number;
+}
 declare function sonareMeterRingBufferByteLength(capacity: number): number;
 declare function createSonareMeterRingBuffer(capacity?: number): SonareMeterRingBuffer;
 declare function readSonareMeterRingBuffer(ring: SonareMeterRingBuffer, readIndex?: number): SonareMeterRingReadResult;
@@ -745,6 +1063,22 @@ declare function createSonareScopeRingBuffer(capacity?: number, bands?: number,
 declare function readSonareScopeRingBuffer(ring: SonareScopeRingBuffer, readIndex?: number): SonareScopeRingReadResult;
 declare function sonareEngineCommandRingBufferByteLength(capacity: number): number;
 declare function sonareEngineTelemetryRingBufferByteLength(capacity: number): number;
+declare function sonareClipPageRequestRingBufferByteLength(capacity: number): number;
+declare function sonareExternalMidiRingBufferByteLength(capacity: number): number;
+declare function createSonareExternalMidiRingBuffer(capacity?: number): SonareExternalMidiRingBuffer;
+/** Write one lowered MIDI-1 event without allocations from the audio worklet. */
+declare function pushSonareExternalMidiRingBuffer(ring: SharedExternalMidiRingWriter, destinationId: number, renderFrame: number, byteWord: number, byteCount: number): boolean;
+/** Main-thread drain. It is intentionally the only place MIDI byte arrays are built. */
+declare function readSonareExternalMidiRingBuffer(ring: SonareExternalMidiRingBuffer): SonareExternalMidiRingReadResult;
+declare function createSonareClipPageRequestRingBuffer(capacity?: number): SonareClipPageRequestRingBuffer;
+/**
+ * Writes one request without allocating. Invalid uint32 coordinates and a full
+ * ring are counted as drops so the main thread can surface a bounded-loss
+ * diagnostic without receiving a worklet postMessage.
+ */
+declare function pushSonareClipPageRequestRingBuffer(ring: SharedClipPageRequestRingWriter, clipId: number, pageIndex: number): boolean;
+/** Drains the SPSC request ring on the main thread. Object creation is here, never in process(). */
+declare function readSonareClipPageRequestRingBuffer(ring: SonareClipPageRequestRingBuffer): SonareClipPageRequestRingReadResult;
 declare function createSonareEngineCommandRingBuffer(capacity?: number): SonareEngineCommandRingBuffer;
 declare function createSonareEngineTelemetryRingBuffer(capacity?: number): SonareEngineTelemetryRingBuffer;
 declare function pushSonareEngineCommandRingBuffer(ring: SonareEngineCommandRingBuffer, command: SonareEngineCommandRecord): boolean;
@@ -783,6 +1117,16 @@ interface SonareRealtimeEngineWorkletProcessorOptions {
     scopeBands?: number;
     scopeSharedBuffer?: SharedArrayBuffer;
     scopeRingCapacity?: number;
+    /**
+     * Lock-free SPSC queue for clip-page cache misses. Supplying this is required
+     * for realtime-safe OPFS streaming: it avoids both embind object creation and
+     * postMessage structured cloning from AudioWorklet process().
+     */
+    clipPageRequestSharedBuffer?: SharedArrayBuffer;
+    clipPageRequestRingCapacity?: number;
+    /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
+    externalMidiSharedBuffer?: SharedArrayBuffer;
+    externalMidiRingCapacity?: number;
 }
 interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
     preset?: RealtimeVoiceChangerConfigInput;
@@ -792,7 +1136,8 @@ interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
 }
 interface SonareRealtimeVoiceChangerSetConfigMessage {
     type: 'setConfig';
-    preset: RealtimeVoiceChangerConfigInput;
+    /** Pre-normalized by the main thread; never JSON parsed in the worklet. */
+    config: RealtimeVoiceChangerPodConfig;
 }
 interface SonareRealtimeVoiceChangerResetMessage {
     type: 'reset';
@@ -807,6 +1152,10 @@ interface SonareRealtimeEngineNodeCapabilities {
     sharedArrayBuffer: boolean;
     atomics: boolean;
     audioWorklet: boolean;
+    /** True only when clip-page misses use the bounded SAB ring. */
+    clipPageRequestsRealtimeSafe: boolean;
+    /** True when external MIDI uses the SAB output ring rather than postMessage. */
+    externalMidiRealtimeSafe: boolean;
     engineAbiVersion?: number;
     expectedEngineAbiVersion?: number;
     abiCompatible?: boolean;
@@ -863,9 +1212,15 @@ interface SonareWorkletExternalMidiMessage {
     type: 'externalMidi';
     events: SonareWorkletExternalMidiEvent[];
 }
-type SonareWorkletTransportMessage = SonareWorkletMeterSnapshot | SonareWorkletSpectrumSnapshot | SonareWorkletExternalMidiMessage | SonareEngineTelemetryRecord;
+/** A control-plane sync message that the worklet rejected without crashing. */
+interface SonareEngineSyncErrorMessage {
+    type: 'syncError';
+    syncType: SonareEngineSyncMessage['type'];
+    message: string;
+}
+type SonareWorkletTransportMessage = SonareWorkletMeterSnapshot | SonareWorkletSpectrumSnapshot | SonareWorkletExternalMidiMessage | SonareEngineClipPageRequestMessage | SonareEngineTelemetryRecord;
 interface WorkletTransport {
-    postMessage?: (message: SonareWorkletTransportMessage | SonareEngineCaptureResponseMessage | SonareEngineTransportResponseMessage, transfer?: Transferable[]) => void;
+    postMessage?: (message: SonareWorkletTransportMessage | SonareEngineCaptureResponseMessage | SonareEngineTransportResponseMessage | SonareEngineSyncErrorMessage, transfer?: Transferable[]) => void;
     onMeter?: (meter: SonareWorkletMeterSnapshot) => void;
     onSpectrum?: (spectrum: SonareWorkletSpectrumSnapshot) => void;
 }
@@ -882,7 +1237,8 @@ interface SonareEngineSyncClipsDeltaMessage {
 interface SonareEngineSyncClipPageProviderMessage {
     type: 'syncClipPageProvider';
     clipId: number;
-    clip: EngineClip;
+    /** Omitted when an OPFS stream is primed before its clip is scheduled. */
+    clip?: EngineClip;
     numChannels: number;
     numSamples: number;
     pageFrames: number;
@@ -894,10 +1250,41 @@ interface SonareEngineSyncClipPageMessage {
     pageIndex: number;
     channels: Float32Array[];
 }
+/** Evicts one page after the main-thread sliding window advances. */
+interface SonareEngineSyncClipPageClearMessage {
+    type: 'syncClipPageClear';
+    clipId: number;
+    pageIndex: number;
+}
+/** Releases a provider whose clip was removed or whose stream was closed. */
+interface SonareEngineSyncClipPageDestroyMessage {
+    type: 'syncClipPageDestroy';
+    clipId: number;
+}
 /** Makes a fully supplied paged clip visible to the audio engine. */
 interface SonareEngineSyncClipPageCommitMessage {
     type: 'syncClipPageCommit';
     clipId: number;
+    /**
+     * Clip schedule to publish with a provider that was primed before its
+     * schedule was known. The original pre-baked push path supplies it on the
+     * provider message instead.
+     */
+    clip?: EngineClip;
+}
+/**
+ * A bounded batch of page misses emitted by the AudioWorklet. The main thread
+ * resolves these from OPFS and responds with `syncClipPage`; a missing page is
+ * silent until that response arrives.
+ */
+interface SonareEngineClipPageRequestMessage {
+    type: 'clipPageRequest';
+    requests: Array<{
+        clipId: number;
+        pageIndex: number;
+    }>;
+    /** Number of misses dropped because a bounded native or SAB request queue was full. */
+    dropped?: number;
 }
 interface SonareEngineSyncMidiClipsMessage {
     type: 'syncMidiClips';
@@ -916,6 +1303,11 @@ interface SonareEngineSyncAutomationMessage {
     paramId: number;
     points: EngineAutomationPoint[];
 }
+/** Replaces the live engine's registered custom-parameter set. */
+interface SonareEngineSyncParametersMessage {
+    type: 'syncParameters';
+    parameters: EngineParameterInfo[];
+}
 interface SonareEngineSyncTempoMessage {
     type: 'syncTempo';
     bpm: number;
@@ -1046,6 +1438,7 @@ interface SonareEngineSyncSf2InstrumentMessage {
         destinationId?: number;
         gain?: number;
         polyphony?: number;
+        preferModelForModeledFamilies?: boolean;
     };
 }
 interface SonareEngineSyncLoadSoundFontMessage {
@@ -1076,6 +1469,12 @@ interface SonareEngineSyncMidiCcMessage {
     value: number;
     renderFrame: number;
 }
+interface SonareEngineSyncMidiUmpMessage {
+    type: 'syncMidiUmp';
+    destinationId: number;
+    word0: number;
+    renderFrame: number;
+}
 interface SonareEngineSyncMidiSysexMessage {
     type: 'syncMidiSysex';
     destinationId: number;
@@ -1095,7 +1494,31 @@ interface SonareEngineSyncExternalMidiClockMessage {
     type: 'syncExternalMidiClock';
     enabled: boolean;
 }
-type SonareEngineSyncMessage = SonareEngineSyncClipsMessage | SonareEngineSyncClipsDeltaMessage | SonareEngineSyncClipPageProviderMessage | SonareEngineSyncClipPageMessage | SonareEngineSyncClipPageCommitMessage | SonareEngineSyncMidiClipsMessage | SonareEngineSyncMarkersMessage | SonareEngineSyncMetronomeMessage | SonareEngineSyncAutomationMessage | SonareEngineSyncTempoMessage | SonareEngineSyncMixerMessage | SonareEngineSyncCaptureMessage | SonareEngineSyncTrackStripEqBandMessage | SonareEngineSyncMasterStripEqBandMessage | SonareEngineSyncTrackStripInsertBypassedMessage | SonareEngineSyncMasterStripInsertBypassedMessage | SonareEngineSyncTrackStripInsertParamByNameMessage | SonareEngineSyncMasterStripInsertParamByNameMessage | SonareEngineSyncBusStripInsertParamByNameMessage | SonareEngineSyncTrackStripPanMessage | SonareEngineSyncTrackStripPanLawMessage | SonareEngineSyncTrackStripPanModeMessage | SonareEngineSyncTrackStripDualPanMessage | SonareEngineSyncTrackStripChannelDelaySamplesMessage | SonareEngineSyncBuiltinInstrumentMessage | SonareEngineSyncSynthInstrumentMessage | SonareEngineSyncSf2InstrumentMessage | SonareEngineSyncLoadSoundFontMessage | SonareEngineSyncMidiFxMessage | SonareEngineSyncMidiNoteMessage | SonareEngineSyncMidiCcMessage | SonareEngineSyncMidiSysexMessage | SonareEngineSyncMidiPanicMessage | SonareEngineSyncMidiDestinationExternalMessage | SonareEngineSyncExternalMidiClockMessage;
+interface SonareEngineSyncMidiInputSourceMessage {
+    type: 'syncMidiInputSource' | 'syncClearMidiInputSource';
+    destinationId?: number;
+}
+interface SonareEngineSyncMidiCcBindingMessage {
+    type: 'syncMidiCcBinding';
+    channel: number;
+    controller: number;
+    paramId: number;
+    minValue: number;
+    maxValue: number;
+}
+interface SonareEngineSyncMidiInputEventMessage {
+    type: 'syncMidiInputNoteOn' | 'syncMidiInputNoteOff' | 'syncMidiInputCc';
+    group: number;
+    channel: number;
+    data0: number;
+    data1: number;
+    portTimeSamples: number;
+}
+/** Releases the realtime engine and all worklet-owned clip buffers. */
+interface SonareEngineDestroyMessage {
+    type: 'destroy';
+}
+type SonareEngineSyncMessage = SonareEngineSyncClipsMessage | SonareEngineSyncClipsDeltaMessage | SonareEngineSyncClipPageProviderMessage | SonareEngineSyncClipPageMessage | SonareEngineSyncClipPageClearMessage | SonareEngineSyncClipPageCommitMessage | SonareEngineSyncClipPageDestroyMessage | SonareEngineSyncMidiClipsMessage | SonareEngineSyncMarkersMessage | SonareEngineSyncMetronomeMessage | SonareEngineSyncAutomationMessage | SonareEngineSyncParametersMessage | SonareEngineSyncTempoMessage | SonareEngineSyncMixerMessage | SonareEngineSyncCaptureMessage | SonareEngineSyncTrackStripEqBandMessage | SonareEngineSyncMasterStripEqBandMessage | SonareEngineSyncTrackStripInsertBypassedMessage | SonareEngineSyncMasterStripInsertBypassedMessage | SonareEngineSyncTrackStripInsertParamByNameMessage | SonareEngineSyncMasterStripInsertParamByNameMessage | SonareEngineSyncBusStripInsertParamByNameMessage | SonareEngineSyncTrackStripPanMessage | SonareEngineSyncTrackStripPanLawMessage | SonareEngineSyncTrackStripPanModeMessage | SonareEngineSyncTrackStripDualPanMessage | SonareEngineSyncTrackStripChannelDelaySamplesMessage | SonareEngineSyncBuiltinInstrumentMessage | SonareEngineSyncSynthInstrumentMessage | SonareEngineSyncSf2InstrumentMessage | SonareEngineSyncLoadSoundFontMessage | SonareEngineSyncMidiFxMessage | SonareEngineSyncMidiNoteMessage | SonareEngineSyncMidiCcMessage | SonareEngineSyncMidiUmpMessage | SonareEngineSyncMidiSysexMessage | SonareEngineSyncMidiPanicMessage | SonareEngineSyncMidiDestinationExternalMessage | SonareEngineSyncExternalMidiClockMessage | SonareEngineSyncMidiInputSourceMessage | SonareEngineSyncMidiCcBindingMessage | SonareEngineSyncMidiInputEventMessage | SonareEngineDestroyMessage;
 interface SonareEngineCaptureRequestMessage {
     type: 'captureRequest';
     requestId: number;
@@ -1172,6 +1595,12 @@ declare class SonareEngine {
     private nextMarkerId;
     private transportPlaying;
     private readonly pendingInstrumentSync;
+    private readonly workletClipPageRequests;
+    private readonly workletPageProviderClipIds;
+    private workletClipStreamer;
+    private workletClipPump;
+    private workletClipPagePollTimer;
+    private unsubscribeWorkletClipRequests;
     private destroyed;
     private constructor();
     static create(context: BaseAudioContext, options?: SonareEngineOptions): Promise<SonareEngine>;
@@ -1253,6 +1682,10 @@ declare class SonareEngine {
      */
     automationLaneCount(): number;
     listParameters(): EngineParameterInfo[];
+    /** Registers a custom parameter on the offline mirror and worklet engine. */
+    addParameter(info: EngineParameterInfo): void;
+    /** Clears custom parameters and their automation lanes on both engines. */
+    clearParameters(): void;
     setSoloMute(target: string | number, solo: boolean, mute: boolean): boolean;
     setStripGain(target: string | number, db: number): boolean;
     setStripPan(target: string | number, pan: number): boolean;
@@ -1302,7 +1735,18 @@ declare class SonareEngine {
     setBusStripInsertParamByName(busId: number, insertIndex: number, paramName: string, value: number): void;
     setStripInsertParamByName(target: string | number, insertIndex: number, paramName: string, value: number): void;
     setMasterChain(sceneJson: string): void;
-    addClip(trackId: string | number, buffer: Float32Array[], startPpq: number, opts?: Partial<Omit<EngineClip, 'channels' | 'startPpq'>>): number;
+    /**
+     * Creates and primes an OPFS-backed page provider for this live worklet
+     * engine. Pass the returned `provider` to {@link addClip} in place of a
+     * `Float32Array[]`; the `clipId` in `options` must equal that clip's explicit
+     * `opts.id`. Subsequent cache misses are fetched on the main thread and
+     * supplied back to the worklet through its bounded pull protocol.
+     */
+    attachOpfsClipStream(options: OpfsClipStreamOptions): Promise<{
+        binding: OpfsClipPageProviderBinding;
+        provider: ClipPageProvider;
+    }>;
+    addClip(trackId: string | number, buffer: Float32Array[] | ClipPageProvider, startPpq: number, opts?: Partial<Omit<EngineClip, 'channels' | 'pageProvider' | 'startPpq'>>): number;
     removeClip(clipId: number): void;
     setMidiClips(schedules: readonly EngineMidiClipSchedule[]): void;
     setBuiltinInstrument(trackId: string | number, config?: {
@@ -1314,6 +1758,7 @@ declare class SonareEngine {
         destinationId?: number;
         gain?: number;
         polyphony?: number;
+        preferModelForModeledFamilies?: boolean;
     }): void;
     /**
      * Route a track's MIDI to the external output (drained via {@link onMidiOut})
@@ -1341,9 +1786,20 @@ declare class SonareEngine {
     pushMidiNoteOn(trackId: string | number, group: number, channel: number, note: number, velocity: number, renderFrame?: number): void;
     pushMidiNoteOff(trackId: string | number, group: number, channel: number, note: number, velocity?: number, renderFrame?: number): void;
     pushMidiCc(trackId: string | number, group: number, channel: number, controller: number, value: number, renderFrame?: number): void;
+    pushMidiUmp(trackId: string | number, word0: number, renderFrame?: number): void;
     pushMidiSysex(trackId: string | number, data: Uint8Array, renderFrame?: number): void;
+    bindMidiCc(channel: number, controller: number, paramId: number, options?: MidiCcBindOptions): void;
+    setMidiInputSource(destinationId?: number): void;
+    clearMidiInputSource(): void;
+    pushMidiInputNoteOn(group: number, channel: number, note: number, velocity: number, portTimeSamples?: number): void;
+    pushMidiInputNoteOff(group: number, channel: number, note: number, velocity?: number, portTimeSamples?: number): void;
+    pushMidiInputCc(group: number, channel: number, controller: number, value: number, portTimeSamples?: number): void;
     pushMidiPanic(renderFrame?: number): void;
     configureCapture(options: CaptureOptions): void;
+    /**
+     * Arms the engine-global capture path. `trackId` is retained for source
+     * compatibility and must be `0`; per-track capture is not implemented.
+     */
     armRecord(trackId: string | number, enabled: boolean): boolean;
     punch(inPpq: number, outPpq: number): boolean;
     captureStatus(): Promise<EngineCaptureStatus>;
@@ -1380,11 +1836,24 @@ declare class SonareEngine {
     pollMeters(): SonareWorkletMeterSnapshot[];
     pollScope(): SonareWorkletScopeSnapshot[];
     destroy(): void;
+    private ensureWorkletClipStreamer;
+    /**
+     * SAB requests have no postMessage wake-up by design. Polling on the main
+     * thread is therefore intentionally outside the audio callback; 8 ms keeps
+     * the bounded OPFS prefetch frontier responsive without adding worklet GC.
+     */
+    private startWorkletClipPagePolling;
+    private pumpWorkletClipPages;
+    private enqueueWorkletClipPageRequest;
+    private popWorkletClipPageRequest;
+    private commitWorkletClipPageProvider;
     private mixerLanes;
     private syncMixer;
     private postInstrumentSync;
     private flushPendingInstrumentSync;
     private postSync;
+    private flushOfflineMirror;
+    private sendMirroredCommand;
     private get mixerContext();
     private get stripContext();
     private get automationContext();
@@ -1396,6 +1865,7 @@ declare class SonareEngine {
     private stripParamId;
     private sendSmoothedParam;
     private resolveParamId;
+    private syncParameters;
     private resolveTargetId;
     private ensureTrackLane;
     private ensureBus;
@@ -1408,14 +1878,20 @@ declare class SonareRealtimeEngineNode {
     readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
     readonly meterRing?: SonareMeterRingBuffer;
     readonly scopeRing?: SonareScopeRingBuffer;
+    readonly clipPageRequestRing?: SonareClipPageRequestRingBuffer;
+    readonly externalMidiRing?: SonareExternalMidiRingBuffer;
     readonly ready: Promise<void>;
     private telemetryReadIndex;
     private meterReadIndex;
     private scopeReadIndex;
+    private clipPageRequestDroppedRead;
+    private ringPollTimer;
     private telemetryListeners;
     private meterListeners;
     private scopeListeners;
     private midiOutListeners;
+    private clipPageRequestListeners;
+    private syncErrorListeners;
     private captureRequestId;
     private readonly captureRequests;
     private transportRequestId;
@@ -1424,6 +1900,8 @@ declare class SonareRealtimeEngineNode {
     private rejectReady;
     private destroyed;
     private constructor();
+    /** Subscribes to control-plane sync rejections reported by the worklet. */
+    onSyncError(listener: (message: SonareEngineSyncErrorMessage) => void): () => void;
     static create(context: BaseAudioContext, options?: SonareRealtimeEngineNodeOptions): Promise<SonareRealtimeEngineNode>;
     play(sampleTime?: number): boolean;
     stop(sampleTime?: number): boolean;
@@ -1437,6 +1915,14 @@ declare class SonareRealtimeEngineNode {
     pollTelemetry(): SonareEngineTelemetryRecord[];
     pollMeters(): SonareWorkletMeterSnapshot[];
     pollScope(): SonareWorkletScopeSnapshot[];
+    /** Drain lowered MIDI-1 records from the SAB ring on the main thread. */
+    pollMidiOut(): SonareWorkletExternalMidiEvent[];
+    /**
+     * 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;
     onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void;
     onMeter(callback: (meter: SonareWorkletMeterSnapshot) => void): () => void;
     onScope(callback: (scope: SonareWorkletScopeSnapshot) => void): () => void;
@@ -1446,10 +1932,18 @@ declare class SonareRealtimeEngineNode {
      * Web MIDI output port. Returns an unsubscribe function.
      */
     onMidiOut(callback: (events: SonareWorkletExternalMidiEvent[]) => void): () => void;
+    /**
+     * 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;
     destroy(): void;
     private emitTelemetry;
+    private startRingPolling;
+    private stopRingPollingIfUnused;
     private emitMeter;
     private emitMidiOut;
+    private emitClipPageRequests;
     private emitScope;
     private sendCaptureRequest;
     private sendTransportRequest;
@@ -1474,6 +1968,8 @@ declare class SonareRealtimeEngineWorkletProcessor {
     private telemetryRing?;
     private meterRing?;
     private scopeRing?;
+    private clipPageRequestRing?;
+    private externalMidiRing?;
     private transport?;
     private meterIntervalFrames;
     private lastMeterFrame;
@@ -1481,24 +1977,40 @@ declare class SonareRealtimeEngineWorkletProcessor {
     private channelBuffers;
     private readonly liveClips;
     private readonly pagedClipProviders;
+    private readonly pagedClipPageFrames;
     private readonly pendingPagedClips;
+    private readonly clipPageRequestClipIds;
+    private readonly clipPageRequestPageIndices;
+    private clipPageRequestOverflowReported;
     constructor(options?: SonareRealtimeEngineWorkletProcessorOptions, transport?: WorkletTransport);
     process(inputs: WorkletInput, outputs: WorkletOutput): boolean;
     private reacquireChannelBuffers;
     receiveCommand(command: SonareEngineCommandRecord): void;
     receiveSync(message: SonareEngineSyncMessage): void;
+    private applySync;
     receiveCaptureRequest(message: SonareEngineCaptureRequestMessage): void;
     receiveTransportRequest(message: SonareEngineTransportRequestMessage): void;
     destroy(): void;
     private drainCommands;
+    private safeApplyCommand;
     private applyCommand;
     private publishTelemetry;
+    private writeTelemetryScratch;
     private publishTelemetryRecord;
     private publishMeters;
+    private writeMeterScratch;
     private writeMeterRing;
     private publishScope;
+    private writeScopeScratch;
     private publishExternalMidi;
-    private writeScopeRing;
+    /**
+     * Forward a bounded batch of native page misses to the main thread. This
+     * deliberately runs after audio rendering: a cache miss is silence for this
+     * block, and OPFS I/O must never delay `process()`.
+     */
+    private publishClipPageRequests;
+    private removePagedClipProvider;
+    private clearPagedClipProviders;
     private commandRingFromSharedBuffer;
     private telemetryRingFromSharedBuffer;
 }
@@ -1549,16 +2061,14 @@ declare class SonareRealtimeVoiceChangerWorkletProcessor {
     private readonly channelCount;
     private monoInput;
     private monoOutput;
+    private bufferGeneration;
     private planarChannels;
     private destroyed;
     constructor(options?: SonareRealtimeVoiceChangerWorkletProcessorOptions);
     /**
-     * Handles a control-plane message from the main thread. Runs on the
-     * AudioWorklet global scope but OUTSIDE of `process()` (i.e. outside the
-     * realtime audio callback), so it is safe to perform JSON parsing and
-     * DSP coefficient recomputation here. `setConfig` MUST NOT be deferred
-     * into `process()` because that would block the audio thread for longer
-     * than one render quantum (e.g. 128 samples / 44.1 kHz = ~2.9 ms).
+     * Handles a control-plane message from the main thread. AudioWorklet port
+     * handlers run on the same audio rendering thread as `process()`: this path
+     * therefore accepts only a pre-normalized POD and never parses JSON.
      */
     receiveMessage(message: SonareRealtimeVoiceChangerMessage): void;
     process(inputs: WorkletInput, outputs: WorkletOutput): boolean;
@@ -1580,4 +2090,4 @@ declare class SonareRealtimeVoiceChangerWorkletProcessor {
 }
 declare function registerSonareRealtimeVoiceChangerWorkletProcessor(name?: string): void;
 
-export { SONARE_ENGINE_COMMAND_RECORD_BYTES, SONARE_ENGINE_RING_HEADER_INTS, SONARE_ENGINE_TELEMETRY_RECORD_BYTES, SONARE_METER_RING_HEADER_INTS, SONARE_METER_RING_RECORD_FLOATS, SONARE_SCOPE_RING_HEADER_INTS, SONARE_SPECTRUM_RING_HEADER_INTS, SonareEngine, type SonareEngineCaptureRequestMessage, type SonareEngineCaptureResponseMessage, type SonareEngineCommandRecord, type SonareEngineCommandRingBuffer, SonareEngineCommandType, type SonareEngineOptions, type SonareEngineSyncAutomationMessage, type SonareEngineSyncBuiltinInstrumentMessage, type SonareEngineSyncCaptureMessage, type SonareEngineSyncClipsDeltaMessage, type SonareEngineSyncClipsMessage, type SonareEngineSyncLoadSoundFontMessage, type SonareEngineSyncMarkersMessage, type SonareEngineSyncMasterStripEqBandMessage, type SonareEngineSyncMasterStripInsertBypassedMessage, type SonareEngineSyncMessage, type SonareEngineSyncMetronomeMessage, type SonareEngineSyncMidiCcMessage, type SonareEngineSyncMidiClipsMessage, type SonareEngineSyncMidiNoteMessage, type SonareEngineSyncMidiPanicMessage, type SonareEngineSyncMixerMessage, type SonareEngineSyncSf2InstrumentMessage, type SonareEngineSyncSynthInstrumentMessage, type SonareEngineSyncTempoMessage, type SonareEngineSyncTrackStripEqBandMessage, type SonareEngineSyncTrackStripInsertBypassedMessage, SonareEngineTelemetryError, type SonareEngineTelemetryRecord, type SonareEngineTelemetryRingBuffer, type SonareEngineTelemetryRingReadResult, SonareEngineTelemetryType, type SonareEngineTransportFacade, type SonareEngineTransportRequestMessage, type SonareEngineTransportResponseMessage, type SonareMeterRingBuffer, type SonareMeterRingReadResult, SonareRealtimeEngineNode, type SonareRealtimeEngineNodeCapabilities, type SonareRealtimeEngineNodeOptions, SonareRealtimeEngineWorkletProcessor, type SonareRealtimeEngineWorkletProcessorOptions, type SonareRealtimeVoiceChangerDestroyMessage, type SonareRealtimeVoiceChangerMessage, type SonareRealtimeVoiceChangerResetMessage, type SonareRealtimeVoiceChangerSetConfigMessage, SonareRealtimeVoiceChangerWorkletProcessor, type SonareRealtimeVoiceChangerWorkletProcessorOptions, type SonareScopeRingBuffer, type SonareScopeRingReadResult, type SonareSpectrumRingBuffer, type SonareSpectrumRingReadResult, type SonareWorkletDestroyMessage, type SonareWorkletMessage, type SonareWorkletMeterSnapshot, SonareWorkletProcessor, type SonareWorkletProcessorOptions, type SonareWorkletScheduleInsertAutomationMessage, type SonareWorkletScopeSnapshot, type SonareWorkletSetMeterIntervalMessage, type SonareWorkletSpectrumSnapshot, type SonareWorkletTransportMessage, createSonareEngineCommandRingBuffer, createSonareEngineTelemetryRingBuffer, createSonareMeterRingBuffer, createSonareScopeRingBuffer, createSonareSpectrumRingBuffer, decodeFrame, encodeFrameHi, encodeFrameLo, init, isInitialized, popSonareEngineCommandRingBuffer, pushSonareEngineCommandRingBuffer, readSonareEngineTelemetryRingBuffer, readSonareMeterRingBuffer, readSonareScopeRingBuffer, readSonareSpectrumRingBuffer, registerSonareRealtimeEngineWorkletProcessor, registerSonareRealtimeVoiceChangerWorkletProcessor, registerSonareWorkletProcessor, sonareEngineCommandRingBufferByteLength, sonareEngineTelemetryRingBufferByteLength, sonareMeterRingBufferByteLength, sonareScopeRingBufferByteLength, sonareSpectrumRingBufferByteLength, writeSonareEngineTelemetryRingBuffer };
+export { type OpfsClipStream, type OpfsClipStreamOptions, SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS, SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S, SONARE_ENGINE_COMMAND_RECORD_BYTES, SONARE_ENGINE_RING_HEADER_INTS, SONARE_ENGINE_TELEMETRY_RECORD_BYTES, SONARE_EXTERNAL_MIDI_RING_HEADER_INTS, SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S, SONARE_METER_RING_HEADER_INTS, SONARE_METER_RING_RECORD_FLOATS, SONARE_SCOPE_RING_HEADER_INTS, SONARE_SPECTRUM_RING_HEADER_INTS, type SonareClipPageRequest, type SonareClipPageRequestRingBuffer, type SonareClipPageRequestRingReadResult, SonareEngine, type SonareEngineCaptureRequestMessage, type SonareEngineCaptureResponseMessage, type SonareEngineClipPageRequestMessage, type SonareEngineCommandRecord, type SonareEngineCommandRingBuffer, SonareEngineCommandType, type SonareEngineOptions, type SonareEngineSyncAutomationMessage, type SonareEngineSyncBuiltinInstrumentMessage, type SonareEngineSyncCaptureMessage, type SonareEngineSyncClipsDeltaMessage, type SonareEngineSyncClipsMessage, type SonareEngineSyncLoadSoundFontMessage, type SonareEngineSyncMarkersMessage, type SonareEngineSyncMasterStripEqBandMessage, type SonareEngineSyncMasterStripInsertBypassedMessage, type SonareEngineSyncMessage, type SonareEngineSyncMetronomeMessage, type SonareEngineSyncMidiCcMessage, type SonareEngineSyncMidiClipsMessage, type SonareEngineSyncMidiNoteMessage, type SonareEngineSyncMidiPanicMessage, type SonareEngineSyncMixerMessage, type SonareEngineSyncSf2InstrumentMessage, type SonareEngineSyncSynthInstrumentMessage, type SonareEngineSyncTempoMessage, type SonareEngineSyncTrackStripEqBandMessage, type SonareEngineSyncTrackStripInsertBypassedMessage, SonareEngineTelemetryError, type SonareEngineTelemetryRecord, type SonareEngineTelemetryRingBuffer, type SonareEngineTelemetryRingReadResult, SonareEngineTelemetryType, type SonareEngineTransportFacade, type SonareEngineTransportRequestMessage, type SonareEngineTransportResponseMessage, type SonareExternalMidiRingBuffer, type SonareExternalMidiRingReadResult, type SonareMeterRingBuffer, type SonareMeterRingReadResult, SonareRealtimeEngineNode, type SonareRealtimeEngineNodeCapabilities, type SonareRealtimeEngineNodeOptions, SonareRealtimeEngineWorkletProcessor, type SonareRealtimeEngineWorkletProcessorOptions, type SonareRealtimeVoiceChangerDestroyMessage, type SonareRealtimeVoiceChangerMessage, type SonareRealtimeVoiceChangerResetMessage, type SonareRealtimeVoiceChangerSetConfigMessage, SonareRealtimeVoiceChangerWorkletProcessor, type SonareRealtimeVoiceChangerWorkletProcessorOptions, type SonareScopeRingBuffer, type SonareScopeRingReadResult, type SonareSpectrumRingBuffer, type SonareSpectrumRingReadResult, type SonareWorkletDestroyMessage, type SonareWorkletMessage, type SonareWorkletMeterSnapshot, SonareWorkletProcessor, type SonareWorkletProcessorOptions, type SonareWorkletScheduleInsertAutomationMessage, type SonareWorkletScopeSnapshot, type SonareWorkletSetMeterIntervalMessage, type SonareWorkletSpectrumSnapshot, type SonareWorkletTransportMessage, attachOpfsClipStream, createSonareClipPageRequestRingBuffer, createSonareEngineCommandRingBuffer, createSonareEngineTelemetryRingBuffer, createSonareExternalMidiRingBuffer, createSonareMeterRingBuffer, createSonareScopeRingBuffer, createSonareSpectrumRingBuffer, decodeFrame, encodeFrameHi, encodeFrameLo, init, isInitialized, popSonareEngineCommandRingBuffer, pushSonareClipPageRequestRingBuffer, pushSonareEngineCommandRingBuffer, pushSonareExternalMidiRingBuffer, readSonareClipPageRequestRingBuffer, readSonareEngineTelemetryRingBuffer, readSonareExternalMidiRingBuffer, readSonareMeterRingBuffer, readSonareScopeRingBuffer, readSonareSpectrumRingBuffer, registerSonareRealtimeEngineWorkletProcessor, registerSonareRealtimeVoiceChangerWorkletProcessor, registerSonareWorkletProcessor, sonareClipPageRequestRingBufferByteLength, sonareEngineCommandRingBufferByteLength, sonareEngineTelemetryRingBufferByteLength, sonareExternalMidiRingBufferByteLength, sonareMeterRingBufferByteLength, sonareScopeRingBufferByteLength, sonareSpectrumRingBufferByteLength, writeSonareEngineTelemetryRingBuffer };