@libraz/libsonare 1.0.4 → 1.2.0

package/dist/worklet.d.ts

@@ -0,0 +1,447 @@
+import { RealtimeEngine, EngineParameterInfo, EngineClip, EngineMetronomeConfig, AutomationCurve } from './index.js';
+export { init, isInitialized } from './index.js';
+
+interface SonareRtModule {
+  _malloc(size: number): number;
+  _free(ptr: number): void;
+  _sonare_rt_engine_abi_version(): number;
+  _sonare_rt_engine_create(): number;
+  _sonare_rt_engine_destroy(engine: number): void;
+  _sonare_rt_engine_prepare(
+    engine: number,
+    sampleRate: number,
+    maxBlockSize: number,
+    commandCapacity: number,
+    telemetryCapacity: number,
+  ): number;
+  _sonare_rt_engine_play(engine: number, renderFrame: bigint): number;
+  _sonare_rt_engine_stop(engine: number, renderFrame: bigint): number;
+  _sonare_rt_engine_seek_sample(
+    engine: number,
+    timelineSample: bigint,
+    renderFrame: bigint,
+  ): number;
+  _sonare_rt_engine_seek_ppq(engine: number, ppq: number, renderFrame: bigint): number;
+  _sonare_rt_engine_set_tempo(engine: number, bpm: number): number;
+  _sonare_rt_engine_set_loop(
+    engine: number,
+    startPpq: number,
+    endPpq: number,
+    enabled: number,
+  ): number;
+  _sonare_rt_engine_seek_marker(engine: number, markerId: number, renderFrame: bigint): number;
+  _sonare_rt_engine_set_metronome_enabled(
+    engine: number,
+    enabled: number,
+    beatGain: number,
+    accentGain: number,
+    clickSamples: number,
+  ): number;
+  _sonare_rt_engine_set_capture_armed(engine: number, armed: number): number;
+  _sonare_rt_engine_set_capture_punch(
+    engine: number,
+    startSample: bigint,
+    endSample: bigint,
+    enabled: number,
+  ): number;
+  _sonare_rt_engine_process(
+    engine: number,
+    channelsPtr: number,
+    numChannels: number,
+    numFrames: number,
+  ): void;
+  _sonare_rt_engine_drain_telemetry(
+    engine: number,
+    typesErrorsValuesPtr: number,
+    frameValuesPtr: number,
+    maxRecords: number,
+  ): number;
+}
+
+interface SonareWorkletProcessorOptions {
+    sceneJson: string;
+    sampleRate?: number;
+    blockSize?: number;
+    stripCount?: number;
+    meterIntervalFrames?: number;
+    meterSharedBuffer?: SharedArrayBuffer;
+    meterRingCapacity?: number;
+    spectrumIntervalFrames?: number;
+    spectrumBands?: number;
+    spectrumSharedBuffer?: SharedArrayBuffer;
+    spectrumRingCapacity?: number;
+}
+interface SonareRealtimeEngineWorkletProcessorOptions {
+    runtimeTarget?: 'embind' | 'sonare-rt';
+    rtModuleUrl?: string;
+    rtWasmBinary?: ArrayBuffer | Uint8Array;
+    sampleRate?: number;
+    blockSize?: number;
+    channelCount?: number;
+    meterIntervalFrames?: number;
+    commandSharedBuffer?: SharedArrayBuffer;
+    commandRingCapacity?: number;
+    telemetrySharedBuffer?: SharedArrayBuffer;
+    telemetryRingCapacity?: number;
+}
+interface SonareRealtimeEngineNodeCapabilities {
+    mode: 'sab' | 'postMessage';
+    runtimeTarget: 'embind' | 'sonare-rt';
+    sharedArrayBuffer: boolean;
+    atomics: boolean;
+    audioWorklet: boolean;
+    engineAbiVersion?: number;
+    expectedEngineAbiVersion?: number;
+    abiCompatible?: boolean;
+    degradedReason?: string;
+}
+interface SonareRealtimeEngineNodeOptions extends SonareRealtimeEngineWorkletProcessorOptions {
+    processorName?: string;
+    moduleUrl?: string | URL;
+    rtModuleUrl?: string;
+    mode?: 'auto' | 'sab' | 'postMessage';
+    engineAbiVersion?: number;
+    expectedEngineAbiVersion?: number;
+    requireAbiCompatible?: boolean;
+    nodeFactory?: (context: BaseAudioContext, processorName: string, options: AudioWorkletNodeOptions) => AudioWorkletNode;
+}
+interface SonareRtRealtimeEngineRuntimeOptions {
+    module: SonareRtModule;
+    memory: WebAssembly.Memory;
+    sampleRate?: number;
+    blockSize?: number;
+    channelCount?: number;
+    commandSharedBuffer?: SharedArrayBuffer;
+    commandRingCapacity?: number;
+    telemetrySharedBuffer?: SharedArrayBuffer;
+    telemetryRingCapacity?: number;
+}
+interface SonareEngineOptions extends SonareRealtimeEngineNodeOptions {
+    offlineEngine?: RealtimeEngine;
+    offlineBlockSize?: number;
+    offlineChannelCount?: number;
+}
+interface SonareEngineTransportFacade {
+    play(sampleTime?: number): boolean;
+    stop(sampleTime?: number): boolean;
+    seekPpq(ppq: number, sampleTime?: number): boolean;
+    seekSeconds(seconds: number, sampleTime?: number): boolean;
+    setTempo(bpm: number): void;
+    setLoop(startPpq: number, endPpq: number, enabled?: boolean): boolean;
+}
+type WorkletInput = readonly (readonly Float32Array[])[];
+type WorkletOutput = Float32Array[][];
+interface SonareWorkletScheduleInsertAutomationMessage {
+    type: 'scheduleInsertAutomation';
+    stripIndex: number;
+    insertIndex: number;
+    paramId: number;
+    value: number;
+    samplePos?: number;
+    curve?: AutomationCurve;
+}
+interface SonareWorkletSetMeterIntervalMessage {
+    type: 'setMeterInterval';
+    frames: number;
+}
+interface SonareWorkletDestroyMessage {
+    type: 'destroy';
+}
+type SonareWorkletMessage = SonareWorkletScheduleInsertAutomationMessage | SonareWorkletSetMeterIntervalMessage | SonareWorkletDestroyMessage;
+interface SonareWorkletMeterSnapshot {
+    type: 'meter';
+    frame: number;
+    peakDbL: number;
+    peakDbR: number;
+    rmsDbL: number;
+    rmsDbR: number;
+    correlation: number;
+}
+interface SonareWorkletSpectrumSnapshot {
+    type: 'spectrum';
+    frame: number;
+    bands: Float32Array;
+}
+type SonareWorkletTransportMessage = SonareWorkletMeterSnapshot | SonareWorkletSpectrumSnapshot | SonareEngineTelemetryRecord;
+declare const SONARE_METER_RING_HEADER_INTS = 4;
+declare const SONARE_METER_RING_RECORD_FLOATS = 6;
+declare const SONARE_SPECTRUM_RING_HEADER_INTS = 5;
+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 enum SonareEngineCommandType {
+    SetParam = 0,
+    SetParamSmoothed = 1,
+    TransportPlay = 2,
+    TransportStop = 3,
+    TransportSeekSample = 4,
+    TransportSeekPpq = 5,
+    SetTempoMap = 6,
+    SetLoop = 7,
+    SwapGraph = 8,
+    SwapAutomation = 9,
+    SetSoloMute = 10,
+    AddClip = 11,
+    RemoveClip = 12,
+    ArmRecord = 13,
+    Punch = 14,
+    SetMetronome = 15,
+    SetMarker = 16,
+    SeekMarker = 17
+}
+declare enum SonareEngineTelemetryType {
+    ProcessBlock = 0,
+    Error = 1
+}
+declare enum SonareEngineTelemetryError {
+    None = 0,
+    CommandQueueOverflow = 1,
+    PendingCommandOverflow = 2,
+    BoundaryOverflow = 3,
+    TelemetryOverflow = 4,
+    CaptureOverflow = 5,
+    MaxBlockExceeded = 6,
+    UnknownTarget = 7,
+    NonRealtimeSafeParameter = 8,
+    NotPrepared = 9,
+    NonQueueableCommand = 10,
+    AutomationBindTargetOverflow = 11,
+    StaleAutomationLanes = 12,
+    SmoothedParameterCapacity = 13
+}
+interface WorkletTransport {
+    postMessage?: (message: SonareWorkletTransportMessage) => void;
+    onMeter?: (meter: SonareWorkletMeterSnapshot) => void;
+    onSpectrum?: (spectrum: SonareWorkletSpectrumSnapshot) => void;
+}
+interface SonareMeterRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    records: Float32Array;
+    capacity: number;
+}
+interface SonareMeterRingReadResult {
+    nextReadIndex: number;
+    meters: SonareWorkletMeterSnapshot[];
+}
+interface SonareSpectrumRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    records: Float32Array;
+    capacity: number;
+    bands: number;
+}
+interface SonareSpectrumRingReadResult {
+    nextReadIndex: number;
+    spectra: SonareWorkletSpectrumSnapshot[];
+}
+interface SonareEngineCommandRecord {
+    type: SonareEngineCommandType | number;
+    targetId?: number;
+    sampleTime?: number | bigint;
+    argFloat?: number;
+    argInt?: number | bigint;
+}
+interface SonareEngineTelemetryRecord {
+    type: SonareEngineTelemetryType | number;
+    error: SonareEngineTelemetryError | number;
+    renderFrame: number;
+    timelineSample: number;
+    audibleTimelineSample: number;
+    graphLatencySamplesQ8: number;
+    value: number;
+}
+interface SonareEngineCommandRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    view: DataView;
+    capacity: number;
+}
+interface SonareEngineTelemetryRingBuffer {
+    sharedBuffer: SharedArrayBuffer;
+    header: Int32Array;
+    view: DataView;
+    capacity: number;
+}
+interface SonareEngineTelemetryRingReadResult {
+    nextReadIndex: number;
+    telemetry: SonareEngineTelemetryRecord[];
+}
+declare function sonareMeterRingBufferByteLength(capacity: number): number;
+declare function createSonareMeterRingBuffer(capacity?: number): SonareMeterRingBuffer;
+declare function readSonareMeterRingBuffer(ring: SonareMeterRingBuffer, readIndex?: number): SonareMeterRingReadResult;
+declare function sonareSpectrumRingBufferByteLength(capacity: number, bands?: number): number;
+declare function createSonareSpectrumRingBuffer(capacity?: number, bands?: number): SonareSpectrumRingBuffer;
+declare function readSonareSpectrumRingBuffer(ring: SonareSpectrumRingBuffer, readIndex?: number): SonareSpectrumRingReadResult;
+declare function sonareEngineCommandRingBufferByteLength(capacity: number): number;
+declare function sonareEngineTelemetryRingBufferByteLength(capacity: number): number;
+declare function createSonareEngineCommandRingBuffer(capacity?: number): SonareEngineCommandRingBuffer;
+declare function createSonareEngineTelemetryRingBuffer(capacity?: number): SonareEngineTelemetryRingBuffer;
+declare function pushSonareEngineCommandRingBuffer(ring: SonareEngineCommandRingBuffer, command: SonareEngineCommandRecord): boolean;
+declare function popSonareEngineCommandRingBuffer(ring: SonareEngineCommandRingBuffer): SonareEngineCommandRecord | null;
+declare function writeSonareEngineTelemetryRingBuffer(ring: SonareEngineTelemetryRingBuffer, telemetry: SonareEngineTelemetryRecord): void;
+declare function readSonareEngineTelemetryRingBuffer(ring: SonareEngineTelemetryRingBuffer, readIndex?: number): SonareEngineTelemetryRingReadResult;
+/**
+ * AudioWorklet-style mixer bridge backed by the package's single `sonare.wasm`.
+ *
+ * The WASM module must already be initialized via `init()` before constructing
+ * this bridge. Each AudioWorklet input is treated as one stereo strip:
+ * `inputs[strip][0]` is left and `inputs[strip][1]` is right. Missing channels
+ * are replaced with preallocated silence.
+ */
+declare class SonareWorkletProcessor {
+    readonly sampleRate: number;
+    readonly blockSize: number;
+    private mixer;
+    private realtime;
+    private closed;
+    private processedFrames;
+    private lastMeterFrame;
+    private meterIntervalFrames;
+    private spectrumIntervalFrames;
+    private lastSpectrumFrame;
+    private transport?;
+    private meterRing?;
+    private spectrumRing?;
+    private spectrumBands;
+    constructor(options: SonareWorkletProcessorOptions, transport?: WorkletTransport);
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean;
+    receiveMessage(message: SonareWorkletMessage): void;
+    destroy(): void;
+    private publishMeter;
+    private writeMeterRing;
+    private publishSpectrum;
+    private computeSpectrum;
+    private writeSpectrumRing;
+}
+/**
+ * AudioWorklet-style bridge for the DAW realtime engine facade.
+ *
+ * The default mode uses the existing `sonare.wasm` embind facade. The
+ * `sonare-rt` target is exposed as a selectable runtime target for hosts that
+ * load the dedicated Emscripten AudioWorklet module.
+ */
+declare class SonareRealtimeEngineWorkletProcessor {
+    readonly sampleRate: number;
+    readonly blockSize: number;
+    readonly channelCount: number;
+    readonly runtimeTarget: 'embind' | 'sonare-rt';
+    private engine;
+    private closed;
+    private commandRing?;
+    private telemetryRing?;
+    private transport?;
+    private meterIntervalFrames;
+    private lastMeterFrame;
+    constructor(options?: SonareRealtimeEngineWorkletProcessorOptions, transport?: WorkletTransport);
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean;
+    receiveCommand(command: SonareEngineCommandRecord): void;
+    destroy(): void;
+    private drainCommands;
+    private applyCommand;
+    private publishTelemetry;
+    private publishTelemetryRecord;
+    private publishMeters;
+    private commandRingFromSharedBuffer;
+    private telemetryRingFromSharedBuffer;
+}
+declare class SonareRtRealtimeEngineRuntime {
+    readonly sampleRate: number;
+    readonly blockSize: number;
+    readonly channelCount: number;
+    private readonly module;
+    private readonly memory;
+    private readonly engine;
+    private readonly channelPointerTable;
+    private readonly channelBuffers;
+    private readonly telemetryIntsPtr;
+    private readonly telemetryFramesPtr;
+    private readonly commandRing?;
+    private readonly telemetryRing?;
+    private closed;
+    constructor(options: SonareRtRealtimeEngineRuntimeOptions);
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean;
+    destroy(): void;
+    private writeChannelPointers;
+    private drainCommands;
+    private applyCommand;
+    private publishTelemetry;
+    private commandRingFromSharedBuffer;
+    private telemetryRingFromSharedBuffer;
+}
+declare class SonareRealtimeEngineNode {
+    readonly node: AudioWorkletNode;
+    readonly capabilities: SonareRealtimeEngineNodeCapabilities;
+    readonly commandRing?: SonareEngineCommandRingBuffer;
+    readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
+    readonly ready: Promise<void>;
+    private telemetryReadIndex;
+    private telemetryListeners;
+    private meterListeners;
+    private resolveReady;
+    private rejectReady;
+    private destroyed;
+    private constructor();
+    static create(context: BaseAudioContext, options?: SonareRealtimeEngineNodeOptions): Promise<SonareRealtimeEngineNode>;
+    play(sampleTime?: number): boolean;
+    stop(sampleTime?: number): boolean;
+    seekSample(timelineSample: number, sampleTime?: number): boolean;
+    seekPpq(ppq: number, sampleTime?: number): boolean;
+    sendCommand(command: SonareEngineCommandRecord): boolean;
+    pollTelemetry(): SonareEngineTelemetryRecord[];
+    onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void;
+    onMeter(callback: (meter: SonareWorkletMeterSnapshot) => void): () => void;
+    destroy(): void;
+    private emitTelemetry;
+    private emitMeter;
+}
+declare class SonareEngine {
+    readonly node: AudioWorkletNode;
+    readonly capabilities: SonareRealtimeEngineNodeCapabilities;
+    readonly transport: SonareEngineTransportFacade;
+    private readonly realtimeNode;
+    private readonly offlineEngine;
+    private readonly context;
+    private readonly sampleRate;
+    private readonly offlineBlockSize;
+    private readonly offlineChannelCount;
+    private readonly automationLanes;
+    private readonly clips;
+    private readonly markers;
+    private nextClipId;
+    private nextMarkerId;
+    private destroyed;
+    private constructor();
+    static create(context: BaseAudioContext, options?: SonareEngineOptions): Promise<SonareEngine>;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    setTempo(bpm: number): void;
+    setLoop(startPpq: number, endPpq: number, enabled?: boolean): boolean;
+    setParam(nodeId: string, param: string | number, value: number): boolean;
+    scheduleParam(nodeId: string, param: string | number, ppq: number, value: number, curve?: number | 'linear' | 'exponential'): void;
+    addAutomationPoint(laneId: string | number, ppq: number, value: number, curve?: number | 'linear' | 'exponential'): void;
+    listParameters(): EngineParameterInfo[];
+    setSoloMute(target: string | number, solo: boolean, mute: boolean): boolean;
+    addClip(trackId: string | number, buffer: Float32Array[], startPpq: number, opts?: Partial<Omit<EngineClip, 'channels' | 'startPpq'>>): number;
+    removeClip(clipId: number): void;
+    armRecord(trackId: string | number, enabled: boolean): boolean;
+    punch(inPpq: number, outPpq: number): boolean;
+    setMetronome(opts: EngineMetronomeConfig): void;
+    addMarker(ppq: number, name?: string): number;
+    seekMarker(markerId: number): boolean;
+    renderOffline(totalFrames: number): Promise<Float32Array[]>;
+    onMeter(callback: (meter: SonareWorkletMeterSnapshot) => void): () => void;
+    onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void;
+    pollTelemetry(): SonareEngineTelemetryRecord[];
+    destroy(): void;
+    private syncClips;
+    private syncMarkers;
+    private resolveParamId;
+    private resolveTargetId;
+    private curveCode;
+    private ppqToApproxSample;
+}
+declare function registerSonareWorkletProcessor(name?: string): void;
+declare function registerSonareRealtimeEngineWorkletProcessor(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_SPECTRUM_RING_HEADER_INTS, SonareEngine, type SonareEngineCommandRecord, type SonareEngineCommandRingBuffer, SonareEngineCommandType, type SonareEngineOptions, SonareEngineTelemetryError, type SonareEngineTelemetryRecord, type SonareEngineTelemetryRingBuffer, type SonareEngineTelemetryRingReadResult, SonareEngineTelemetryType, type SonareEngineTransportFacade, type SonareMeterRingBuffer, type SonareMeterRingReadResult, SonareRealtimeEngineNode, type SonareRealtimeEngineNodeCapabilities, type SonareRealtimeEngineNodeOptions, SonareRealtimeEngineWorkletProcessor, type SonareRealtimeEngineWorkletProcessorOptions, SonareRtRealtimeEngineRuntime, type SonareRtRealtimeEngineRuntimeOptions, type SonareSpectrumRingBuffer, type SonareSpectrumRingReadResult, type SonareWorkletDestroyMessage, type SonareWorkletMessage, type SonareWorkletMeterSnapshot, SonareWorkletProcessor, type SonareWorkletProcessorOptions, type SonareWorkletScheduleInsertAutomationMessage, type SonareWorkletSetMeterIntervalMessage, type SonareWorkletSpectrumSnapshot, type SonareWorkletTransportMessage, createSonareEngineCommandRingBuffer, createSonareEngineTelemetryRingBuffer, createSonareMeterRingBuffer, createSonareSpectrumRingBuffer, popSonareEngineCommandRingBuffer, pushSonareEngineCommandRingBuffer, readSonareEngineTelemetryRingBuffer, readSonareMeterRingBuffer, readSonareSpectrumRingBuffer, registerSonareRealtimeEngineWorkletProcessor, registerSonareWorkletProcessor, sonareEngineCommandRingBufferByteLength, sonareEngineTelemetryRingBufferByteLength, sonareMeterRingBufferByteLength, sonareSpectrumRingBufferByteLength, writeSonareEngineTelemetryRingBuffer };