@libraz/libsonare 1.5.2 → 1.5.3

package/src/index.ts

@@ -52,13 +52,33 @@ export type {
   DynamicsResult,
   GateOptions,
   MasteringChannelPolicy,
+  MasteringDynamicsCompressorRequest,
+  MasteringDynamicsGateRequest,
+  MasteringDynamicsTransientShaperRequest,
   MasteringInsertParamInfo,
+  MasteringPairAnalyzeRequest,
+  MasteringPairProcessRequest,
   MasteringProcessorCatalogEntry,
+  MasteringProcessRequest,
+  MasteringProcessStereoRequest,
+  MasteringRepairDeclickRequest,
+  MasteringRepairDeclipRequest,
+  MasteringRepairDecrackleRequest,
+  MasteringRepairDehumRequest,
+  MasteringRepairDenoiseClassicalRequest,
+  MasteringRepairDereverbClassicalRequest,
+  MasteringRepairTrimSilenceRequest,
+  MasteringSamplesParamsRequest,
+  MasteringStereoAnalyzeRequest,
+  MasteringStreamingPreviewRequest,
+  MixStereoRequest,
   TransientShaperOptions,
   TrimSilenceMode,
   TrimSilenceOptions,
   VoiceChangeOptions,
   VoiceChangeRealtimeOptions,
+  VoiceChangeRealtimeRequest,
+  VoiceChangeRequest,
 } from './effects_mastering';
 export {
   harmonic,
@@ -103,6 +123,7 @@ export {
   mixingScenePresetNames,
   mixStereo,
   normalize,
+  noteMove,
   noteStretch,
   percussive,
   pitchCorrectTimevarying,
@@ -114,8 +135,83 @@ export {
   voiceChange,
   voiceChangeRealtime,
 } from './effects_mastering';
+export type {
+  HarmonicRequest,
+  HpssRequest,
+  NormalizeRequest,
+  NoteMoveRequest,
+  NoteStretchRequest,
+  PercussiveRequest,
+  PitchCorrectTimevaryingRequest,
+  PitchCorrectToMidiRequest,
+  PitchCorrectToMidiTimevaryingRequest,
+  PitchShiftRequest,
+  SpectralEditRequest,
+  TimeStretchRequest,
+} from './effects_transform';
 export { ErrorCode, isSonareError, SonareError } from './errors';
-export type { MelodyOptions } from './feature_music';
+export type {
+  CyclicTempogramRequest,
+  DbConversionRequest,
+  EmphasisRequest,
+  FixFramesRequest,
+  FixLengthRequest,
+  FrameSignalRequest,
+  PadCenterRequest,
+  PcenRequest,
+  PeakPickRequest,
+  PlpRequest,
+  SilenceRequest,
+  TempogramRequest,
+  TonnetzRequest,
+  VectorNormalizeRequest,
+} from './feature_core';
+export type {
+  AnalyzeMelodyRequest,
+  AnalyzeSectionsRequest,
+  CqtRequest,
+  CqtToAudioRequest,
+  FourierTempogramRequest,
+  LufsRequest,
+  MelodyOptions,
+  NnlsChromaRequest,
+  OnsetEnvelopeRequest,
+  OnsetStrengthMultiRequest,
+  TempogramRatioRequest,
+  VqtRequest,
+  VqtToAudioRequest,
+} from './feature_music';
+export type { PitchPyinRequest, PitchYinRequest } from './feature_pitch';
+export type { ResampleRequest } from './feature_resample';
+export type {
+  DecomposeRequest,
+  DecomposeWithInitRequest,
+  Ebur128LoudnessRangeRequest,
+  EstimateTuningRequest,
+  HpssWithResidualRequest,
+  LufsInterleavedRequest,
+  NnFilterRequest,
+  PhaseVocoderRequest,
+  PitchTuningRequest,
+  PolyFeaturesRequest,
+  RemixRequest,
+  SpectralContrastRequest,
+  SpectralFrameRequest,
+  SpectralRolloffRequest,
+  ZeroCrossingRateRequest,
+  ZeroCrossingsRequest,
+} from './feature_spectral';
+export type {
+  ChromaSpectrogramRequest,
+  MelSpectrogramRequest,
+  MelToAudioRequest,
+  MelToStftRequest,
+  MfccRequest,
+  MfccToAudioRequest,
+  MfccToMelRequest,
+  SpectrogramRequest,
+  TrimRequest,
+} from './feature_spectrogram';
 export {
   amplitudeToDb,
   analyzeMelody,
@@ -200,19 +296,36 @@ export {
 } from './features';
 export type { BindMicrophoneInputOptions, MicrophoneInputBinding } from './live_audio';
 export { bindMicrophoneInput } from './live_audio';
+export type {
+  MasterAudioRequest,
+  MasterAudioStereoRequest,
+  MasteringChainRequest,
+  MasteringChainStereoRequest,
+} from './mastering_chain';
+export type { MasteringRequest } from './mastering_core';
 export type {
   ClippingRegion,
   ClippingReport,
   DynamicRangeReport,
   MeteringDetectClippingOptions,
+  MeteringDetectClippingRequest,
   MeteringDynamicRangeOptions,
+  MeteringDynamicRangeRequest,
+  MeteringSamplesRequest,
+  MeteringSpectrumFrameRequest,
+  MeteringSpectrumRequest,
+  MeteringStereoDecimatedRequest,
+  MeteringStereoRequest,
+  MeteringTruePeakRequest,
   PhaseScopeReport,
   SpectrumOptions,
   SpectrumReport,
   VectorscopeReport,
   WaveformPeakPyramidOptions,
+  WaveformPeakPyramidRequest,
   WaveformPeaksOptions,
   WaveformPeaksReport,
+  WaveformPeaksRequest,
 } from './metering';
 export {
   meteringCrestFactorDb,
@@ -334,6 +447,7 @@ export type {
   LufsResult,
   MasteringChainConfig,
   MasteringChainResult,
+  MasteringChainStereoResult,
   MasteringOptions,
   MasteringPreset,
   MasteringProcessorParams,
@@ -373,6 +487,7 @@ export type {
   SpectralEditOptions,
   SpectralEditWindow,
   SpectralRegionOp,
+  StageGainReduction,
   StereoAnalysis,
   StftPowerResult,
   StftResult,
@@ -393,10 +508,23 @@ export {
   SectionType,
 } from './public_types';
 export type {
+  AnalyzeBpmRequest,
+  AnalyzeDynamicsRequest,
+  AnalyzeImpulseResponseRequest,
+  AnalyzeRhythmRequest,
+  AnalyzeTimbreRequest,
+  AnalyzeWithProgressRequest,
   BpmAnalysisResult,
   BpmCandidate,
+  ChordFunctionalAnalysisRequest,
+  DetectAcousticRequest,
+  DetectChordsRequest,
+  DetectKeyRequest,
   DynamicsAnalysisResult,
+  EstimateRoomRequest,
   RhythmAnalysisResult,
+  RoomMorphRequest,
+  SamplesRequest,
   TimbreAnalysisResult,
   TimbreFrame,
 } from './quick_analysis';
@@ -423,6 +551,7 @@ export {
   synthesizeRir,
 } from './quick_analysis';
 export type {
+  ClipPageRequest,
   EngineAutomationPoint,
   EngineBounceOptions,
   EngineBounceResult,

package/src/mastering_chain.ts

@@ -1,9 +1,10 @@
+import { flattenChainConfig } from './_chain_config';
 import { getSonareModule } from './module_state';
 import type {
   MasteringChainConfig,
   MasteringChainResult,
+  MasteringChainStereoResult,
   MasteringPreset,
-  MasteringStereoChainResult,
 } from './public_types';
 import type { ProgressCallback } from './sonare.js';
 
@@ -11,6 +12,85 @@ function requireModule() {
   return getSonareModule();
 }
 
+/** Internal envelope selecting the core dotted-param parser in the embind layer. */
+function canonicalChainConfig(config: MasteringChainConfig): Record<string, unknown> {
+  return { __flatParams: flattenChainConfig(config) };
+}
+
+export interface MasteringChainRequest {
+  samples: Float32Array;
+  sampleRate?: number;
+  config?: MasteringChainConfig;
+  onProgress?: ProgressCallback;
+}
+
+export interface MasteringChainStereoRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  config?: MasteringChainConfig;
+  onProgress?: ProgressCallback;
+}
+
+/** Canonical request form for one-shot preset mastering. */
+export interface MasterAudioRequest {
+  samples: Float32Array;
+  sampleRate?: number;
+  preset?: MasteringPreset;
+  overrides?: MasteringChainConfig;
+  onProgress?: ProgressCallback;
+}
+
+/** Canonical request form for one-shot stereo preset mastering. */
+export interface MasterAudioStereoRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  preset?: MasteringPreset;
+  overrides?: MasteringChainConfig;
+  onProgress?: ProgressCallback;
+}
+
+function masterAudioRequest(
+  requestOrSamples: MasterAudioRequest | Float32Array,
+  sampleRate: number,
+  preset: MasteringPreset,
+  overrides: MasteringChainConfig | null,
+  onProgress?: ProgressCallback,
+): MasterAudioRequest {
+  if (requestOrSamples instanceof Float32Array) {
+    return {
+      samples: requestOrSamples,
+      sampleRate,
+      preset,
+      overrides: overrides ?? {},
+      onProgress,
+    };
+  }
+  return requestOrSamples;
+}
+
+function masterAudioStereoRequest(
+  requestOrLeft: MasterAudioStereoRequest | Float32Array,
+  right: Float32Array | undefined,
+  sampleRate: number,
+  preset: MasteringPreset,
+  overrides: MasteringChainConfig | null,
+  onProgress?: ProgressCallback,
+): MasterAudioStereoRequest {
+  if (requestOrLeft instanceof Float32Array) {
+    return {
+      left: requestOrLeft,
+      right: right as Float32Array,
+      sampleRate,
+      preset,
+      overrides: overrides ?? {},
+      onProgress,
+    };
+  }
+  return requestOrLeft;
+}
+
 /**
  * Apply a configurable mastering chain in WASM.
  *
@@ -19,12 +99,34 @@ function requireModule() {
  * @param config - Chain stage configuration
  * @returns Processed audio, loudness metadata, and applied stage names
  */
+export function masteringChain(request: MasteringChainRequest): MasteringChainResult;
 export function masteringChain(
   samples: Float32Array,
+  sampleRate?: number,
+  config?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainResult;
+export function masteringChain(
+  samples: Float32Array | MasteringChainRequest,
   sampleRate = 22050,
-  config: MasteringChainConfig,
+  config: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
 ): MasteringChainResult {
-  return requireModule().masteringChain(samples, sampleRate, config as Record<string, unknown>);
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, config, onProgress } : samples;
+  if (request.onProgress) {
+    return requireModule().masteringChainWithProgress(
+      request.samples,
+      request.sampleRate ?? 22050,
+      canonicalChainConfig(request.config ?? {}),
+      request.onProgress,
+    );
+  }
+  return requireModule().masteringChain(
+    request.samples,
+    request.sampleRate ?? 22050,
+    canonicalChainConfig(request.config ?? {}),
+  );
 }
 
 /**
@@ -36,20 +138,44 @@ export function masteringChain(
  * @param config - Chain stage configuration
  * @returns Processed stereo audio, loudness metadata, and applied stage names
  */
+export function masteringChainStereo(
+  request: MasteringChainStereoRequest,
+): MasteringChainStereoResult;
 export function masteringChainStereo(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  config?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult;
+export function masteringChainStereo(
+  left: Float32Array | MasteringChainStereoRequest,
+  right?: Float32Array,
   sampleRate = 22050,
-  config: MasteringChainConfig,
-): MasteringStereoChainResult {
-  if (left.length !== right.length) {
+  config: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult {
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, config, onProgress }
+      : left;
+  if (request.left.length !== request.right.length) {
     throw new Error('Stereo channel lengths must match.');
   }
+  if (request.onProgress) {
+    return requireModule().masteringChainStereoWithProgress(
+      request.left,
+      request.right,
+      request.sampleRate ?? 22050,
+      canonicalChainConfig(request.config ?? {}),
+      request.onProgress,
+    );
+  }
   return requireModule().masteringChainStereo(
-    left,
-    right,
-    sampleRate,
-    config as Record<string, unknown>,
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    canonicalChainConfig(request.config ?? {}),
   );
 }
 
@@ -62,17 +188,31 @@ export function masteringChainStereo(
  * @param onProgress - Progress callback (progress: 0-1, stage: string)
  * @returns Processed audio, loudness metadata, and applied stage names
  */
+export function masteringChainWithProgress(
+  request: MasteringChainRequest & Required<Pick<MasteringChainRequest, 'onProgress'>>,
+): MasteringChainResult;
 export function masteringChainWithProgress(
   samples: Float32Array,
+  sampleRate?: number,
+  config?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainResult;
+export function masteringChainWithProgress(
+  samples: Float32Array | MasteringChainRequest,
   sampleRate = 22050,
-  config: MasteringChainConfig,
-  onProgress: ProgressCallback,
+  config: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
 ): MasteringChainResult {
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, config, onProgress } : samples;
+  if (!request.onProgress) {
+    throw new TypeError('masteringChainWithProgress: onProgress is required');
+  }
   return requireModule().masteringChainWithProgress(
-    samples,
-    sampleRate,
-    config as Record<string, unknown>,
-    onProgress,
+    request.samples,
+    request.sampleRate ?? 22050,
+    canonicalChainConfig(request.config ?? {}),
+    request.onProgress,
   );
 }
 
@@ -86,22 +226,39 @@ export function masteringChainWithProgress(
  * @param onProgress - Progress callback (progress: 0-1, stage: string)
  * @returns Processed stereo audio, loudness metadata, and applied stage names
  */
+export function masteringChainStereoWithProgress(
+  request: MasteringChainStereoRequest & Required<Pick<MasteringChainStereoRequest, 'onProgress'>>,
+): MasteringChainStereoResult;
 export function masteringChainStereoWithProgress(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  config?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult;
+export function masteringChainStereoWithProgress(
+  left: Float32Array | MasteringChainStereoRequest,
+  right?: Float32Array,
   sampleRate = 22050,
-  config: MasteringChainConfig,
-  onProgress: ProgressCallback,
-): MasteringStereoChainResult {
-  if (left.length !== right.length) {
+  config: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult {
+  const request =
+    left instanceof Float32Array
+      ? { left, right: right as Float32Array, sampleRate, config, onProgress }
+      : left;
+  if (!request.onProgress) {
+    throw new TypeError('masteringChainStereoWithProgress: onProgress is required');
+  }
+  if (request.left.length !== request.right.length) {
     throw new Error('Stereo channel lengths must match.');
   }
   return requireModule().masteringChainStereoWithProgress(
-    left,
-    right,
-    sampleRate,
-    config as Record<string, unknown>,
-    onProgress,
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    canonicalChainConfig(request.config ?? {}),
+    request.onProgress,
   );
 }
 
@@ -120,16 +277,42 @@ export function masteringPresetNames(): MasteringPreset[] {
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)
  * @param presetName - Preset identifier from {@link masteringPresetNames}
- * @param overrides - Optional flat overrides (dot-notation, e.g. `'loudness.targetLufs'`) applied on top of the preset. Pass `null` for preset defaults.
+ * @param overrides - Optional nested {@link MasteringChainConfig} applied on top of the preset (e.g. `{ loudness: { targetLufs: -14 } }`). Pass `null` for preset defaults.
+ * @param onProgress - Optional per-stage progress callback (progress: 0-1, stage: string).
  * @returns Processed audio, loudness metadata, and applied stage names
  */
+export function masterAudio(request: MasterAudioRequest): MasteringChainResult;
 export function masterAudio(
   samples: Float32Array,
+  sampleRate?: number,
+  presetName?: MasteringPreset,
+  overrides?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainResult;
+export function masterAudio(
+  samples: MasterAudioRequest | Float32Array,
   sampleRate = 22050,
   presetName: MasteringPreset = 'pop',
-  overrides: Record<string, number | boolean> = {},
+  overrides: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
 ): MasteringChainResult {
-  return requireModule().masterAudio(presetName, samples, sampleRate, overrides);
+  const request = masterAudioRequest(samples, sampleRate, presetName, overrides, onProgress);
+  const flat = flattenChainConfig(request.overrides ?? {});
+  if (request.onProgress) {
+    return requireModule().masterAudioWithProgress(
+      request.preset ?? 'pop',
+      request.samples,
+      request.sampleRate ?? 22050,
+      flat,
+      request.onProgress,
+    );
+  }
+  return requireModule().masterAudio(
+    request.preset ?? 'pop',
+    request.samples,
+    request.sampleRate ?? 22050,
+    flat,
+  );
 }
 
 /**
@@ -139,62 +322,134 @@ export function masterAudio(
  * @param right - Right channel samples
  * @param sampleRate - Sample rate in Hz
  * @param presetName - Preset identifier from {@link masteringPresetNames}
- * @param overrides - Optional flat overrides (dot-notation, e.g. `'loudness.targetLufs'`) applied on top of the preset. Pass `null` for preset defaults.
+ * @param overrides - Optional nested {@link MasteringChainConfig} applied on top of the preset (e.g. `{ loudness: { targetLufs: -14 } }`). Pass `null` for preset defaults.
+ * @param onProgress - Optional per-stage progress callback (progress: 0-1, stage: string).
  * @returns Processed stereo audio, loudness metadata, and applied stage names
  */
+export function masterAudioStereo(request: MasterAudioStereoRequest): MasteringChainStereoResult;
 export function masterAudioStereo(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  presetName?: MasteringPreset,
+  overrides?: MasteringChainConfig,
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult;
+export function masterAudioStereo(
+  left: MasterAudioStereoRequest | Float32Array,
+  right: Float32Array | undefined = undefined,
   sampleRate = 22050,
   presetName: MasteringPreset = 'pop',
-  overrides: Record<string, number | boolean> = {},
-): MasteringStereoChainResult {
-  if (left.length !== right.length) {
+  overrides: MasteringChainConfig = {},
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult {
+  const request = masterAudioStereoRequest(
+    left,
+    right,
+    sampleRate,
+    presetName,
+    overrides,
+    onProgress,
+  );
+  const flat = flattenChainConfig(request.overrides ?? {});
+  if (request.left.length !== request.right.length) {
     throw new Error('Stereo channel lengths must match.');
   }
-  return requireModule().masterAudioStereo(presetName, left, right, sampleRate, overrides);
+  if (request.onProgress) {
+    return requireModule().masterAudioStereoWithProgress(
+      request.preset ?? 'pop',
+      request.left,
+      request.right,
+      request.sampleRate ?? 22050,
+      flat,
+      request.onProgress,
+    );
+  }
+  return requireModule().masterAudioStereo(
+    request.preset ?? 'pop',
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    flat,
+  );
 }
 
 /**
  * Mono `masterAudio` with per-stage progress reporting. `onProgress` is invoked
  * with `(progress, stage)` between each chain stage (progress is in [0,1]).
  */
+export function masterAudioWithProgress(
+  request: MasterAudioRequest & Required<Pick<MasterAudioRequest, 'onProgress'>>,
+): MasteringChainResult;
 export function masterAudioWithProgress(
   samples: Float32Array,
+  sampleRate?: number,
+  presetName?: MasteringPreset,
+  overrides?: MasteringChainConfig | null,
+  onProgress?: ProgressCallback,
+): MasteringChainResult;
+export function masterAudioWithProgress(
+  samples: MasterAudioRequest | Float32Array,
   sampleRate = 22050,
-  presetName: MasteringPreset,
-  onProgress: ProgressCallback,
-  overrides: Record<string, number | boolean> | null = null,
+  presetName: MasteringPreset = 'pop',
+  overrides: MasteringChainConfig | null = null,
+  onProgress?: ProgressCallback,
 ): MasteringChainResult {
+  const request = masterAudioRequest(samples, sampleRate, presetName, overrides, onProgress);
+  if (!request.onProgress) {
+    throw new TypeError('masterAudioWithProgress: onProgress is required');
+  }
   return requireModule().masterAudioWithProgress(
-    presetName,
-    samples,
-    sampleRate,
-    overrides,
-    onProgress,
+    request.preset ?? 'pop',
+    request.samples,
+    request.sampleRate ?? 22050,
+    flattenChainConfig(request.overrides ?? {}),
+    request.onProgress,
   );
 }
 
 /**
  * Stereo `masterAudio` with per-stage progress reporting.
  */
+export function masterAudioStereoWithProgress(
+  request: MasterAudioStereoRequest & Required<Pick<MasterAudioStereoRequest, 'onProgress'>>,
+): MasteringChainStereoResult;
 export function masterAudioStereoWithProgress(
   left: Float32Array,
   right: Float32Array,
+  sampleRate?: number,
+  presetName?: MasteringPreset,
+  overrides?: MasteringChainConfig | null,
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult;
+export function masterAudioStereoWithProgress(
+  left: MasterAudioStereoRequest | Float32Array,
+  right: Float32Array | undefined = undefined,
   sampleRate = 22050,
-  presetName: MasteringPreset,
-  onProgress: ProgressCallback,
-  overrides: Record<string, number | boolean> | null = null,
-): MasteringStereoChainResult {
-  if (left.length !== right.length) {
-    throw new Error('Stereo channel lengths must match.');
-  }
-  return requireModule().masterAudioStereoWithProgress(
-    presetName,
+  presetName: MasteringPreset = 'pop',
+  overrides: MasteringChainConfig | null = null,
+  onProgress?: ProgressCallback,
+): MasteringChainStereoResult {
+  const request = masterAudioStereoRequest(
     left,
     right,
     sampleRate,
+    presetName,
     overrides,
     onProgress,
   );
+  if (!request.onProgress) {
+    throw new TypeError('masterAudioStereoWithProgress: onProgress is required');
+  }
+  if (request.left.length !== request.right.length) {
+    throw new Error('Stereo channel lengths must match.');
+  }
+  return requireModule().masterAudioStereoWithProgress(
+    request.preset ?? 'pop',
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    flattenChainConfig(request.overrides ?? {}),
+    request.onProgress,
+  );
 }