@libraz/libsonare 1.5.5 → 1.6.0

package/src/public_types.ts

@@ -4,3 +4,71 @@ export * from './public_types_mixing';
 export * from './public_types_music';
 export * from './public_types_realtime';
 export * from './public_types_spectral';
+
+/** Runtime capabilities reported by the loaded libsonare build. */
+export interface SonareCapabilities {
+  version: string;
+  abi: {
+    project: number;
+    engine: number;
+  };
+  platform: string;
+  features: {
+    mastering: boolean;
+    mixing: boolean;
+    fx: boolean;
+    ffmpeg: boolean;
+  };
+  decode: {
+    builtin: string[];
+    ffmpeg: string[];
+  };
+  simd: string;
+  hardwareConcurrency: number;
+}
+
+/** One parameter descriptor in the cross-surface capability catalog. */
+export interface CapabilityCatalogParameter {
+  name: string;
+  id: number;
+  rtSafe: boolean;
+  type: 'boolean' | 'number';
+  min: number | null;
+  max: number | null;
+  default: boolean | number | null;
+  unit: string | null;
+}
+
+/** One named mastering processor and its host-facing capabilities. */
+export interface CapabilityCatalogProcessor {
+  id: string;
+  kind: 'realtime' | 'offline' | 'pair';
+  realtimeInsertable: boolean;
+  stereoOnly: boolean;
+  latencySamples: number;
+  tailSamples: number;
+  /** Coarse realtime work estimate, or null when the processor is not an insert. */
+  realtimeCost: 'low' | 'moderate' | 'high' | null;
+  channelPolicy: 'multichannel' | 'stereoPairOnly' | 'perChannel' | 'passthrough';
+  category: string;
+  params: CapabilityCatalogParameter[];
+}
+
+/** Built-in preset names grouped by feature family. */
+export interface CapabilityCatalogPresets {
+  mastering: string[];
+  synth: string[];
+  mixingScene: string[];
+  voiceChanger: string[];
+}
+
+/** Complete runtime catalog exposed by {@link capabilityCatalog}. */
+export interface CapabilityCatalog {
+  version: string;
+  abi: SonareCapabilities['abi'];
+  processors: CapabilityCatalogProcessor[];
+  presets: CapabilityCatalogPresets;
+}
+
+/** Synchronous progress callback for offline operations. Its return value is ignored. */
+export type ProgressCallback = (progress: number, stage: string) => void;

package/src/public_types_mastering.ts

@@ -394,6 +394,26 @@ export interface StageGainReduction {
   gainReductionDb: number;
 }
 
+/** Existing EBU R128 measurements captured before or after mastering. */
+export interface MasteringLoudnessSummary {
+  integratedLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
+  truePeakDbtp: number;
+  loudnessRange: number;
+}
+
+/** Compact explanation of how an offline mastering chain changed a program. */
+export interface MasteringReport {
+  before: MasteringLoudnessSummary;
+  after: MasteringLoudnessSummary;
+  appliedGainDb: number;
+  maxGainReductionDb: number;
+  loudnessTargetLimited: boolean;
+  /** 32 logarithmically-spaced after-minus-before spectral energy deltas (dB). */
+  bandEnergyDeltaDb: Float32Array;
+}
+
 export interface MasteringChainResult {
   /** Latency-compensated offline output; no separate latency field is reported. */
   samples: Float32Array;
@@ -414,6 +434,7 @@ export interface MasteringChainResult {
   loudnessTargetLimited: boolean;
   /** Per-stage gain reductions for the dynamics/maximizer stages (a subset of `stages`). */
   stageGainReductions: StageGainReduction[];
+  report: MasteringReport;
 }
 
 export interface MasteringChainStereoResult {
@@ -429,6 +450,7 @@ export interface MasteringChainStereoResult {
   outputLra: number;
   loudnessTargetLimited: boolean;
   stageGainReductions: StageGainReduction[];
+  report: MasteringReport;
 }
 
 /**

package/src/public_types_mixing.ts

@@ -1,4 +1,11 @@
-export type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
+export type PanMode =
+  | 'balance'
+  | 'pan'
+  | 'stereoPan'
+  | 'stereo-pan'
+  | 'dualPan'
+  | 'dual-pan'
+  | number;
 
 /**
  * Surround pan position for a strip feeding a >2-channel bus. Phase 1 honors
@@ -77,7 +84,9 @@ export 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.
+ * (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.
  */
 export type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';
 

package/src/public_types_music.ts

@@ -315,6 +315,13 @@ export interface TimeSignature {
   confidence: number;
 }
 
+/** Existing tempo-estimator hypothesis retained by unified analysis. */
+export interface BpmHypothesis {
+  value: number;
+  confidence: number;
+  relation: 'primary' | 'half' | 'double' | 'other';
+}
+
 /**
  * Rhythm features
  */
@@ -343,8 +350,10 @@ export interface MelodyContour {
 export interface AnalysisResult {
   bpm: number;
   bpmConfidence: number;
+  bpmCandidates: BpmHypothesis[];
   key: Key;
   timeSignature: TimeSignature;
+  timeSignatureCandidates: TimeSignature[];
   beatTimes: Float32Array;
   beats: Beat[];
   chords: Chord[];

package/src/public_types_spectral.ts

@@ -182,6 +182,39 @@ export interface PitchResult {
   meanF0: number;
 }
 
+/** Per-bin pitch candidates and peak magnitudes from spectral piptrack. */
+export interface PiptrackResult {
+  nBins: number;
+  nFrames: number;
+  pitches: Float32Array;
+  magnitudes: Float32Array;
+}
+
+/** Magnitude and reassigned time/frequency coordinates for every STFT bin. */
+export interface ReassignedSpectrogramResult {
+  nBins: number;
+  nFrames: number;
+  magnitude: Float32Array;
+  times: Float32Array;
+  frequencies: Float32Array;
+}
+
+/** Row-major matrix returned by librosa.segment-compatible APIs. */
+export interface SegmentMatrix {
+  rows: number;
+  cols: number;
+  values: Float32Array;
+}
+
+/** One stable monophonic note region segmented from an F0 track. */
+export interface NoteSegment {
+  frameStart: number;
+  frameEnd: number;
+  startSeconds: number;
+  endSeconds: number;
+  medianCents: number;
+}
+
 /**
  * Loudness measurement result (EBU R128 / ITU-R BS.1770)
  */

package/src/quick_analysis.ts

@@ -43,12 +43,29 @@ export interface SamplesRequest extends GuardedOptions {
   sampleRate?: number;
 }
 
+/** Peak-picking configuration for {@link detectOnsets}. */
+export interface OnsetDetectOptions {
+  nFft?: number;
+  hopLength?: number;
+  threshold?: number;
+  preMax?: number;
+  postMax?: number;
+  preAvg?: number;
+  postAvg?: number;
+  delta?: number;
+  wait?: number;
+  backtrack?: boolean;
+  backtrackRange?: number;
+}
+export interface DetectOnsetsRequest extends SamplesRequest, OnsetDetectOptions {}
+
 /** Canonical request form for key detection functions. */
 export interface DetectKeyRequest extends KeyDetectionOptions, SamplesRequest {}
 
 /** Canonical request form for analysis with synchronous progress reporting. */
 export interface AnalyzeWithProgressRequest extends SamplesRequest {
-  onProgress: ProgressCallback;
+  onProgress?: ProgressCallback;
+  cancel?: () => boolean;
 }
 
 /** Canonical request form for chord detection. */
@@ -207,20 +224,20 @@ export function detectKeyCandidates(
  * @param sampleRate - Sample rate in Hz (default: 22050)
  * @returns Array of onset times in seconds
  */
-export function detectOnsets(request: SamplesRequest): Float32Array;
+export function detectOnsets(request: DetectOnsetsRequest): Float32Array;
 export function detectOnsets(
   samples: Float32Array,
   sampleRate?: number,
-  options?: GuardedOptions,
+  options?: OnsetDetectOptions & GuardedOptions,
 ): Float32Array;
 export function detectOnsets(
-  samples: Float32Array | SamplesRequest,
+  samples: Float32Array | DetectOnsetsRequest,
   sampleRate = 22050,
-  options: GuardedOptions = {},
+  options: OnsetDetectOptions & GuardedOptions = {},
 ): Float32Array {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   validateAnalysisInput('detectOnsets', request.samples, request.sampleRate ?? 22050, request);
-  return requireModule().detectOnsets(request.samples, request.sampleRate ?? 22050);
+  return requireModule().detectOnsets(request.samples, request.sampleRate ?? 22050, request);
 }
 
 /**
@@ -559,7 +576,8 @@ export function analyzeWithProgress(
   const result = requireModule().analyzeWithProgress(
     request.samples,
     request.sampleRate ?? 22050,
-    request.onProgress,
+    request.onProgress ?? (() => {}),
+    request.cancel ?? (() => false),
   );
   return convertAnalysisResult(result);
 }

package/src/realtime_engine.ts

@@ -38,6 +38,7 @@ export type EngineMarker = WasmEngineMarker;
 export type EngineMetronomeConfig = WasmEngineMetronomeConfig;
 export type EngineGraphSpec = WasmEngineGraphSpec;
 export type EngineCaptureStatus = WasmEngineCaptureStatus;
+export type EngineCaptureSource = EngineCaptureStatus['source'] | number;
 export type EngineBounceOptions = WasmEngineBounceOptions;
 export type EngineBounceResult = WasmEngineBounceResult;
 export type EngineFreezeOptions = WasmEngineFreezeOptions;
@@ -161,6 +162,7 @@ export class RealtimeEngine {
     maxBlockSize = 128,
     commandCapacity = 1024,
     telemetryCapacity = 1024,
+    maxChannels = 64,
   ) {
     const module = getSonareModule();
     const capabilities = engineCapabilities();
@@ -174,6 +176,7 @@ export class RealtimeEngine {
       maxBlockSize,
       commandCapacity,
       telemetryCapacity,
+      maxChannels,
     );
   }
 
@@ -182,8 +185,15 @@ export class RealtimeEngine {
     maxBlockSize: number,
     commandCapacity = 1024,
     telemetryCapacity = 1024,
+    maxChannels = 64,
   ): void {
-    this.native.prepare(sampleRate, maxBlockSize, commandCapacity, telemetryCapacity);
+    this.native.prepareWithChannels(
+      sampleRate,
+      maxBlockSize,
+      commandCapacity,
+      telemetryCapacity,
+      maxChannels,
+    );
   }
 
   /** Queue a sample-accurate parameter change (engine kSetParam). */
@@ -256,7 +266,12 @@ export class RealtimeEngine {
    * synthesizer GM fallback bank (the data-free floor).
    */
   setSf2Instrument(
-    config: { destinationId?: number; gain?: number; polyphony?: number } = {},
+    config: {
+      destinationId?: number;
+      gain?: number;
+      polyphony?: number;
+      preferModelForModeledFamilies?: boolean;
+    } = {},
     destinationId = config.destinationId ?? 0,
   ): void {
     this.native.setSf2Instrument(destinationId, config);
@@ -347,6 +362,10 @@ export class RealtimeEngine {
     return this.native.externalMidiDroppedCount();
   }
 
+  externalMidiPendingCount(): number {
+    return this.native.externalMidiPendingCount();
+  }
+
   /**
    * 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
@@ -358,6 +377,31 @@ export class RealtimeEngine {
     return this.native.drainExternalMidi(maxRecords);
   }
 
+  /** Scalar, allocation-free external-MIDI drain for AudioWorklet SAB output. */
+  popExternalMidiToScratch(): boolean {
+    return this.native.popExternalMidiToScratch();
+  }
+
+  externalMidiScratchDestinationId(): number {
+    return this.native.externalMidiScratchDestinationId();
+  }
+
+  externalMidiScratchRenderFrame(): number {
+    return this.native.externalMidiScratchRenderFrame();
+  }
+
+  externalMidiScratchByteWord(): number {
+    return this.native.externalMidiScratchByteWord();
+  }
+
+  externalMidiScratchByteCount(): number {
+    return this.native.externalMidiScratchByteCount();
+  }
+
+  consumeExternalMidiScratch(): void {
+    this.native.consumeExternalMidiScratch();
+  }
+
   pushMidiInputNoteOn(
     group: number,
     channel: number,
@@ -427,6 +471,11 @@ export class RealtimeEngine {
     this.native.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
   }
 
+  /** Queue one immediate MIDI 1.0 channel-voice UMP word for a destination. */
+  pushMidiUmp(destinationId: number, word0: number, renderFrame = -1): void {
+    this.native.pushMidiUmp(destinationId, word0, renderFrame);
+  }
+
   /**
    * Queue an immediate (live) MIDI SysEx frame to a MIDI destination. `data` is
    * the full message including the leading 0xF0 and trailing 0xF7 (1..512
@@ -480,6 +529,11 @@ export class RealtimeEngine {
     this.native.settleParameters();
   }
 
+  /** Drains queued commands on an offline/control-only engine immediately. */
+  flushControlCommands(): void {
+    this.native.flushControlCommands();
+  }
+
   seekPpq(ppq: number, renderFrame = -1): void {
     this.native.seekPpq(ppq, renderFrame);
   }
@@ -824,6 +878,27 @@ export class RealtimeEngine {
     return this.native.popClipPageRequest();
   }
 
+  /**
+   * Moves one native request into the binding's persistent scalar scratch.
+   * This avoids creating an embind JS object in AudioWorklet process().
+   */
+  popClipPageRequestToScratch(): boolean {
+    return this.native.popClipPageRequestToScratch();
+  }
+
+  clipPageRequestScratchClipId(): number {
+    return this.native.clipPageRequestScratchClipId();
+  }
+
+  clipPageRequestScratchSample(): number {
+    return this.native.clipPageRequestScratchSample();
+  }
+
+  /** Cumulative page misses dropped because the native bounded request queue was full. */
+  clipPageRequestOverflowCount(): number {
+    return this.native.clipPageRequestOverflowCount();
+  }
+
   setCaptureBuffer(numChannels: number, capacityFrames: number): void {
     this.native.setCaptureBuffer(numChannels, capacityFrames);
   }
@@ -836,7 +911,7 @@ export class RealtimeEngine {
     this.native.setCapturePunch(startSample, endSample, enabled);
   }
 
-  setCaptureSource(source: EngineCaptureStatus['source']): void {
+  setCaptureSource(source: EngineCaptureSource): void {
     this.native.setCaptureSource(source);
   }
 
@@ -861,6 +936,10 @@ export class RealtimeEngine {
     return this.native.capturedAudio();
   }
 
+  /**
+   * Renders in place, adding engine output to `channels`. Zero each plane first
+   * when it contains no upstream input.
+   */
   process(channels: Float32Array[]): Float32Array[] {
     return this.native.process(channels);
   }
@@ -886,6 +965,7 @@ export class RealtimeEngine {
 
   /**
    * 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`.
    */
@@ -913,6 +993,51 @@ export class RealtimeEngine {
     return this.native.drainTelemetry(maxRecords);
   }
 
+  popTelemetryToScratch(): boolean {
+    return this.native.popTelemetryToScratch();
+  }
+
+  telemetryScratchType(): number {
+    return this.native.telemetryScratchType();
+  }
+
+  telemetryScratchError(): number {
+    return this.native.telemetryScratchError();
+  }
+
+  telemetryScratchRenderFrame(): number {
+    return Number(this.native.telemetryScratchRenderFrame());
+  }
+
+  telemetryScratchTimelineSample(): number {
+    return Number(this.native.telemetryScratchTimelineSample());
+  }
+
+  telemetryScratchAudibleTimelineSample(): number {
+    return Number(this.native.telemetryScratchAudibleTimelineSample());
+  }
+
+  telemetryScratchGraphLatencySamplesQ8(): number {
+    return this.native.telemetryScratchGraphLatencySamplesQ8();
+  }
+
+  telemetryScratchValue(): number {
+    return this.native.telemetryScratchValue();
+  }
+
+  popMeterTelemetryToScratch(): boolean {
+    return this.native.popMeterTelemetryToScratch();
+  }
+  meterScratchTargetId(): number {
+    return this.native.meterScratchTargetId();
+  }
+  meterScratchRenderFrame(): number {
+    return Number(this.native.meterScratchRenderFrame());
+  }
+  meterScratchValue(field: number): number {
+    return this.native.meterScratchValue(field);
+  }
+
   drainMeterTelemetry(maxRecords = 1024): EngineMeterTelemetry[] {
     return this.native.drainMeterTelemetry(maxRecords);
   }
@@ -944,6 +1069,31 @@ export class RealtimeEngine {
     return this.native.drainScopeTelemetry(maxRecords);
   }
 
+  popScopeTelemetryToScratch(): boolean {
+    return this.native.popScopeTelemetryToScratch();
+  }
+  scopeScratchTargetId(): number {
+    return this.native.scopeScratchTargetId();
+  }
+  scopeScratchRenderFrame(): number {
+    return Number(this.native.scopeScratchRenderFrame());
+  }
+  scopeScratchBandCount(): number {
+    return this.native.scopeScratchBandCount();
+  }
+  scopeScratchBand(index: number): number {
+    return this.native.scopeScratchBand(index);
+  }
+  scopeScratchPointCount(): number {
+    return this.native.scopeScratchPointCount();
+  }
+  scopeScratchPointLeft(index: number): number {
+    return this.native.scopeScratchPointLeft(index);
+  }
+  scopeScratchPointRight(index: number): number {
+    return this.native.scopeScratchPointRight(index);
+  }
+
   destroy(): void {
     this.native.delete();
   }