@libraz/libsonare 1.7.0 → 1.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "type": "module",
   "packageManager": "yarn@4.18.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",

package/src/_chain_config.ts

@@ -6,7 +6,12 @@ type ChainSection = { [key: string]: number | boolean | ChainSection | undefined
  * Flattens a nested {@link MasteringChainConfig} into the dot-notation
  * `{ "module.processor.param": value }` map the core consumes. Internal helper
  * shared by the mastering-chain / master-audio entry points. The core owns
- * legacy flat-key aliases, so this remains a structural flattening step.
+ * legacy leaf-name aliases, so this remains a structural flattening step.
+ *
+ * A key the caller already wrote in dot notation carries through untouched, so
+ * both spellings a {@link MasteringChainConfig} accepts reach the core as the
+ * same parameter — matching what the Python binding documents. An unknown key
+ * in either spelling is rejected by the core, not here.
  */
 export function flattenChainConfig(config: MasteringChainConfig): Record<string, number | boolean> {
   const out: Record<string, number | boolean> = {};

package/src/effects_mastering.ts

@@ -41,12 +41,16 @@ export type {
   MasteringRealtimeCost,
   MasteringSamplesParamsRequest,
   MasteringStereoAnalyzeRequest,
+  MasteringStereoParamsRequest,
   MasteringStreamingPreviewRequest,
+  MasteringStreamingPreviewStereoRequest,
 } from './mastering_core';
 export {
   mastering,
   masteringAssistantSuggest,
+  masteringAssistantSuggestStereo,
   masteringAudioProfile,
+  masteringAudioProfileStereo,
   masteringInsertNames,
   masteringInsertParamInfo,
   masteringInsertParamNames,
@@ -61,6 +65,7 @@ export {
   masteringStereoAnalysisNames,
   masteringStereoAnalyze,
   masteringStreamingPreview,
+  masteringStreamingPreviewStereo,
 } from './mastering_core';
 export type {
   CompressorDetector,

package/src/effects_transform.ts

@@ -6,6 +6,7 @@ import type {
   PitchCorrectOptions,
   SpectralEditOptions,
   SpectralRegionOp,
+  VoicedFlags,
 } from './public_types';
 import type { ValidateOptions } from './validation';
 import { assertSampleRate, assertSamples } from './validation';
@@ -14,6 +15,18 @@ function requireModule() {
   return getSonareModule();
 }
 
+// The embind layer reads the companion voicing array as Float32Array. A flag is
+// a decision, not a magnitude: collapse to 1/0 on truthiness, which is the same
+// reduction the Node facade applies, so both surfaces agree on every accepted
+// input type.
+function toVoicedFloat32(voiced: VoicedFlags): Float32Array {
+  const out = new Float32Array(voiced.length);
+  for (let index = 0; index < voiced.length; index += 1) {
+    out[index] = voiced[index] ? 1 : 0;
+  }
+  return out;
+}
+
 function resolveEffectFftOptions(
   fnName: string,
   nFft: unknown,
@@ -114,7 +127,7 @@ export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
   targetMidi: number;
   sampleRate?: number;
   hopLength?: number;
-  voiced?: Int32Array;
+  voiced?: VoicedFlags;
   voicedProb?: Float32Array;
 }
 
@@ -423,16 +436,18 @@ export function pitchCorrectToMidi(
  * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
  * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
  * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
- * flattened. `voiced` (non-zero = voiced) and `voicedProb` ([0,1]) are optional;
+ * flattened. `voiced` (truthy = voiced) and `voicedProb` ([0,1]) are optional;
  * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
- * when the corresponding `voiced` entry is zero, matching pYIN output.
+ * when the corresponding `voiced` entry is falsy, matching pYIN output. The
+ * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can be passed
+ * through directly.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
  * @param targetMidi - Desired MIDI note number
  * @param sampleRate - Sample rate in Hz
  * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
- * @param voiced - Optional per-frame voiced flags (non-zero = voiced)
+ * @param voiced - Optional per-frame voiced flags (truthy = voiced)
  * @param voicedProb - Optional per-frame voicing probability in [0, 1]
  * @returns Pitch-corrected audio
  */
@@ -445,7 +460,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi: number,
   sampleRate?: number,
   hopLength?: number,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options?: ValidateOptions,
 ): Float32Array;
@@ -455,7 +470,7 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi?: number,
   sampleRate = 22050,
   hopLength = 512,
-  voiced?: Int32Array,
+  voiced?: VoicedFlags,
   voicedProb?: Float32Array,
   options: ValidateOptions = {},
 ): Float32Array {
@@ -479,9 +494,7 @@ export function pitchCorrectToMidiTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
-  const voicedF32 = request.voiced ? Float32Array.from(request.voiced) : undefined;
+  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : undefined;
   return requireModule().pitchCorrectToMidiTimevarying(
     request.samples,
     request.sampleRate ?? 22050,
@@ -536,11 +549,9 @@ export function pitchCorrectTimevarying(
   if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
     throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
   }
-  // The embind layer reads the companion arrays as Float32Array (voiced uses
-  // 0.0/1.0); convert here so a single native conversion path suffices.
   const nativeOptions = {
     ...request,
-    voiced: request.voiced ? Float32Array.from(request.voiced) : undefined,
+    voiced: request.voiced ? toVoicedFloat32(request.voiced) : undefined,
   };
   return requireModule().pitchCorrectTimevarying(
     request.samples,

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,
@@ -375,6 +380,7 @@ export type {
 } from './metering';
 export {
   meteringCrestFactorDb,
+  meteringCrestFactorDbStereo,
   meteringDcOffset,
   meteringDetectClipping,
   meteringDynamicRange,
@@ -566,6 +572,7 @@ export type {
   TempogramMode,
   Timbre,
   TimeSignature,
+  VoicedFlags,
   VoicePresetId,
 } from './public_types';
 export {

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/project_types.ts

@@ -300,12 +300,11 @@ export interface SynthModRouting {
  *
  * The patch starts from a BASE — the named `preset` (see
  * {@link synthPresetNames}; a `"va:"` routing prefix is accepted) or, when
- * `preset` is omitted, the default subtractive patch. Every numeric field then
- * uses "0 / omit => keep the base value" (non-zero values override, clamped to
- * their audible ranges) and the enum fields reserve `'default'` as keep. The
- * frozen C ABI has no per-field presence bits, so explicit zero numeric
- * overrides (for example `ampSustain: 0`) cannot be represented; they keep the
- * base value. A non-empty `modRoutings` REPLACES the base mod matrix.
+ * `preset` is omitted, the default subtractive patch. Omitting a numeric field
+ * keeps the base value; supplying one overrides it (clamped to its audible
+ * range), including an explicit `0` such as `stereoSpread: 0`. The enum fields
+ * reserve `'default'` as keep. A `modRoutings` array REPLACES the base mod
+ * matrix, and an empty array clears it, while omitting the key keeps it.
  *
  * Mode-specific deep parameters (FM operator stacks, modal mode tables,
  * drawbar registrations, kit pieces, piano strings) travel inside the named
@@ -341,12 +340,10 @@ export interface SynthPatch {
   velToCutoffCents?: number;
   ampAttackMs?: number;
   ampDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   ampSustain?: number;
   ampReleaseMs?: number;
   filterAttackMs?: number;
   filterDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   filterSustain?: number;
   filterReleaseMs?: number;
   lfoRateHz?: number;

package/src/public_types_mastering.ts

@@ -352,6 +352,15 @@ export interface MasteringChainConfig {
     releaseMs?: number;
     applyGainAtInputRate?: boolean;
   };
+  /**
+   * Dot-notation spelling of any leaf above, e.g. `'loudness.targetLufs': -20`
+   * beside or instead of `loudness: { targetLufs: -20 }`. It is the form the C
+   * ABI carries parameters in, so a caller assembling overrides dynamically can
+   * emit it directly; the core validates the key and rejects an unknown one.
+   * The nested spelling is canonical — prefer it in hand-written code, where it
+   * is checked field by field while a dotted key is only checked at run time.
+   */
+  [flatKey: `${string}.${string}`]: number | boolean | undefined;
 }
 
 /**

package/src/public_types_spectral.ts

@@ -1,5 +1,19 @@
 import type { ValidateOptions } from './validation';
 
+/**
+ * Per-frame voicing decision, one entry per `f0Hz` frame. A truthy or non-zero
+ * entry marks the frame voiced. The union covers what the analysis side hands
+ * back — `PitchResult.voicedFlag` is a `boolean[]` — as well as the typed and
+ * plain numeric arrays a caller may build directly, so a pitch track can be fed
+ * straight into pitch correction without a conversion step.
+ */
+export type VoicedFlags =
+  | Int32Array
+  | Uint8Array
+  | Float32Array
+  | readonly number[]
+  | readonly boolean[];
+
 /** Options for `pitchCorrectTimevarying`. All fields are optional. */
 export interface PitchCorrectOptions extends ValidateOptions {
   /** `'midi'` retunes toward `targetMidi`; `'scale'` snaps to the key. Default `'midi'`. */
@@ -20,8 +34,8 @@ export interface PitchCorrectOptions extends ValidateOptions {
   retuneSpeedMs?: number;
   /** Corrections below this are bypassed to preserve vibrato (cents). Default 20. */
   vibratoThresholdCents?: number;
-  /** Per-frame voiced flags (non-zero = voiced); omit to treat all frames as voiced. */
-  voiced?: Int32Array;
+  /** Per-frame voiced flags (truthy = voiced); omit to treat all frames as voiced. */
+  voiced?: VoicedFlags;
   /** Per-frame voicing probability in `[0, 1]`; omit to derive from `voiced`. */
   voicedProb?: Float32Array;
 }

package/src/sonare.js.d.ts

@@ -1328,6 +1328,11 @@ export interface SonareModule {
     hopLength: number,
   ) => number;
   meteringCrestFactorDb: (samples: Float32Array, sampleRate: number) => number;
+  meteringCrestFactorDbStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+  ) => number;
   meteringDcOffset: (samples: Float32Array, sampleRate: number) => number;
   meteringTruePeakDb: (
     samples: Float32Array,
@@ -1693,6 +1698,24 @@ export interface SonareModule {
     sampleRate: number,
     platforms: Array<{ name: string; targetLufs: number; ceilingDb: number }>,
   ) => string;
+  masteringAssistantSuggestStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringAudioProfileStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringStreamingPreviewStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    platforms: Array<{ name: string; targetLufs: number; ceilingDb: number }>,
+  ) => string;
   masteringRepairDeclick: (
     samples: Float32Array,
     sampleRate: number,