@libraz/libsonare 1.6.0 → 1.7.1

package/src/feature_music.ts

@@ -103,6 +103,7 @@ export interface NnlsChromaRequest extends GuardedOptions {
   enableStftBlend?: boolean;
   stftBlendWeight?: number;
   stftBlendNFft?: number;
+  hopLength?: number;
 }
 
 function validateMusicSamples(
@@ -156,12 +157,18 @@ export function nnlsChroma(
     return nnlsChroma(samples.samples, samples.sampleRate, samples);
   }
   validateMusicSamples('nnlsChroma', samples, sampleRate, options);
-  return requireModule().nnlsChroma(
+  const hopLength = options.hopLength === undefined ? 512 : options.hopLength;
+  assertPositiveInteger('nnlsChroma', hopLength, 'hopLength');
+  if (hopLength > 2 ** 31 - 1) {
+    throw new RangeError('nnlsChroma: hopLength must fit in a signed 32-bit integer');
+  }
+  return requireModule().nnlsChromaEx(
     samples,
     sampleRate,
     options.enableStftBlend ?? true,
     options.stftBlendWeight ?? 0.55,
     options.stftBlendNFft ?? 4096,
+    hopLength,
   );
 }
 

package/src/feature_spectral.ts

@@ -19,6 +19,41 @@ function requireModule() {
   return getSonareModule();
 }
 
+function resolveEffectFftOptions(
+  fnName: string,
+  nFft: unknown,
+  hopLength: unknown,
+): { nFft: number; hopLength: number } {
+  const resolvedNFft = nFft === undefined ? 2048 : nFft;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  if (typeof resolvedNFft !== 'number' || !Number.isInteger(resolvedNFft)) {
+    throw new TypeError(`${fnName}: nFft must be an integer`);
+  }
+  if (resolvedNFft < 2 || resolvedNFft > 2 ** 30) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if ((resolvedNFft & (resolvedNFft - 1)) !== 0) {
+    throw new RangeError(`${fnName}: nFft must be an even power of two >= 2`);
+  }
+  if (typeof resolvedHopLength !== 'number' || !Number.isInteger(resolvedHopLength)) {
+    throw new TypeError(`${fnName}: hopLength must be an integer`);
+  }
+  if (resolvedHopLength <= 0 || resolvedHopLength > 2 ** 31 - 1) {
+    throw new RangeError(`${fnName}: hopLength must be a positive integer`);
+  }
+  return { nFft: resolvedNFft, hopLength: resolvedHopLength };
+}
+
+function resolveHardMask(fnName: string, value: unknown): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${fnName}: hardMask must be a boolean`);
+  }
+  return value;
+}
+
 /** Canonical request form for frame-based spectral feature extraction. */
 export interface SpectralFrameRequest {
   samples: Float32Array;
@@ -166,6 +201,9 @@ export interface HpssWithResidualRequest {
   sampleRate?: number;
   kernelHarmonic?: number;
   kernelPercussive?: number;
+  nFft?: number;
+  hopLength?: number;
+  hardMask?: boolean;
 }
 export interface LufsInterleavedRequest extends ValidateOptions {
   samples: Float32Array;
@@ -542,18 +580,42 @@ export function hpssWithResidual(
   sampleRate?: number,
   kernelHarmonic?: number,
   kernelPercussive?: number,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): WasmHpssWithResidualResult;
 export function hpssWithResidual(
   samples: Float32Array | HpssWithResidualRequest,
   sampleRate = 22050,
   kernelHarmonic = 31,
   kernelPercussive = 31,
+  nFft?: number,
+  hopLength?: number,
+  hardMask?: boolean,
 ): WasmHpssWithResidualResult {
   if (!(samples instanceof Float32Array)) {
     const r = samples;
-    return hpssWithResidual(r.samples, r.sampleRate, r.kernelHarmonic, r.kernelPercussive);
+    return hpssWithResidual(
+      r.samples,
+      r.sampleRate,
+      r.kernelHarmonic,
+      r.kernelPercussive,
+      r.nFft,
+      r.hopLength,
+      r.hardMask,
+    );
   }
-  return requireModule().hpssWithResidual(samples, sampleRate, kernelHarmonic, kernelPercussive);
+  const fftOptions = resolveEffectFftOptions('hpssWithResidual', nFft, hopLength);
+  const resolvedHardMask = resolveHardMask('hpssWithResidual', hardMask);
+  return requireModule().hpssWithResidualEx(
+    samples,
+    sampleRate,
+    kernelHarmonic,
+    kernelPercussive,
+    fftOptions.nFft,
+    fftOptions.hopLength,
+    resolvedHardMask,
+  );
 }
 
 /**

package/src/feature_spectrogram.ts

@@ -113,6 +113,8 @@ export interface TrimRequest extends GuardedOptions {
   samples: Float32Array;
   sampleRate: number;
   thresholdDb?: number;
+  frameLength?: number;
+  hopLength?: number;
 }
 
 function validateSpectrogramSamples(
@@ -183,19 +185,58 @@ export function trim(
   thresholdDb?: number,
   options?: GuardedOptions,
 ): Float32Array;
+export function trim(
+  samples: Float32Array,
+  sampleRate: number,
+  thresholdDb?: number,
+  frameLength?: number,
+  hopLength?: number,
+  options?: GuardedOptions,
+): Float32Array;
 export function trim(
   samples: Float32Array | TrimRequest,
   sampleRate = 22050,
   thresholdDb = -60.0,
+  frameLengthOrOptions?: number | GuardedOptions,
+  hopLength?: number,
   options: GuardedOptions = {},
 ): Float32Array {
   if (!(samples instanceof Float32Array)) {
     const r = samples;
-    return trim(r.samples, r.sampleRate, r.thresholdDb, r);
+    return trim(r.samples, r.sampleRate, r.thresholdDb, r.frameLength, r.hopLength, r);
+  }
+  if (frameLengthOrOptions === null) {
+    throw new TypeError('trim: frameLength must be an integer or options object');
   }
-  validateSpectrogramSamples('trim', samples, sampleRate, options);
+  if (
+    frameLengthOrOptions !== undefined &&
+    typeof frameLengthOrOptions !== 'number' &&
+    typeof frameLengthOrOptions !== 'object'
+  ) {
+    throw new TypeError('trim: frameLength must be an integer or options object');
+  }
+  const positionalOptions =
+    typeof frameLengthOrOptions === 'object' && frameLengthOrOptions !== null
+      ? frameLengthOrOptions
+      : options;
+  const positionalFrameLength =
+    typeof frameLengthOrOptions === 'number' ? frameLengthOrOptions : undefined;
+  const resolvedFrameLength = positionalFrameLength ?? 2048;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  validateSpectrogramSamples('trim', samples, sampleRate, positionalOptions);
   assertFiniteScalar('trim', thresholdDb, 'thresholdDb');
-  return requireModule().trim(samples, sampleRate, thresholdDb);
+  assertPositiveInteger('trim', resolvedFrameLength, 'frameLength');
+  assertPositiveInteger('trim', resolvedHopLength, 'hopLength');
+  if (resolvedFrameLength > 2 ** 31 - 1 || resolvedHopLength > 2 ** 31 - 1) {
+    throw new RangeError('trim: frameLength and hopLength must fit in a signed 32-bit integer');
+  }
+  return requireModule().trimEx(
+    samples,
+    sampleRate,
+    thresholdDb,
+    resolvedFrameLength,
+    resolvedHopLength,
+  );
 }
 
 // ============================================================================

package/src/index.ts

@@ -78,7 +78,9 @@ export type {
   MasteringRepairTrimSilenceRequest,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
+  MasteringStereoParamsRequest,
   MasteringStreamingPreviewRequest,
+  MasteringStreamingPreviewStereoRequest,
   MixStereoRequest,
   TransientShaperOptions,
   TrimSilenceMode,
@@ -97,7 +99,9 @@ export {
   masterAudioWithProgress,
   mastering,
   masteringAssistantSuggest,
+  masteringAssistantSuggestStereo,
   masteringAudioProfile,
+  masteringAudioProfileStereo,
   masteringChain,
   masteringChainStereo,
   masteringChainStereoWithProgress,
@@ -127,6 +131,7 @@ export {
   masteringStereoAnalysisNames,
   masteringStereoAnalyze,
   masteringStreamingPreview,
+  masteringStreamingPreviewStereo,
   mixingScenePresetJson,
   mixingScenePresetNames,
   mixStereo,
@@ -146,6 +151,7 @@ export {
 export type {
   HarmonicRequest,
   HpssRequest,
+  NormalizeMode,
   NormalizeRequest,
   NoteMoveRequest,
   NoteStretchRequest,
@@ -374,6 +380,7 @@ export type {
 } from './metering';
 export {
   meteringCrestFactorDb,
+  meteringCrestFactorDbStereo,
   meteringDcOffset,
   meteringDetectClipping,
   meteringDynamicRange,
@@ -410,9 +417,11 @@ export type {
   ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
+  ProjectAssistSidecarInput,
   ProjectAutomationCurve,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
   ProjectClip,
@@ -451,9 +460,13 @@ export type {
   SynthPatch,
 } from './project';
 export {
+  AutomationTargetKind,
   BUILTIN_SYNTH_WAVEFORMS,
   EXPECTED_PROJECT_ABI_VERSION,
   MarkerKind,
+  PROJECT_AUTOMATION_TARGET_OPAQUE,
+  PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB,
+  PROJECT_AUTOMATION_TARGET_TRACK_PAN,
   Project,
   projectAbiVersion,
   SYNTH_BODY_TYPES,
@@ -525,6 +538,8 @@ export type {
   PairAnalysis,
   PairProcessor,
   PanLaw,
+  PanLawInput,
+  PanLawName,
   PanMode,
   PitchCorrectOptions,
   PitchResult,
@@ -557,6 +572,7 @@ export type {
   TempogramMode,
   Timbre,
   TimeSignature,
+  VoicedFlags,
   VoicePresetId,
 } from './public_types';
 export {
@@ -636,10 +652,12 @@ export type {
   EngineTempoSegment,
   EngineTimeSignatureSegment,
   EngineTrackLane,
+  EngineTrackMonitorMode,
   EngineTrackSend,
   EngineTransportState,
   ExternalMidiEvent,
   MidiCcBindOptions,
+  TrackMonitorMode,
 } from './realtime_engine';
 export {
   ClipPageProvider,
@@ -840,13 +858,20 @@ function resolveVoicePresetOrdinal(preset: VoicePresetId | number): number {
 
 /**
  * Map a voice-character preset ordinal (or canonical id) to its canonical id
- * string (e.g. `'bright-idol'`). Invalid ordinals throw.
+ * string (e.g. `'bright-idol'`). Unknown numeric ordinals return `null`;
+ * unknown preset ids throw.
  */
-export function voiceCharacterPresetId(preset: VoicePresetId | number): string {
+export function voiceCharacterPresetId(preset: VoicePresetId | number): VoicePresetId | null {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
-  return module.voiceCharacterPresetId(resolveVoicePresetOrdinal(preset));
+  if (
+    typeof preset === 'number' &&
+    (!Number.isSafeInteger(preset) || preset < 0 || preset >= VOICE_PRESET_ORDINALS.length)
+  ) {
+    return null;
+  }
+  return module.voiceCharacterPresetId(resolveVoicePresetOrdinal(preset)) as VoicePresetId;
 }
 
 /**

package/src/mastering_core.ts

@@ -77,6 +77,22 @@ export interface MasteringStreamingPreviewRequest {
   platforms?: StreamingPlatform[];
 }
 
+/** Canonical request form for the stereo analysis entry points. */
+export interface MasteringStereoParamsRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  params?: MasteringProcessorParams;
+}
+
+/** Canonical request form for the stereo streaming-platform preview. */
+export interface MasteringStreamingPreviewStereoRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  platforms?: StreamingPlatform[];
+}
+
 /**
  * Apply mastering loudness normalization with a true-peak ceiling.
  *
@@ -479,3 +495,57 @@ export function masteringStreamingPreview(
     request.platforms ?? [],
   );
 }
+
+/**
+ * Suggest a mastering chain for a stereo pair, as shared JSON.
+ *
+ * Profiles through {@link masteringAudioProfileStereo}, so the loudness stage
+ * of the suggestion is built on the channel-summed program rather than a
+ * downmix that reads roughly 6 dB low.
+ */
+export function masteringAssistantSuggestStereo(request: MasteringStereoParamsRequest): string {
+  return requireModule().masteringAssistantSuggestStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
+/**
+ * Mastering assistant profile of a stereo pair, as shared JSON.
+ *
+ * Only the `loudness` block is measured from the two channels: integrated LUFS
+ * and LRA come from the channel-summed program and the true peak is the larger
+ * of the two. The spectral, dynamics and tempo fields describe shape and timing
+ * rather than absolute level and are measured on the downmix, which keeps them
+ * comparable with {@link masteringAudioProfile}.
+ */
+export function masteringAudioProfileStereo(request: MasteringStereoParamsRequest): string {
+  return requireModule().masteringAudioProfileStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
+/**
+ * Preview streaming-platform normalization for a stereo pair, as shared JSON.
+ *
+ * Measures the integrated loudness with BS.1770 channel summing and reports the
+ * larger of the two channel true peaks. Passing a `0.5 * (left + right)` downmix
+ * to {@link masteringStreamingPreview} instead reads roughly 6 dB low on
+ * decorrelated material, and both the normalization gain and the ceiling-risk
+ * flag follow from that measurement.
+ */
+export function masteringStreamingPreviewStereo(
+  request: MasteringStreamingPreviewStereoRequest,
+): string {
+  return requireModule().masteringStreamingPreviewStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.platforms ?? [],
+  );
+}

package/src/metering.ts

@@ -186,6 +186,24 @@ export function meteringCrestFactorDb(
   return requireModule().meteringCrestFactorDb(request.samples, request.sampleRate ?? 22050);
 }
 
+/**
+ * Crest factor in dB across both channels of a stereo pair.
+ *
+ * Takes the peak across both channels and the RMS over both together. An
+ * out-of-phase pair cancels in the `0.5 * (left + right)` downmix
+ * {@link meteringCrestFactorDb} would need, which understates its RMS and so
+ * overstates the crest factor.
+ */
+export function meteringCrestFactorDbStereo(request: MeteringStereoRequest): number {
+  assertSamples('meteringCrestFactorDbStereo', request.left, request.validate !== false);
+  assertSamples('meteringCrestFactorDbStereo', request.right, request.validate !== false);
+  return requireModule().meteringCrestFactorDbStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+  );
+}
+
 export function meteringDcOffset(request: MeteringSamplesRequest): number;
 export function meteringDcOffset(
   samples: Float32Array,

package/src/mixer.ts

@@ -12,7 +12,7 @@ import type {
   MeterTap,
   MixerProcessResult,
   MixMeterSnapshot,
-  PanLaw,
+  PanLawInput,
   PanMode,
   SendTiming,
   SurroundPan,
@@ -336,8 +336,8 @@ export class Mixer {
     this.mixer.setPolarityInvert(stripIndex, invertLeft, invertRight);
   }
 
-  /** Set the strip's pan law. */
-  setPanLaw(stripIndex: number, panLaw: PanLaw | number): void {
+  /** Set the strip's pan law (a {@link PanLawName} alias or raw C ABI ordinal). */
+  setPanLaw(stripIndex: number, panLaw: PanLawInput): void {
     this.mixer.setPanLaw(stripIndex, panLawCode(panLaw));
   }
 

package/src/project.ts

@@ -15,9 +15,11 @@ export type {
   ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
+  ProjectAssistSidecarInput,
   ProjectAutomationCurve,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
   ProjectClip,
@@ -65,9 +67,13 @@ export type {
   SynthPatch,
 } from './project_types';
 export {
+  AutomationTargetKind,
   BUILTIN_SYNTH_WAVEFORMS,
   EXPECTED_PROJECT_ABI_VERSION,
   MarkerKind,
+  PROJECT_AUTOMATION_TARGET_OPAQUE,
+  PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB,
+  PROJECT_AUTOMATION_TARGET_TRACK_PAN,
   SYNTH_BODY_TYPES,
   SYNTH_ENGINE_MODES,
   SYNTH_FILTER_MODELS,