@libraz/libsonare 1.3.3 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "type": "module",
   "packageManager": "yarn@4.15.0",
   "description": "Audio analysis library for music information retrieval",

package/src/codes.ts

@@ -52,5 +52,10 @@ export function meterTapCode(tap: MeterTap | number): number {
 }
 
 export function sendTimingCode(timing: SendTiming | number): number {
-  return timing === 'preFader' || timing === 0 ? 0 : 1;
+  // Mirrors SonareSendTiming: post-fader is 0 (so an omitted/zeroed value is
+  // post-fader), pre-fader is 1. A raw number is passed through as the C ABI int.
+  if (typeof timing === 'number') {
+    return timing;
+  }
+  return timing === 'preFader' ? 1 : 0;
 }

package/src/effects_mastering.ts

@@ -16,13 +16,15 @@ import type {
   PairProcessor,
   RealtimeVoiceChangerConfigInput,
   SoloProcessor,
+  SpectralEditOptions,
+  SpectralRegionOp,
   StereoAnalysis,
   StreamingPlatform,
 } from './public_types';
 import type { ProgressCallback } from './sonare.js';
 import { RealtimeVoiceChanger } from './streaming_mixing';
 import type { ValidateOptions } from './validation';
-import { assertSamples } from './validation';
+import { assertSampleRate, assertSamples } from './validation';
 
 function requireModule() {
   return getSonareModule();
@@ -339,6 +341,31 @@ export function normalize(
   return requireModule().normalize(samples, sampleRate, targetDb);
 }
 
+/**
+ * Apply region-based spectral edits (gain/attenuate/mute/heal) to mono audio.
+ *
+ * Each op is a time x frequency rectangle applied in array order over a single
+ * STFT buffer, so a later op observes the result of earlier ops. The output has
+ * the same length and sample rate as the input; an empty `ops` list is an
+ * identity transform (within the iSTFT's own tolerance).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param ops - Region edit ops applied in order ({@link SpectralRegionOp})
+ * @param options - STFT + heal configuration ({@link SpectralEditOptions})
+ * @returns Edited audio
+ */
+export function spectralEdit(
+  samples: Float32Array,
+  sampleRate: number,
+  ops: SpectralRegionOp[] = [],
+  options: SpectralEditOptions & ValidateOptions = {},
+): Float32Array {
+  assertSamples('spectralEdit', samples, options.validate !== false);
+  assertSampleRate('spectralEdit', sampleRate);
+  return requireModule().spectralEdit(samples, sampleRate, ops, options as Record<string, unknown>);
+}
+
 /**
  * Apply mastering loudness normalization with a true-peak ceiling.
  *
@@ -392,6 +419,81 @@ export function masteringInsertParamNames(name: string): string[] {
   ).masteringInsertParamNames(name);
 }
 
+/** One realtime-automatable parameter of an insert processor. */
+export interface MasteringInsertParamInfo {
+  /** JSON-key parameter name, as used in scene insert params. */
+  name: string;
+  /** Integer param id for realtime automation lanes / MIDI-CC binding. */
+  id: number;
+  /** Whether the param can be changed live from the audio thread. */
+  rtSafe: boolean;
+}
+
+/**
+ * Returns the realtime-automatable parameter descriptors for an insert / FX
+ * processor: each entry maps a JSON-key parameter name to the integer id used by
+ * realtime automation and reports whether it is realtime-safe. Unlike
+ * {@link masteringInsertParamNames} (every construction key), this lists only the
+ * realtime-controllable subset — the keys accepted by
+ * {@link RealtimeEngine.setTrackStripInsertParamByName}. Returns an empty array
+ * for an unknown name or a processor with no automatable parameters.
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ */
+export function masteringInsertParamInfo(name: string): MasteringInsertParamInfo[] {
+  const json = (
+    requireModule() as unknown as { masteringInsertParamInfo: (name: string) => string }
+  ).masteringInsertParamInfo(name);
+  return JSON.parse(json) as MasteringInsertParamInfo[];
+}
+
+/**
+ * How a processor handles a buffer with more than two channels (a surround
+ * bed). "multichannel" processes every plane in one call; "stereoPairOnly"
+ * operates on the front L/R pair and passes any surround planes through dry.
+ * "perChannel"/"passthrough" are reserved and unused by the current catalog.
+ */
+export type MasteringChannelPolicy =
+  | 'multichannel'
+  | 'stereoPairOnly'
+  | 'perChannel'
+  | 'passthrough';
+
+/** One processor's realtime/offline/pair classification in the catalog. */
+export interface MasteringProcessorCatalogEntry {
+  /** Processor id (the name used for scene inserts / named processors). */
+  id: string;
+  /**
+   * Primary classification, by precedence pair > realtime > offline: "pair" for
+   * two-input match.* processors, "realtime" for ids that build as a realtime
+   * scene insert, "offline" for whole-file-only processors.
+   */
+  kind: 'realtime' | 'offline' | 'pair';
+  /** True exactly for ids that always succeed as a realtime scene insert. */
+  realtimeInsertable: boolean;
+  /** True for processors with no mono implementation (stereo-only). */
+  stereoOnly: boolean;
+  /**
+   * How the mixer wraps the processor on a >2-channel (surround) bus insert:
+   * "multichannel" (one full-buffer call) or "stereoPairOnly" (front L/R pair,
+   * surround planes passed through dry).
+   */
+  channelPolicy: MasteringChannelPolicy;
+}
+
+/**
+ * Returns the machine-readable classification catalog for every named processor
+ * id, merging the offline registry, the realtime insert factory, and the pair
+ * registry. Lets a host filter a processor picker by realtime insertability
+ * instead of offering ids the realtime strip would reject.
+ */
+export function masteringProcessorCatalog(): MasteringProcessorCatalogEntry[] {
+  const json = (
+    requireModule() as unknown as { masteringProcessorCatalog: () => string }
+  ).masteringProcessorCatalog();
+  return JSON.parse(json) as MasteringProcessorCatalogEntry[];
+}
+
 export function masteringPairProcessorNames(): PairProcessor[] {
   return requireModule().masteringPairProcessorNames() as PairProcessor[];
 }

package/src/feature_music.ts

@@ -257,11 +257,21 @@ export function analyzeMelody(
   const fmin = options.fmin ?? 65.0;
   const fmax = options.fmax ?? 2093.0;
   validateFrequencyBounds('analyzeMelody', fmin, fmax);
+  // The melody tracker's fmin is a YIN pitch floor: 0 is meaningless, and the
+  // flat C ABI (sonare_analyze_melody) rejects it. validateFrequencyBounds only
+  // guards fmin >= 0, so enforce strict positivity here for parity.
+  if (fmin <= 0) {
+    throw new RangeError('analyzeMelody: fmin must be positive');
+  }
   validatePositiveIntegers('analyzeMelody', {
     frameLength: options.frameLength ?? 2048,
     hopLength: options.hopLength ?? 256,
   });
-  assertFiniteScalar('analyzeMelody', options.threshold ?? 0.1, 'threshold');
+  const threshold = options.threshold ?? 0.1;
+  assertFiniteScalar('analyzeMelody', threshold, 'threshold');
+  if (threshold <= 0) {
+    throw new RangeError('analyzeMelody: threshold must be positive');
+  }
   return requireModule().analyzeMelody(
     samples,
     sampleRate,
@@ -371,7 +381,9 @@ export function tempogramRatio(
  * Measure loudness (EBU R128 / ITU-R BS.1770).
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard for
+ *   audio; pass the buffer's actual rate, as K-weighting is sample-rate
+ *   dependent and a wrong rate yields wrong loudness.
  * @returns Loudness measurement result
  */
 export function lufs(
@@ -388,7 +400,8 @@ export function lufs(
  * Compute the momentary loudness (LUFS) over time.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard and
+ *   K-weighting is sample-rate dependent; pass the buffer's actual rate.
  * @returns Momentary LUFS values over time
  */
 export function momentaryLufs(
@@ -405,7 +418,8 @@ export function momentaryLufs(
  * Compute the short-term loudness (LUFS) over time.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard and
+ *   K-weighting is sample-rate dependent; pass the buffer's actual rate.
  * @returns Short-term LUFS values over time
  */
 export function shortTermLufs(

package/src/feature_spectral.ts

@@ -218,6 +218,10 @@ export function hpssWithResidual(
  * Channel-weighted multichannel integrated loudness + LRA (ITU-R BS.1770 /
  * EBU R128) from an interleaved buffer of `frames * channels` samples. The
  * per-channel frame count is derived from the buffer length and `channels`.
+ *
+ * Pass the buffer's actual `sampleRate`: the default (22050) is non-standard for
+ * audio, and K-weighting is sample-rate dependent, so a wrong rate yields wrong
+ * loudness.
  */
 export function lufsInterleaved(
   samples: Float32Array,
@@ -231,7 +235,9 @@ export function lufsInterleaved(
 }
 
 /**
- * Standards-compliant EBU R128 loudness range (LRA) in LU.
+ * Standards-compliant EBU R128 loudness range (LRA) in LU. Pass the buffer's
+ * actual `sampleRate`: the default (22050) is non-standard and K-weighting is
+ * sample-rate dependent.
  */
 export function ebur128LoudnessRange(samples: Float32Array, sampleRate = 22050): number {
   return requireModule().ebur128LoudnessRange(samples, sampleRate);

package/src/index.ts

@@ -43,6 +43,9 @@ export type {
   DereverbClassicalOptions,
   DynamicsResult,
   GateOptions,
+  MasteringChannelPolicy,
+  MasteringInsertParamInfo,
+  MasteringProcessorCatalogEntry,
   TransientShaperOptions,
   TrimSilenceMode,
   TrimSilenceOptions,
@@ -67,6 +70,7 @@ export {
   masteringDynamicsGate,
   masteringDynamicsTransientShaper,
   masteringInsertNames,
+  masteringInsertParamInfo,
   masteringInsertParamNames,
   masteringPairAnalysisNames,
   masteringPairAnalyze,
@@ -74,6 +78,7 @@ export {
   masteringPairProcessorNames,
   masteringPresetNames,
   masteringProcess,
+  masteringProcessorCatalog,
   masteringProcessorNames,
   masteringProcessStereo,
   masteringRepairDeclick,
@@ -95,6 +100,7 @@ export {
   pitchCorrectToMidi,
   pitchCorrectToMidiTimevarying,
   pitchShift,
+  spectralEdit,
   timeStretch,
   voiceChange,
   voiceChangeRealtime,
@@ -245,6 +251,7 @@ export type {
   ProjectLoopMode,
   ProjectLoopRecordingDesc,
   ProjectLoopRecordingResult,
+  ProjectMarker,
   ProjectMidiClipResult,
   ProjectMidiEvent,
   ProjectNotePairValidation,
@@ -268,6 +275,7 @@ export type {
 } from './project';
 export {
   EXPECTED_PROJECT_ABI_VERSION,
+  MarkerKind,
   Project,
   projectAbiVersion,
   SYNTH_BODY_TYPES,
@@ -348,6 +356,10 @@ export type {
   Section,
   SendTiming,
   SoloProcessor,
+  SpectralEditMode,
+  SpectralEditOptions,
+  SpectralEditWindow,
+  SpectralRegionOp,
   StereoAnalysis,
   StftPowerResult,
   StftResult,
@@ -410,10 +422,12 @@ export type {
   EngineGraphSpec,
   EngineMarker,
   EngineMeterTelemetry,
+  EngineMeterTelemetryWide,
   EngineMetronomeConfig,
   EngineMidiClipSchedule,
   EngineMidiEvent,
   EngineParameterInfo,
+  EngineScopeTelemetry,
   EngineTelemetry,
   EngineTempoSegment,
   EngineTimeSignatureSegment,

package/src/mixer.ts

@@ -15,6 +15,7 @@ import type {
   PanLaw,
   PanMode,
   SendTiming,
+  SurroundPan,
 } from './public_types';
 
 export interface MixerRealtimeBuffer {
@@ -348,6 +349,14 @@ export class Mixer {
     this.mixer.setDualPan(stripIndex, leftPan, rightPan);
   }
 
+  /**
+   * Set the strip's surround pan position, used when it feeds a >2-channel bus.
+   * Stored on the scene; inert until the surround DSP path applies it.
+   */
+  setSurroundPan(stripIndex: number, pan: SurroundPan): void {
+    this.mixer.setSurroundPan(stripIndex, pan);
+  }
+
   /**
    * Add a send to a strip after construction.
    *

package/src/project.ts

@@ -25,6 +25,34 @@ export interface ProjectBounceOptions {
   instrumentLatencySamples?: number;
 }
 
+/**
+ * Marker kind ordinals. Mirrors `SonareMarkerKind` in `src/sonare_c_types.h`;
+ * the values are part of the ABI and must not be renumbered.
+ */
+export const MarkerKind = {
+  marker: 0,
+  text: 1,
+  lyric: 2,
+  cuePoint: 3,
+  keySignature: 4,
+} as const;
+
+/** A project timeline marker with its kind and (for key signatures) the key. */
+export interface ProjectMarker {
+  /** Stable marker id (0 when allocating a new id via {@link Project.setMarkerEx}). */
+  id: number;
+  /** Marker position in PPQ (quarter notes). */
+  ppq: number;
+  /** Marker label. */
+  name?: string;
+  /** {@link MarkerKind} ordinal (default 0 = marker). */
+  kind?: number;
+  /** Key signature only: -7..7 (sharps positive). */
+  keyFifths?: number;
+  /** Key signature only: false = major, true = minor. */
+  keyMinor?: boolean;
+}
+
 /** Oscillator waveform for the built-in synth. */
 export type BuiltinSynthWaveform =
   | 'sine'
@@ -544,6 +572,10 @@ interface WasmProject {
   setWarpMap: (map: ProjectWarpMapDesc) => void;
   removeWarpMap: (warpRefId: number) => void;
   setTrackMidiDestination: (trackId: number, destinationId: number) => void;
+  setTrackGain: (trackId: number, gain: number) => void;
+  setTrackMute: (trackId: number, mute: boolean) => void;
+  setTrackSolo: (trackId: number, solo: boolean) => void;
+  setTrackPan: (trackId: number, pan: number) => void;
   undo: () => void;
   redo: () => void;
   setMidiEvents: (
@@ -627,6 +659,9 @@ interface WasmProject {
   getSampleRate: () => number;
   setMixerSceneJson: (sceneJson: string) => void;
   setMarker: (markerId: number, ppq: number, name: string) => number;
+  setMarkerEx: (marker: ProjectMarker) => number;
+  markerByIndex: (index: number) => ProjectMarker;
+  markerCount: () => number;
   trackCount: () => number;
   sourceCount: () => number;
   tempoSegmentCount: () => number;
@@ -1166,6 +1201,26 @@ export class Project {
     this.native.setTrackMidiDestination(trackId, destinationId);
   }
 
+  /** Set a track's linear playback gain (1.0 = unity; >= 0) via an undoable edit. */
+  setTrackGain(trackId: number, gain: number): void {
+    this.native.setTrackGain(trackId, gain);
+  }
+
+  /** Set a track's mute flag via an undoable edit (a muted track is silent). */
+  setTrackMute(trackId: number, mute: boolean): void {
+    this.native.setTrackMute(trackId, mute);
+  }
+
+  /** Set a track's solo flag via an undoable edit (when any track is soloed, only soloed tracks sound). */
+  setTrackSolo(trackId: number, solo: boolean): void {
+    this.native.setTrackSolo(trackId, solo);
+  }
+
+  /** Set a track's stereo balance in [-1, +1] (0 = center) via an undoable edit. */
+  setTrackPan(trackId: number, pan: number): void {
+    this.native.setTrackPan(trackId, pan);
+  }
+
   /** Undo the most recent edit. */
   undo(): void {
     this.native.undo();
@@ -1527,6 +1582,25 @@ export class Project {
     return this.native.setMarker(markerId, ppq, name);
   }
 
+  /**
+   * Add or replace a marker from a full {@link ProjectMarker}, including its
+   * {@link MarkerKind} and (for key signatures) the key. Pass `id` 0 to allocate
+   * a new id; returns the stable marker id.
+   */
+  setMarkerEx(marker: ProjectMarker): number {
+    return this.native.setMarkerEx(marker);
+  }
+
+  /** Read a project marker by index (0-based, in stored order). */
+  markerByIndex(index: number): ProjectMarker {
+    return this.native.markerByIndex(index);
+  }
+
+  /** Number of markers in the project. */
+  markerCount(): number {
+    return this.native.markerCount();
+  }
+
   /** Number of tracks in the project. */
   trackCount(): number {
     return this.native.trackCount();

package/src/public_types.ts

@@ -367,6 +367,40 @@ export interface NoteStretchOptions {
   stretchRatio?: number;
 }
 
+/** How a `spectralEdit` region op modifies the masked bins. */
+export type SpectralEditMode = 'gain' | 'attenuate' | 'mute' | 'heal';
+
+/** Analysis/synthesis window used by `spectralEdit`. */
+export type SpectralEditWindow = 'hann' | 'hamming' | 'blackman' | 'rectangular';
+
+/** One time x frequency rectangle edit op for `spectralEdit`. */
+export interface SpectralRegionOp {
+  /** Region time start (input samples); clamped to [0, length]. Default 0. */
+  startSample?: number;
+  /** Region time end, exclusive (input samples); clamped to [0, length]. Default = signal length. */
+  endSample?: number;
+  /** Region frequency low edge in Hz; clamped to [0, nyquist]. Default 0. */
+  lowHz?: number;
+  /** Region frequency high edge in Hz; <=0 or >= nyquist means nyquist. Default 0. */
+  highHz?: number;
+  /** Linear gain in dB for 'gain'/'attenuate'; ignored by 'mute'/'heal'. Default 0. */
+  gainDb?: number;
+  /** Edit mode. Default 'gain'. */
+  mode?: SpectralEditMode;
+}
+
+/** STFT + heal parameters for `spectralEdit`. All fields are optional. */
+export interface SpectralEditOptions {
+  /** FFT size; must be a power of two (>= 2). Default 2048. */
+  nFft?: number;
+  /** Hop length; must satisfy 0 < hop <= nFft/2. Default 512. */
+  hopLength?: number;
+  /** Analysis + synthesis window. Default 'hann'. */
+  window?: SpectralEditWindow;
+  /** Neighbour frames each side used by 'heal' (>= 1). Default 2. */
+  healRadiusFrames?: number;
+}
+
 /**
  * Detected beat
  */
@@ -655,6 +689,24 @@ export type MasteringProcessorParams = Record<string, number | boolean>;
 
 export type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
 
+/**
+ * Surround pan position for a strip feeding a >2-channel bus. Phase 1 honors
+ * `azimuth`/`divergence`/`lfe`; `elevation`/`distance` are reserved. All fields
+ * are optional and default to a centered point source.
+ */
+export interface SurroundPan {
+  /** -180..180 deg, 0 = front-center, positive = right. */
+  azimuth?: number;
+  /** Reserved (no height beds in phase 1). */
+  elevation?: number;
+  /** 0 = point source, 1 = spread across the front. */
+  divergence?: number;
+  /** 0..1 scalar send into the LFE plane. */
+  lfe?: number;
+  /** Reserved (focus/spread), defaults to 1. */
+  distance?: number;
+}
+
 export interface MixOptions {
   inputTrimDb?: number | number[];
   faderDb?: number | number[];