@libraz/libsonare 1.5.4 → 1.5.5

package/src/project_class.ts

@@ -449,7 +449,11 @@ export class Project {
     this.native.setMidiEvents(clipId, events);
   }
 
-  /** Import an in-memory SMF buffer; returns the first added clip id. */
+  /**
+   * Import an in-memory SMF buffer; returns the first added clip id.
+   * Malformed or partially truncated tracks are rejected instead of installing
+   * a silently shortened clip.
+   */
   importSmf(data: Uint8Array): number {
     return this.native.importSmf(data);
   }
@@ -498,7 +502,10 @@ export class Project {
     this.native.setProgramOnChannel(clipId, group, channel, program, bank);
   }
 
-  /** Destructively bake a MIDI-FX chain into a clip's stored MIDI events. */
+  /**
+   * Destructively bake a MIDI-FX chain into all stored events. Large clips are
+   * drained without truncation; failure leaves the original clip unchanged.
+   */
   bakeMidiFx(clipId: number, configJson: string): void {
     this.native.bakeMidiFx(clipId, configJson);
   }
@@ -510,9 +517,9 @@ export class Project {
 
   /**
    * Pre-flight check for hanging / unmatched notes in a MIDI clip: reports
-   * whether every note-on has a matching note-off (FIFO per channel+note).
-   * Useful before bouncing to catch a stuck note. Throws if `clipId` is unknown
-   * or not a MIDI clip.
+   * whether every note-on in the exported half-open playback window has a
+   * matching note-off (FIFO per group+channel+note). Useful before bouncing to
+   * catch a stuck note. Throws if `clipId` is unknown or not a MIDI clip.
    */
   validateMidiNotes(clipId: number): ProjectNotePairValidation {
     return this.native.validateMidiNotes(clipId);

package/src/public_types_mastering.ts

@@ -138,6 +138,8 @@ export interface MasteringResult {
   inputLufs: number;
   outputLufs: number;
   appliedGainDb: number;
+  /** True when peak headroom prevented the requested LUFS target. */
+  loudnessTargetLimited?: boolean;
   latencySamples?: number;
 }
 
@@ -329,6 +331,7 @@ export interface MasteringChainConfig {
     monoMaker?: {
       enabled?: boolean;
       amount?: number;
+      frequencyHz?: number;
     };
   };
   maximizer?: {
@@ -407,6 +410,8 @@ export interface MasteringChainResult {
   outputTruePeakDbtp: number;
   /** EBU Tech 3342 Loudness Range of the output (LU). */
   outputLra: number;
+  /** True when peak headroom prevented the requested LUFS target. */
+  loudnessTargetLimited: boolean;
   /** Per-stage gain reductions for the dynamics/maximizer stages (a subset of `stages`). */
   stageGainReductions: StageGainReduction[];
 }
@@ -422,6 +427,7 @@ export interface MasteringChainStereoResult {
   /** See {@link MasteringChainResult} for field semantics. */
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: StageGainReduction[];
 }
 

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;

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 {
@@ -186,8 +187,14 @@ export interface PitchResult {
  */
 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

@@ -378,20 +378,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);
 }
 

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,
@@ -290,6 +290,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();
   }
@@ -479,6 +484,7 @@ export class RealtimeEngine {
     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 +557,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);
   }
@@ -833,6 +840,7 @@ export class RealtimeEngine {
     this.native.setCaptureSource(source);
   }
 
+  /** Positive values delay capture relative to the punch window. */
   setRecordOffsetSamples(offsetSamples: number): void {
     this.native.setRecordOffsetSamples(offsetSamples);
   }

package/src/sonare.js.d.ts

@@ -458,6 +458,8 @@ export interface WasmLufsResult {
   integratedLufs: number;
   momentaryLufs: number;
   shortTermLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
   loudnessRange: number;
 }
 
@@ -467,6 +469,7 @@ export interface WasmMasteringResult {
   inputLufs: number;
   outputLufs: number;
   appliedGainDb: number;
+  loudnessTargetLimited?: boolean;
   latencySamples?: number;
 }
 
@@ -479,6 +482,7 @@ export interface WasmMasteringChainResult extends WasmMasteringResult {
   stages: string[];
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
 }
 
@@ -492,6 +496,7 @@ export interface WasmMasteringStereoChainResult {
   stages: string[];
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
 }
 
@@ -624,8 +629,9 @@ export interface WasmEngineMetronomeConfig {
   enabled: boolean;
   beatGain?: number;
   accentGain?: number;
+  /** Explicit click length in samples (0..384000). The engine caps it to one second at its sample rate. */
   clickSamples?: number;
-  /** Optional click length in seconds; > 0 overrides the engine 2 ms default. */
+  /** Optional click length in seconds (0..1); > 0 overrides the engine 2 ms default. */
   clickSeconds?: number;
 }
 
@@ -943,6 +949,7 @@ export interface WasmRealtimeEngine {
     minValue: number,
     maxValue: number,
   ) => void;
+  bindMidiCcBinding: (binding: import('./project_types').ProjectMidiCcBinding) => void;
   clearMidiCcBindings: () => void;
   midiCcBindingCount: () => number;
   setMidiFx: (destinationId: number, configJson: string) => void;
@@ -1100,7 +1107,7 @@ export interface SonareModule {
     detectInversions: boolean,
     chromaMethod: number,
   ) => string[];
-  analyze: (samples: Float32Array, sampleRate: number) => WasmAnalysisResult;
+  analyze: (samples: Float32Array, sampleRate: number, options: object) => WasmAnalysisResult;
   _synthEnumTables: () => WasmSynthEnumTables;
   _synthPatchRoundTrip: (patch: unknown) => unknown;
   _analysisResultSchemaPaths: () => string[];
@@ -1182,6 +1189,13 @@ export interface SonareModule {
 
   meteringPeakDb: (samples: Float32Array, sampleRate: number) => number;
   meteringRmsDb: (samples: Float32Array, sampleRate: number) => number;
+  meteringSilenceRatio: (
+    samples: Float32Array,
+    sampleRate: number,
+    thresholdDb: number,
+    frameLength: number,
+    hopLength: number,
+  ) => number;
   meteringCrestFactorDb: (samples: Float32Array, sampleRate: number) => number;
   meteringDcOffset: (samples: Float32Array, sampleRate: number) => number;
   meteringTruePeakDb: (
@@ -1695,6 +1709,7 @@ export interface SonareModule {
     nMfcc: number,
     nFrames: number,
     nMels: number,
+    lifter: number,
   ) => WasmMelPowerResult;
   mfccToAudio: (
     mfcc: Float32Array,
@@ -1708,6 +1723,7 @@ export interface SonareModule {
     fmax: number,
     nIter: number,
     htk: boolean,
+    lifter: number,
   ) => Float32Array;
 
   // Features - Chroma
@@ -1889,12 +1905,14 @@ export interface SonareModule {
     sampleRate: number,
     hopLength: number,
     nChroma: number,
+    binsPerOctave: number,
   ) => WasmChromaResult;
   chromaCqt: (
     samples: Float32Array,
     sampleRate: number,
     hopLength: number,
     nChroma: number,
+    binsPerOctave: number,
   ) => WasmChromaResult;
   bassChroma: (
     samples: Float32Array,
@@ -1902,7 +1920,13 @@ export interface SonareModule {
     hopLength: number,
     nChroma: number,
   ) => WasmChromaResult;
-  nnlsChroma: (samples: Float32Array, sampleRate: number) => WasmNnlsChromaResult;
+  nnlsChroma: (
+    samples: Float32Array,
+    sampleRate: number,
+    enableStftBlend: boolean,
+    stftBlendWeight: number,
+    stftBlendNFft: number,
+  ) => WasmNnlsChromaResult;
   cqt: (
     samples: Float32Array,
     sampleRate: number,
@@ -2255,6 +2279,7 @@ export interface WasmMixer {
   removeSend: (stripIndex: number, sendIndex: number) => void;
   meterTap: (stripIndex: number, tap: number) => WasmMixMeterSnapshot;
   stripMeter: (stripIndex: number) => WasmMixMeterSnapshot;
+  busMeter: (busId: string) => WasmMixMeterSnapshot;
   scheduleFaderAutomation: (
     stripIndex: number,
     samplePos: number,
@@ -2286,6 +2311,7 @@ export interface WasmMixer {
   busCount: () => number;
   addVcaGroup: (id: string, gainDb: number, members: string[]) => void;
   setVcaGroupGainDb: (id: string, gainDb: number) => void;
+  setVcaGroupMembers: (id: string, members: string[]) => void;
   removeVcaGroup: (id: string) => void;
   vcaGroupCount: () => number;
   toSceneJson: () => string;

package/src/streaming_processors.ts

@@ -1,3 +1,4 @@
+import { flattenChainConfig } from './_chain_config';
 import { getSonareModule } from './module_state';
 import type {
   EqBand,
@@ -64,7 +65,12 @@ export class StreamingMasteringChain {
 
   constructor(config: StreamingMasteringChainConfig) {
     const module = getSonareModule();
-    this.chain = module.createStreamingMasteringChain(config as Record<string, unknown>);
+    const { loudnessStaticGainDb, loudnessStaticGainPeakDb, ...chainConfig } = config;
+    this.chain = module.createStreamingMasteringChain({
+      __flatParams: flattenChainConfig(chainConfig),
+      loudnessStaticGainDb,
+      loudnessStaticGainPeakDb,
+    });
   }
 
   /**

package/src/validation.ts

@@ -78,6 +78,12 @@ export function assertSampleRate(fnName: string, sampleRate: number): void {
   }
 }
 
+/** Validate and retain the public Audio.fromBuffer construction contract. */
+export function validateAudioBuffer(samples: Float32Array, sampleRate: number): void {
+  assertSamples('Audio.fromBuffer', samples, true);
+  assertSampleRate('Audio.fromBuffer', sampleRate);
+}
+
 export function assertNonNegativeInteger(fnName: string, value: number, argName: string): void {
   if (!Number.isInteger(value) || value < 0) {
     throw new RangeError(`${fnName}: ${argName} must be a non-negative integer`);

package/src/worklet/messages.ts

@@ -191,15 +191,29 @@ export interface ResolvedMetronomeConfig {
 export const DEFAULT_METRONOME_CONFIG: ResolvedMetronomeConfig = {
   beatGain: 0.35,
   accentGain: 0.7,
-  clickSamples: 96,
+  clickSamples: 0,
 };
 
 export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedMetronomeConfig {
-  return {
+  const resolved = {
     beatGain: config.beatGain ?? DEFAULT_METRONOME_CONFIG.beatGain,
     accentGain: config.accentGain ?? DEFAULT_METRONOME_CONFIG.accentGain,
     clickSamples: config.clickSamples ?? DEFAULT_METRONOME_CONFIG.clickSamples,
   };
+  if (
+    !Number.isFinite(resolved.beatGain) ||
+    resolved.beatGain < 0 ||
+    !Number.isFinite(resolved.accentGain) ||
+    resolved.accentGain < 0 ||
+    !Number.isInteger(resolved.clickSamples) ||
+    resolved.clickSamples < 0 ||
+    resolved.clickSamples > 384000 ||
+    (config.clickSeconds !== undefined &&
+      (!Number.isFinite(config.clickSeconds) || config.clickSeconds < 0 || config.clickSeconds > 1))
+  ) {
+    throw new RangeError('invalid metronome gains or click length');
+  }
+  return resolved;
 }
 
 // Out-of-band control messages posted from the main-thread SonareEngine facade

package/src/worklet/protocol.ts

@@ -122,6 +122,8 @@ export enum SonareEngineTelemetryError {
   CommandBacklogDeferred = 14,
   ClipPageUnderrun = 15,
   InsertAutomationOverflow = 16,
+  MidiClockOverflow = 17,
+  MetronomeOverflow = 18,
 }
 
 export interface SonareMeterRingBuffer {