@libraz/libsonare 1.5.4 → 1.6.0

package/src/public_types_music.ts

@@ -233,6 +233,10 @@ export interface Beat {
 export interface Chord {
   root: PitchClass;
   bass: PitchClass;
+  /** Canonical core spelling; stable across all language bindings. */
+  rootName: string;
+  /** Canonical core spelling; stable across all language bindings. */
+  bassName: string;
   quality: ChordQuality;
   start: number;
   end: number;
@@ -311,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
  */
@@ -339,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

@@ -30,15 +30,16 @@ export interface PitchCorrectOptions extends ValidateOptions {
 export interface NoteStretchOptions {
   /** Note onset position in samples (selects the region). Default 0. */
   onsetSample?: number;
-  /** Note offset position in samples (selects the region). Default 0. */
+  /** Note offset position in samples (selects the region). Defaults to the input length. */
   offsetSample?: number;
-  /** Stretch ratio (0.5 = double duration, 2.0 = half duration). Default 1. */
+  /** Stretch ratio (0.5 = half duration, 2.0 = double duration). Default 1. */
   stretchRatio?: number;
 }
 
 /** Options for `noteMove`. */
 export interface NoteMoveOptions {
   onsetSample?: number;
+  /** Defaults to the input length. */
   offsetSample?: number;
   targetOnsetSample?: number;
 }
@@ -47,7 +48,7 @@ export interface NoteMoveOptions {
 export type SpectralEditMode = 'gain' | 'attenuate' | 'mute' | 'heal';
 
 /** Analysis/synthesis window used by `spectralEdit`. */
-export type SpectralEditWindow = 'hann' | 'hamming' | 'blackman' | 'rectangular';
+export type SpectralEditWindow = 'hann' | 'hamming' | 'blackman' | 'rectangular' | 'rect';
 
 /** One time x frequency rectangle edit op for `spectralEdit`. */
 export interface SpectralRegionOp {
@@ -181,13 +182,52 @@ 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)
  */
 export interface LufsResult {
   integratedLufs: number;
+  /** Final complete 400 ms window, not Max-M. */
   momentaryLufs: number;
+  /** Final complete 3 s window, not Max-S. */
   shortTermLufs: number;
+  /** Maximum 400 ms window (EBU R128 Max-M). */
+  maxMomentaryLufs: number;
+  /** Maximum 3 s window (EBU R128 Max-S). */
+  maxShortTermLufs: number;
   loudnessRange: number;
 }
 

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);
 }
 
 /**
@@ -378,20 +395,38 @@ export function chordFunctionalAnalysis(
  * the UI responsive for long inputs, drive this from a Web Worker and use
  * {@link analyzeWithProgress} to report progress.
  */
-export function analyze(request: SamplesRequest): AnalysisResult;
+export interface MusicAnalyzeOptions {
+  nFft?: number;
+  hopLength?: number;
+  bpmMin?: number;
+  bpmMax?: number;
+  startBpm?: number;
+  useTriadsOnly?: boolean;
+  useHpss?: boolean;
+  chromaHighpassHz?: number;
+  useBassWeighted?: boolean;
+  chromaHopMultiplier?: number;
+  useChordHmm?: boolean;
+  useChordKeyContext?: boolean;
+  chordHmmBeamWidth?: number;
+  detectChordInversions?: boolean;
+}
+export interface MusicAnalyzeRequest extends SamplesRequest, MusicAnalyzeOptions {}
+
+export function analyze(request: MusicAnalyzeRequest): AnalysisResult;
 export function analyze(
   samples: Float32Array,
   sampleRate?: number,
-  options?: GuardedOptions,
+  options?: GuardedOptions & MusicAnalyzeOptions,
 ): AnalysisResult;
 export function analyze(
-  samples: Float32Array | SamplesRequest,
+  samples: Float32Array | MusicAnalyzeRequest,
   sampleRate = 22050,
-  options: GuardedOptions = {},
+  options: GuardedOptions & MusicAnalyzeOptions = {},
 ): AnalysisResult {
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   validateAnalysisInput('analyze', request.samples, request.sampleRate ?? 22050, request);
-  const result = requireModule().analyze(request.samples, request.sampleRate ?? 22050);
+  const result = requireModule().analyze(request.samples, request.sampleRate ?? 22050, request);
   return convertAnalysisResult(result);
 }
 
@@ -541,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

@@ -1,7 +1,7 @@
 import { panLawCode, panModeCode, sendTimingCode } from './codes';
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
-import type { SynthPatch } from './project';
+import type { ProjectMidiCcBinding, SynthPatch } from './project';
 import type { EqBand, PanLaw, PanMode, SendTiming } from './public_types';
 import type {
   WasmClipPageRequest,
@@ -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);
@@ -290,6 +305,11 @@ export class RealtimeEngine {
     );
   }
 
+  /** Bind a 7/14-bit CC, RPN, or NRPN descriptor to a live parameter. */
+  bindMidiCcBinding(binding: ProjectMidiCcBinding): void {
+    this.native.bindMidiCcBinding(binding);
+  }
+
   clearMidiCcBindings(): void {
     this.native.clearMidiCcBindings();
   }
@@ -342,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
@@ -353,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,
@@ -422,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
@@ -475,10 +529,16 @@ 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);
   }
 
+  /** Set a finite tempo in the range (0, 100000] BPM. */
   setTempo(bpm: number): void {
     this.native.setTempo(bpm);
   }
@@ -551,6 +611,7 @@ export class RealtimeEngine {
     this.native.setLoopFromMarkers(startMarkerId, endMarkerId);
   }
 
+  /** Set a metronome config; click lengths are limited to one second. */
   setMetronome(config: EngineMetronomeConfig): void {
     this.native.setMetronome(config);
   }
@@ -817,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);
   }
@@ -829,10 +911,11 @@ export class RealtimeEngine {
     this.native.setCapturePunch(startSample, endSample, enabled);
   }
 
-  setCaptureSource(source: EngineCaptureStatus['source']): void {
+  setCaptureSource(source: EngineCaptureSource): void {
     this.native.setCaptureSource(source);
   }
 
+  /** Positive values delay capture relative to the punch window. */
   setRecordOffsetSamples(offsetSamples: number): void {
     this.native.setRecordOffsetSamples(offsetSamples);
   }
@@ -853,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);
   }
@@ -878,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`.
    */
@@ -905,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);
   }
@@ -936,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();
   }