@libraz/libsonare 1.5.5 → 1.6.0

package/src/sonare.js.d.ts

@@ -2,7 +2,12 @@
  * Type declarations for the Emscripten-generated WASM module with embind
  */
 
-import type { SpectralRegionOp, SurroundPan } from './public_types';
+import type {
+  ProgressCallback,
+  SonareCapabilities,
+  SpectralRegionOp,
+  SurroundPan,
+} from './public_types';
 
 export interface SonareModuleOptions {
   locateFile?: (path: string, prefix: string) => string;
@@ -133,8 +138,10 @@ export interface WasmMelodyContourResult {
 export interface WasmAnalysisResult {
   bpm: number;
   bpmConfidence: number;
+  bpmCandidates: WasmBpmHypothesis[];
   key: WasmKeyResult;
   timeSignature: WasmTimeSignatureResult;
+  timeSignatureCandidates: WasmTimeSignatureResult[];
   beats: WasmBeatResult[];
   chords: WasmChordResult[];
   sections: WasmSectionResult[];
@@ -145,6 +152,12 @@ export interface WasmAnalysisResult {
   form: string;
 }
 
+export interface WasmBpmHypothesis {
+  value: number;
+  confidence: number;
+  relation: 'primary' | 'half' | 'double' | 'other';
+}
+
 export interface WasmBpmCandidate {
   bpm: number;
   confidence: number;
@@ -324,6 +337,12 @@ export interface WasmMatrix2dResult {
   cols: number;
 }
 
+export interface WasmSegmentMatrixResult {
+  rows: number;
+  cols: number;
+  values: Float32Array;
+}
+
 export interface WasmDecomposeResult {
   w: Float32Array;
   h: Float32Array;
@@ -390,6 +409,14 @@ export interface WasmPitchResult {
   meanF0: number;
 }
 
+export interface WasmNoteSegment {
+  frameStart: number;
+  frameEnd: number;
+  startSeconds: number;
+  endSeconds: number;
+  medianCents: number;
+}
+
 export interface WasmTrimResult {
   audio: Float32Array;
   startSample: number;
@@ -478,12 +505,30 @@ export interface WasmStageGainReduction {
   gainReductionDb: number;
 }
 
+export interface WasmMasteringLoudnessSummary {
+  integratedLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
+  truePeakDbtp: number;
+  loudnessRange: number;
+}
+
+export interface WasmMasteringReport {
+  before: WasmMasteringLoudnessSummary;
+  after: WasmMasteringLoudnessSummary;
+  appliedGainDb: number;
+  maxGainReductionDb: number;
+  loudnessTargetLimited: boolean;
+  bandEnergyDeltaDb: Float32Array;
+}
+
 export interface WasmMasteringChainResult extends WasmMasteringResult {
   stages: string[];
   outputTruePeakDbtp: number;
   outputLra: number;
   loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
+  report: WasmMasteringReport;
 }
 
 export interface WasmMasteringStereoChainResult {
@@ -498,6 +543,7 @@ export interface WasmMasteringStereoChainResult {
   outputLra: number;
   loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
+  report: WasmMasteringReport;
 }
 
 export interface WasmMasteringStereoResult {
@@ -624,6 +670,36 @@ export interface WasmProjectMarker {
   keyFifths?: number;
   keyMinor?: boolean;
 }
+export interface WasmProjectTrack {
+  id: number;
+  kind: number;
+  midiDestinationId: number;
+  gain: number;
+  pan: number;
+  mute: boolean;
+  solo: boolean;
+  name: string;
+}
+export interface WasmProjectClip {
+  id: number;
+  trackId: number;
+  sourceId: number;
+  sourceKind: number;
+  startPpq: number;
+  lengthPpq: number;
+  sourceOffsetPpq: number;
+  gain: number;
+  loopMode: number;
+  loopLengthPpq: number;
+}
+export interface WasmProjectSource {
+  id: number;
+  kind: number;
+  channelCount: number;
+  storageHandleId: number;
+  sampleRateHint: number;
+  nameOrUri: string;
+}
 
 export interface WasmEngineMetronomeConfig {
   enabled: boolean;
@@ -843,6 +919,7 @@ export interface WasmRealtimeEngine {
   stop: (renderFrame: number) => void;
   seekSample: (timelineSample: number, renderFrame: number) => void;
   settleParameters: () => void;
+  flushControlCommands: () => void;
   seekPpq: (ppq: number, renderFrame: number) => void;
   setTempo: (bpm: number) => void;
   setTempoSegments: (segments: WasmEngineTempoSegment[]) => void;
@@ -926,10 +1003,14 @@ export interface WasmRealtimeEngine {
   clearClipPage: (providerId: number, pageIndex: number) => void;
   destroyClipPageProvider: (providerId: number) => void;
   popClipPageRequest: () => WasmClipPageRequest | null;
+  popClipPageRequestToScratch: () => boolean;
+  clipPageRequestScratchClipId: () => number;
+  clipPageRequestScratchSample: () => number;
+  clipPageRequestOverflowCount: () => number;
   setCaptureBuffer: (numChannels: number, capacityFrames: number) => void;
   armCapture: (armed: boolean) => void;
   setCapturePunch: (startSample: number, endSample: number, enabled: boolean) => void;
-  setCaptureSource: (source: WasmEngineCaptureStatus['source']) => void;
+  setCaptureSource: (source: WasmEngineCaptureStatus['source'] | number) => void;
   setRecordOffsetSamples: (offsetSamples: number) => void;
   setInputMonitor: (enabled: boolean, gain: number) => void;
   resetCapture: () => void;
@@ -1002,14 +1083,29 @@ export interface WasmRealtimeEngine {
     value: number,
     renderFrame: number,
   ) => void;
+  pushMidiUmp: (destinationId: number, word0: 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;
+  externalMidiPendingCount: () => number;
   drainExternalMidi: (maxRecords: number) => WasmExternalMidiEvent[];
+  popExternalMidiToScratch: () => boolean;
+  externalMidiScratchDestinationId: () => number;
+  externalMidiScratchRenderFrame: () => number;
+  externalMidiScratchByteWord: () => number;
+  externalMidiScratchByteCount: () => number;
+  consumeExternalMidiScratch: () => void;
   clearParameters: () => void;
   process: (channels: Float32Array[]) => Float32Array[];
+  prepareWithChannels: (
+    sampleRate: number,
+    maxBlockSize: number,
+    commandCapacity: number,
+    telemetryCapacity: number,
+    maxChannels: number,
+  ) => void;
   prepareChannels: (numChannels: number, maxFrames: number) => void;
   getChannelBuffer: (channel: number, numFrames: number) => Float32Array;
   processPrepared: (numFrames: number) => void;
@@ -1018,19 +1114,40 @@ export interface WasmRealtimeEngine {
   bounceOffline: (options: WasmEngineBounceOptions) => WasmEngineBounceResult;
   freezeOffline: (options: WasmEngineFreezeOptions) => WasmEngineFreezeResult;
   drainTelemetry: (maxRecords: number) => WasmEngineTelemetry[];
+  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) => WasmEngineMeterTelemetry[];
   drainMeterTelemetryWide: (maxRecords: number) => WasmEngineMeterTelemetryWide[];
   configureScopeTelemetry: (intervalFrames: number, bandCount: number) => number;
   drainScopeTelemetry: (maxRecords: number) => WasmEngineScopeTelemetry[];
+  popScopeTelemetryToScratch: () => boolean;
+  scopeScratchTargetId: () => number;
+  scopeScratchRenderFrame: () => number;
+  scopeScratchBandCount: () => number;
+  scopeScratchBand: (index: number) => number;
+  scopeScratchPointCount: () => number;
+  scopeScratchPointLeft: (index: number) => number;
+  scopeScratchPointRight: (index: number) => number;
   delete: () => void;
 }
 
-export type ProgressCallback = (progress: number, stage: string) => void;
+export type { ProgressCallback } from './public_types';
 export type TempogramMode = 'autocorrelation' | 'auto' | 'ac' | 'cosine' | 0 | 1;
 
 export interface WasmSynthEnumTables {
   engineModes: string[];
   waveforms: string[];
+  builtinWaveforms: string[];
   filterModels: string[];
   filterOutputs: string[];
   bodyTypes: string[];
@@ -1068,7 +1185,7 @@ export interface SonareModule {
     profileType: number,
     genreHint: string,
   ) => WasmKeyCandidateResult[];
-  detectOnsets: (samples: Float32Array, sampleRate: number) => Float32Array;
+  detectOnsets: (samples: Float32Array, sampleRate: number, options: object) => Float32Array;
   detectBeats: (samples: Float32Array, sampleRate: number) => Float32Array;
   detectDownbeats: (samples: Float32Array, sampleRate: number) => Float32Array;
   detectChords: (
@@ -1142,6 +1259,7 @@ export interface SonareModule {
     samples: Float32Array,
     sampleRate: number,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmAnalysisResult;
   analyzeBpm: (
     samples: Float32Array,
@@ -1181,11 +1299,13 @@ export interface SonareModule {
   detectKeyCandidates: (samples: Float32Array, sampleRate: number) => WasmKeyCandidateResult[];
   hasFfmpegSupport: () => boolean;
   version: () => string;
+  capabilities: () => SonareCapabilities;
+  capabilityCatalog: () => string;
   abiVersion: () => number;
   engineAbiVersion: () => number;
   voiceChangerAbiVersion: () => number;
-  voiceCharacterPresetId: (preset: number) => string | null;
-  realtimeVoiceChangerPresetConfig: (preset: number) => WasmRealtimeVoiceChangerPodConfig | null;
+  voiceCharacterPresetId: (preset: number) => string;
+  realtimeVoiceChangerPresetConfig: (preset: number) => WasmRealtimeVoiceChangerPodConfig;
 
   meteringPeakDb: (samples: Float32Array, sampleRate: number) => number;
   meteringRmsDb: (samples: Float32Array, sampleRate: number) => number;
@@ -1590,6 +1710,7 @@ export interface SonareModule {
     sampleRate: number,
     config: Record<string, unknown>,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringChainResult;
   masteringChainStereoWithProgress: (
     left: Float32Array,
@@ -1597,6 +1718,7 @@ export interface SonareModule {
     sampleRate: number,
     config: Record<string, unknown>,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringStereoChainResult;
   masteringPresetNames: () => string[];
   masterAudio: (
@@ -1618,6 +1740,7 @@ export interface SonareModule {
     sampleRate: number,
     overrides: Record<string, number | boolean> | null,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringChainResult;
   masterAudioStereoWithProgress: (
     presetName: string,
@@ -1626,6 +1749,7 @@ export interface SonareModule {
     sampleRate: number,
     overrides: Record<string, number | boolean> | null,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringStereoChainResult;
   mixingScenePresetNames: () => string[];
   mixingScenePresetJson: (presetName: string) => string;
@@ -1680,6 +1804,79 @@ export interface SonareModule {
     htk: boolean,
     lifter: number,
   ) => WasmMfccResult;
+  melDelta: (
+    features: Float32Array,
+    nFeatures: number,
+    nFrames: number,
+    width: number,
+  ) => Float32Array;
+  reassignedSpectrogram: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    refPower: number,
+    fillNan: boolean,
+  ) => {
+    nBins: number;
+    nFrames: number;
+    magnitude: Float32Array;
+    times: Float32Array;
+    frequencies: Float32Array;
+  };
+  segmentCrossSimilarity: (
+    x: Float32Array,
+    xRows: number,
+    xCols: number,
+    y: Float32Array,
+    yRows: number,
+    yCols: number,
+    k: number,
+    metric: string,
+    mode: string,
+  ) => WasmSegmentMatrixResult;
+  segmentRecurrenceMatrix: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    k: number,
+    width: number,
+    sym: boolean,
+    metric: string,
+    mode: string,
+  ) => WasmSegmentMatrixResult;
+  segmentRecurrenceToLag: (
+    recurrence: Float32Array,
+    n: number,
+    pad: boolean,
+  ) => WasmSegmentMatrixResult;
+  segmentLagToRecurrence: (
+    lag: Float32Array,
+    rows: number,
+    lags: number,
+  ) => WasmSegmentMatrixResult;
+  segmentSubsegment: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    boundaries: Int32Array,
+    nSegments: number,
+  ) => Int32Array;
+  segmentAgglomerative: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    k: number,
+    linkage: string,
+  ) => Int32Array;
+  segmentPathEnhance: (
+    recurrence: Float32Array,
+    n: number,
+    win: number,
+    maxRatio: number,
+    minRatio: number,
+    nFilters: number,
+  ) => WasmSegmentMatrixResult;
 
   // Features - Inverse reconstruction
   melToStft: (
@@ -1704,6 +1901,16 @@ export interface SonareModule {
     nIter: number,
     htk: boolean,
   ) => Float32Array;
+  griffinLim: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    nIter: number,
+    momentum: number,
+  ) => Float32Array;
   mfccToMel: (
     mfcc: Float32Array,
     nMfcc: number,
@@ -1746,6 +1953,7 @@ export interface SonareModule {
     sampleRate: number,
     nFft: number,
     hopLength: number,
+    p: number,
   ) => Float32Array;
   spectralRolloff: (
     samples: Float32Array,
@@ -1760,6 +1968,13 @@ export interface SonareModule {
     nFft: number,
     hopLength: number,
   ) => Float32Array;
+  spectralFlux: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    lag: number,
+  ) => Float32Array;
   zeroCrossingRate: (
     samples: Float32Array,
     sampleRate: number,
@@ -1826,6 +2041,30 @@ export interface SonareModule {
     threshold: number,
     fillNa: boolean,
   ) => WasmPitchResult;
+  piptrack: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    fmin: number,
+    fmax: number,
+    threshold: number,
+  ) => {
+    nBins: number;
+    nFrames: number;
+    pitches: Float32Array;
+    magnitudes: Float32Array;
+  };
+  noteSegments: (
+    f0Hz: Float32Array,
+    voicedProb: Float32Array,
+    frameRate: number,
+    options: {
+      segmentationThresholdCents?: number;
+      minNoteMs?: number;
+      referenceHz?: number;
+    },
+  ) => WasmNoteSegment[];
 
   // Core - Conversion
   hzToMel: (hz: number) => number;
@@ -1857,9 +2096,31 @@ export interface SonareModule {
     hopLength: number,
   ) => Int32Array;
   frameSignal: (samples: Float32Array, frameLength: number, hopLength: number) => WasmFrameResult;
+  tone: (
+    frequency: number,
+    sampleRate: number,
+    duration: number,
+    phase: number,
+    amplitude: number,
+  ) => Float32Array;
+  chirp: (
+    fmin: number,
+    fmax: number,
+    sampleRate: number,
+    duration: number,
+    linear: boolean,
+  ) => Float32Array;
+  clicks: (
+    times: Float32Array,
+    sampleRate: number,
+    length: number,
+    frequency: number,
+    clickDuration: number,
+  ) => Float32Array;
   padCenter: (values: Float32Array, size: number, padValue: number) => Float32Array;
   fixLength: (values: Float32Array, size: number, padValue: number) => Float32Array;
   fixFrames: (frames: Int32Array, xMin: number, xMax: number, pad: boolean) => Int32Array;
+  onsetBacktrack: (events: Int32Array, energy: Float32Array) => Int32Array;
   peakPick: (
     values: Float32Array,
     preMax: number,
@@ -1883,6 +2144,8 @@ export interface SonareModule {
     hopLength: number,
     winLength: number,
     mode: TempogramMode,
+    center: boolean,
+    norm: boolean,
   ) => WasmTempogramResult;
   cyclicTempogram: (
     onsetEnvelope: Float32Array,
@@ -2019,6 +2282,8 @@ export interface SonareModule {
     sampleRate: number,
     hopLength: number,
     winLength: number,
+    center: boolean,
+    norm: boolean,
   ) => WasmFourierTempogramResult;
   tempogramRatio: (
     tempogramData: Float32Array,
@@ -2115,6 +2380,7 @@ export interface SonareModule {
     maxBlockSize: number,
     commandCapacity: number,
     telemetryCapacity: number,
+    maxChannels?: number,
   ) => WasmRealtimeEngine;
 
   // Streaming - StreamingMasteringChain
@@ -2152,6 +2418,8 @@ export interface WasmStreamingMasteringChain {
     left: Float32Array,
     right: Float32Array,
   ) => { left: Float32Array; right: Float32Array };
+  flushMono: () => Float32Array;
+  flushStereo: () => { left: Float32Array; right: Float32Array };
   reset: () => void;
   latencySamples: () => number;
   stageNames: () => string[];
@@ -2206,8 +2474,10 @@ export interface WasmRealtimeVoiceChanger {
   prepare: (sampleRate: number, maxBlockSize: number, channels: number) => void;
   reset: () => void;
   setConfig: (config: Record<string, unknown> | string) => void;
+  setPodConfig: (config: WasmRealtimeVoiceChangerPodConfig) => void;
   configJson: () => string;
   latencySamples: () => number;
+  bufferGeneration: () => number;
   processMono: (samples: Float32Array) => Float32Array;
   processMonoInto: (samples: Float32Array, output: Float32Array) => void;
   processInterleaved: (samples: Float32Array, channels: number) => Float32Array;

package/src/streaming_processors.ts

@@ -104,6 +104,21 @@ export class StreamingMasteringChain {
     return this.chain.processStereo(left, right);
   }
 
+  /**
+   * Emit delayed audio and finite processor tails after the final mono block.
+   * Call until this returns an empty array. The initial `latencySamples()`
+   * samples of the concatenated stream are delayed and should be discarded for
+   * time-aligned output.
+   */
+  flushMono(): Float32Array {
+    return this.chain.flushMono();
+  }
+
+  /** Stereo counterpart of {@link flushMono}. */
+  flushStereo(): { left: Float32Array; right: Float32Array } {
+    return this.chain.flushStereo();
+  }
+
   /** Reset all processor state without rebuilding. */
   reset(): void {
     this.chain.reset();

package/src/web_midi.ts

@@ -1,4 +1,36 @@
-import type { MidiCcBindOptions, RealtimeEngine } from './realtime_engine';
+import type { MidiCcBindOptions } from './realtime_engine';
+
+export interface WebMidiEngine {
+  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,
+    time?: number,
+  ): void;
+  pushMidiInputNoteOff(
+    group: number,
+    channel: number,
+    note: number,
+    velocity?: number,
+    time?: number,
+  ): void;
+  pushMidiInputCc(
+    group: number,
+    channel: number,
+    controller: number,
+    value: number,
+    time?: number,
+  ): void;
+}
 
 type MidiInputState = 'connected' | 'disconnected';
 
@@ -103,7 +135,7 @@ export function isWebMidiAvailable(): boolean {
 }
 
 export async function bindWebMidi(
-  engine: RealtimeEngine,
+  engine: WebMidiEngine,
   options: BindWebMidiOptions = {},
 ): Promise<WebMidiBinding> {
   const navigatorWithMidi = globalThis.navigator as NavigatorWithMidi | undefined;
@@ -237,7 +269,7 @@ export async function bindWebMidi(
 }
 
 function dispatchMidiMessage(
-  engine: RealtimeEngine,
+  engine: WebMidiEngine,
   event: MidiMessageEventLike,
   group: number,
   runningStatus: number,
@@ -300,7 +332,7 @@ function dispatchMidiMessage(
 }
 
 function dispatchUmpMessage(
-  engine: RealtimeEngine,
+  engine: WebMidiEngine,
   words: ArrayLike<number>,
   portTimeSamples: number,
 ): void {