@libraz/libsonare 1.7.2 → 1.8.0

package/src/mastering_chain.ts

@@ -7,11 +7,170 @@ import type {
   MasteringPreset,
 } from './public_types';
 import type { ProgressCallback } from './sonare.js';
+import type { ValidateOptions } from './validation';
+import { assertSamples } from './validation';
 
 function requireModule() {
   return getSonareModule();
 }
 
+export type NormalizeMode = 'peak' | 'rms';
+
+// `context` is the calling entry point's name: the refusal is about that
+// caller's argument, so naming a fixed one would send a normalizeStereo user
+// looking at normalize.
+function resolveNormalizeMode(value: unknown, context = 'normalize'): NormalizeMode {
+  if (value === undefined) {
+    return 'peak';
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError(`${context}: mode must be the string 'peak' or 'rms'`);
+  }
+  if (value !== 'peak' && value !== 'rms') {
+    throw new RangeError(`${context}: mode must be the string 'peak' or 'rms'`);
+  }
+  return value;
+}
+
+export interface NormalizeRequest extends ValidateOptions {
+  samples: Float32Array;
+  sampleRate?: number;
+  targetDb?: number;
+  mode?: NormalizeMode;
+}
+
+/**
+ * Normalize audio to a target peak or RMS level.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale).
+ *   For `mode: 'peak'`, this is the peak target; for `mode: 'rms'`, this is the RMS target.
+ * @param mode - Normalization mode: `'peak'` (default) or `'rms'`.
+ * @returns Normalized audio
+ */
+export function normalize(request: NormalizeRequest): Float32Array;
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb?: number,
+  options?: ValidateOptions,
+): Float32Array;
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb?: number,
+  mode?: NormalizeMode,
+  options?: ValidateOptions,
+): Float32Array;
+export function normalize(
+  samples: Float32Array | NormalizeRequest,
+  sampleRate?: number,
+  targetDb = 0.0,
+  modeOrOptions: NormalizeMode | ValidateOptions = 'peak',
+  options: ValidateOptions = {},
+): Float32Array {
+  if (
+    modeOrOptions !== undefined &&
+    modeOrOptions !== null &&
+    typeof modeOrOptions !== 'string' &&
+    typeof modeOrOptions !== 'object'
+  ) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  if (modeOrOptions === null) {
+    throw new TypeError("normalize: mode must be the string 'peak' or 'rms'");
+  }
+  const positionalOptions =
+    typeof modeOrOptions === 'object' && modeOrOptions !== null ? modeOrOptions : options;
+  const positionalMode = typeof modeOrOptions === 'string' ? modeOrOptions : undefined;
+  const request: NormalizeRequest =
+    samples instanceof Float32Array
+      ? { samples, sampleRate, targetDb, mode: positionalMode, ...positionalOptions }
+      : samples;
+  assertSamples('normalize', request.samples, request.validate !== false);
+  const mode = resolveNormalizeMode(request.mode);
+  return requireModule().normalizeEx(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.targetDb ?? 0.0,
+    mode,
+  );
+}
+
+export interface NormalizeStereoRequest extends ValidateOptions {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  targetDb?: number;
+  mode?: NormalizeMode;
+}
+
+/** A normalized channel pair and the gain both channels were moved by. */
+export interface NormalizeStereoResult {
+  left: Float32Array;
+  right: Float32Array;
+  /**
+   * One figure rather than a pair: the gain is one decision shared by both
+   * channels. Silence leaves the pair untouched and reports 0.
+   */
+  appliedGainDb: number;
+}
+
+/**
+ * Normalize a stereo pair on a gain measured across both channels.
+ *
+ * Normalizing the two channels separately lifts the quieter one until the peaks
+ * match, which changes the balance rather than the level. The level here is read
+ * from the pair and the resulting gain goes to both channels, so the image is
+ * preserved: for `mode: 'peak'` the louder channel reaches `targetDb` and the
+ * other keeps its distance from it; for `mode: 'rms'` the quantity driven to
+ * `targetDb` is the root mean square over both channels' samples together — the
+ * quadratic mean of the per-channel figures, not their average — and the output
+ * is hard-clipped to [-1, 1].
+ *
+ * @param request.left - Left channel samples (float32)
+ * @param request.right - Right channel samples, same length as `left`
+ * @param request.sampleRate - Sample rate in Hz (default: 22050)
+ * @param request.targetDb - Finite target at or below 0 dBFS. Defaults to 0 for
+ *   `mode: 'peak'` and -20 for `mode: 'rms'`, matching the library and the other
+ *   language surfaces.
+ * @param request.mode - `'peak'` (default) or `'rms'`
+ * @returns The normalized pair and the shared gain in dB
+ * @throws RangeError when the two channels differ in length
+ *
+ * @example
+ * ```ts
+ * const { left, right, appliedGainDb } = normalizeStereo({
+ *   left: leftSamples,
+ *   right: rightSamples,
+ *   sampleRate: 44100,
+ *   targetDb: -1,
+ * });
+ * ```
+ */
+export function normalizeStereo(request: NormalizeStereoRequest): NormalizeStereoResult {
+  assertSamples('normalizeStereo', request.left, request.validate !== false);
+  assertSamples('normalizeStereo', request.right, request.validate !== false);
+  if (request.left.length !== request.right.length) {
+    throw new RangeError('Stereo channel lengths must match.');
+  }
+  const mode = resolveNormalizeMode(request.mode, 'normalizeStereo');
+  // Mode-dependent, unlike the mono `normalize` on this surface, which defaults
+  // to 0 dB in both modes. 0 dBFS RMS is not a usable default -- the peaks sit
+  // well above the RMS, so every one of them clips -- and the library and the
+  // other surfaces all default RMS to -20. A new entry point takes the shared
+  // default rather than inheriting a surface-local one.
+  const targetDb = request.targetDb ?? (mode === 'rms' ? -20.0 : 0.0);
+  return requireModule().normalizeStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    targetDb,
+    mode,
+  );
+}
+
 /** Internal envelope selecting the core dotted-param parser in the embind layer. */
 function canonicalChainConfig(config: MasteringChainConfig): Record<string, unknown> {
   return { __flatParams: flattenChainConfig(config) };
@@ -279,6 +438,31 @@ export function masteringPresetNames(): MasteringPreset[] {
   return Array.from(requireModule().masteringPresetNames()) as MasteringPreset[];
 }
 
+/**
+ * The flat `{key: number|boolean}` params of preset `preset`'s built-in chain
+ * configuration, in the same key space {@link masteringAssistantSuggestChain}
+ * returns. Passing this straight through as `overrides` to {@link masterAudio}
+ * reproduces the preset unchanged, bit for bit in the C++ core.
+ *
+ * @param preset - Preset identifier from {@link masteringPresetNames}.
+ * @throws For an unknown `preset`.
+ */
+export function masteringPresetParams(preset: MasteringPreset): Record<string, number | boolean> {
+  return requireModule().masteringPresetParams(preset);
+}
+
+/**
+ * List the delivery targets the mastering assistant accepts as `targetPlatform`.
+ *
+ * Read from the library rather than from a list kept here, so a target added in
+ * the core is discoverable without a binding change.
+ *
+ * @returns Target names in index order (e.g. "streaming", "broadcast", "club")
+ */
+export function masteringPlatformNames(): string[] {
+  return Array.from(requireModule().masteringPlatformNames());
+}
+
 /**
  * Apply a named mastering preset chain to mono audio.
  *

package/src/mastering_core.ts

@@ -1,5 +1,10 @@
+import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type {
+  LoudnessMatchResult,
+  MasteringAssistantParams,
+  MasteringInsertParamChoice,
+  MasteringInsertSlot,
   MasteringOptions,
   MasteringProcessorParams,
   MasteringResult,
@@ -11,6 +16,8 @@ import type {
   StreamingPlatform,
 } from './public_types';
 
+export type { MasteringInsertParamChoice, MasteringInsertSlot };
+
 function requireModule() {
   return getSonareModule();
 }
@@ -45,6 +52,15 @@ export interface MasteringPairProcessRequest {
   params?: MasteringProcessorParams;
 }
 
+/** Canonical request form for {@link masteringAbMatchLoudness}. */
+export interface MasteringAbMatchLoudnessRequest {
+  /** The take to gain-match. */
+  source: Float32Array;
+  /** The take whose loudness `source` is matched to; returned untouched. */
+  reference: Float32Array;
+  sampleRate?: number;
+}
+
 /** Canonical request form for a two-input match analysis. */
 export interface MasteringPairAnalyzeRequest {
   analysisName: PairAnalysis;
@@ -70,6 +86,13 @@ export interface MasteringSamplesParamsRequest {
   params?: MasteringProcessorParams;
 }
 
+/** Canonical request form for the assistant, whose params carry a target platform. */
+export interface MasteringAssistantParamsRequest {
+  samples: Float32Array;
+  sampleRate?: number;
+  params?: MasteringAssistantParams;
+}
+
 /** Canonical request form for streaming-platform preview. */
 export interface MasteringStreamingPreviewRequest {
   samples: Float32Array;
@@ -85,6 +108,14 @@ export interface MasteringStereoParamsRequest {
   params?: MasteringProcessorParams;
 }
 
+/** Stereo counterpart of {@link MasteringAssistantParamsRequest}. */
+export interface MasteringAssistantStereoParamsRequest {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate?: number;
+  params?: MasteringAssistantParams;
+}
+
 /** Canonical request form for the stereo streaming-platform preview. */
 export interface MasteringStreamingPreviewStereoRequest {
   left: Float32Array;
@@ -137,9 +168,7 @@ export function masteringProcessorNames(): SoloProcessor[] {
  * `sonare_mastering_insert_names` (which joins this list) as a `string[]`.
  */
 export function masteringInsertNames(): string[] {
-  return (
-    requireModule() as unknown as { masteringInsertNames: () => string[] }
-  ).masteringInsertNames();
+  return requireModule().masteringInsertNames();
 }
 
 /**
@@ -153,43 +182,165 @@ export function masteringInsertNames(): string[] {
  * @param name - Insert processor name (see {@link masteringInsertNames}).
  */
 export function masteringInsertParamNames(name: string): string[] {
-  return Array.from(
-    (
-      requireModule() as unknown as { masteringInsertParamNames: (name: string) => string[] }
-    ).masteringInsertParamNames(name),
-  );
+  return Array.from(requireModule().masteringInsertParamNames(name));
 }
 
-/** One realtime-automatable parameter of an insert processor. */
+/**
+ * One parameter an insert processor's construction reads, whether or not it
+ * is realtime-automatable.
+ */
 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. */
+  /**
+   * Integer param id for realtime automation lanes / MIDI-CC binding, or null
+   * for a construction-only key with no automation target.
+   */
+  id: number | null;
+  /** Whether the param can be changed live from the audio thread; false when `id` is null. */
   rtSafe: boolean;
-  /** Physical unit when the parameter is not unitless. */
-  unit?: string;
+  /**
+   * The C++ type the processor's config builder reads the key as. `"enum"` is
+   * sent as the number in its `choices` entry; `"string"` / `"array"` (an
+   * embedded impulse response, a per-band list) is construction-only and
+   * reports null for `min`, `max`, `default` and `choices`.
+   */
+  type: 'boolean' | 'number' | 'enum' | 'string' | 'array';
+  /**
+   * Smallest value construction accepts, or null when the catalog states no
+   * limit or `choices` is non-null. Measured, so it is a hard constraint
+   * rather than a UI range; see {@link CapabilityCatalogParameter} for what a
+   * measured bound does and does not promise.
+   */
+  min: number | null;
+  /** Largest value construction accepts, or null when the catalog states no limit or `choices` is non-null. */
+  max: number | null;
+  /**
+   * Value the processor uses when the key is absent — the config struct's own
+   * field initializer, an enum as its number. Null for a param id with no
+   * construction key, a `"string"` / `"array"` key, or a construction key with
+   * no fallback.
+   */
+  default: boolean | number | null;
+  /** Physical unit, or null when the parameter is unitless. */
+  unit: string | null;
+  /**
+   * The closed set of values construction accepts, in value order, or null
+   * when the accepted values are not a closed set. Non-null only for `"enum"`
+   * (every declared enumerator construction accepts) or a `"number"` key
+   * whose accepted integers have holes; `min` / `max` are then both null.
+   */
+  choices: MasteringInsertParamChoice[] | null;
+  /**
+   * The {@link MasteringInsertSlot} this key belongs to, or null for a key that
+   * always exists.
+   */
+  slot: string | null;
 }
 
 /**
- * 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.
+ * Returns every parameter an insert / FX processor's construction reads,
+ * including construction-time-only keys with no realtime automation target.
+ * Entries come in two runs: first the processor's realtime automation
+ * targets in id order (the keys accepted by
+ * {@link RealtimeEngine.setTrackStripInsertParamByName}, `id` non-null); then,
+ * sorted by name, every other construction key with `id` null and `rtSafe`
+ * false. The name set matches {@link masteringInsertParamNames} plus any
+ * automation target construction does not read. Returns an empty array for an
+ * unknown name.
  *
  * @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);
+  const json = requireModule().masteringInsertParamInfo(name);
   return JSON.parse(json) as MasteringInsertParamInfo[];
 }
 
+/** Latency and tail of one insert instance, in samples. */
+export interface MasteringInsertTiming {
+  /** Latency in samples at the queried sample rate. */
+  latencySamples: number;
+  /** Audible decay tail in samples at the queried sample rate. */
+  tailSamples: number;
+}
+
+/** One built-in amp-sim rig with its resolved starting configuration. */
+export interface MasteringAmpPresetCatalogEntry {
+  /** Stable index used by the amp-sim `presetIndex` parameter. */
+  index: number;
+  /** Canonical preset identifier accepted by the amp-sim insert. */
+  name: string;
+  /** Effective values from the core preset, before sparse user overrides. */
+  params: Record<string, number | boolean>;
+}
+
+/**
+ * Returns the built-in amp-sim rigs and their resolved control values.
+ *
+ * The catalog is read-only metadata for hosts such as Studio. Persist only the
+ * preset index and explicit overrides in a project so future core updates can
+ * continue to define the canonical DSP configuration.
+ */
+export function masteringAmpPresetCatalog(): MasteringAmpPresetCatalogEntry[] {
+  const json = requireModule().masteringAmpPresetCatalog();
+  return JSON.parse(json) as MasteringAmpPresetCatalogEntry[];
+}
+
+/**
+ * Reject a `params` value {@link masteringInsertTiming} cannot serialize:
+ * anything other than a finite number or a boolean, naming the offending key.
+ * Booleans serialize as JSON booleans, not 0/1, since the C++ reader accepts
+ * `is_bool` alongside a number.
+ */
+function insertTimingParamsToJson(fnName: string, params: Record<string, number | boolean>) {
+  const out: Record<string, number | boolean> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (typeof value === 'boolean') {
+      out[key] = value;
+      continue;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new SonareError(
+        ErrorCode.InvalidParameter,
+        'InvalidParameter',
+        `${fnName}: params.${key} must be a finite number or boolean`,
+      );
+    }
+    out[key] = value;
+  }
+  return JSON.stringify(out);
+}
+
+/**
+ * Latency and tail of insert `name` built from `params` and prepared at
+ * `sampleRate` (`mastering::api::insert_timing`). Answers for the exact
+ * instance a scene or strip would build — an oversampled saturation path, a
+ * linear-phase crossover, a lookahead all change the reported latency. The
+ * capability catalog's `latencySamples` / `tailSamples` are this query at
+ * default parameters and 48 kHz. `effects.reverb.convolution` answers for its
+ * configuration without an impulse response: its latency is its fixed
+ * partition size and does not depend on one.
+ *
+ * A key `name`'s construction does not read is refused rather than ignored,
+ * because an ignored key would answer for a configuration the caller did not
+ * ask for.
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ * @param params - Flat parameter values, keyed as in {@link masteringInsertParamInfo}.
+ * @param sampleRate - Rate the insert is prepared at.
+ * @throws For an unknown `name`, a key the insert does not read, a value its
+ *   construction or `prepare` refuses, or a `params` value that is not a
+ *   finite number or boolean.
+ */
+export function masteringInsertTiming(
+  name: string,
+  params: Record<string, number | boolean>,
+  sampleRate: number,
+): MasteringInsertTiming {
+  const json = insertTimingParamsToJson('masteringInsertTiming', params);
+  return requireModule().masteringInsertTiming(name, json, sampleRate);
+}
+
 /**
  * How a processor handles a buffer with more than two channels (a surround
  * bed). "multichannel" processes every plane in one call; "stereoPairOnly"
@@ -205,6 +356,25 @@ export type MasteringChannelPolicy =
 /** Coarse algorithmic work estimate for a realtime insert; not a benchmark. */
 export type MasteringRealtimeCost = 'low' | 'moderate' | 'high';
 
+/**
+ * Catalog grouping for a processor picker, derived from the id's prefix
+ * ("eq.*" -> "eq", "match.*" -> "reference"); anything unprefixed is "other".
+ */
+export type MasteringProcessorCategory =
+  | 'dynamics'
+  | 'effects'
+  | 'eq'
+  | 'final'
+  | 'maximizer'
+  | 'multiband'
+  | 'other'
+  | 'reference'
+  | 'repair'
+  | 'saturation'
+  | 'spectral'
+  | 'stereo'
+  | 'utility';
+
 /** One processor's realtime/offline/pair classification in the catalog. */
 export interface MasteringProcessorCatalogEntry {
   /** Processor id (the name used for scene inserts / named processors). */
@@ -237,6 +407,19 @@ export interface MasteringProcessorCatalogEntry {
    * surround planes passed through dry).
    */
   channelPolicy: MasteringChannelPolicy;
+  /** Grouping for a processor picker; see {@link MasteringProcessorCategory}. */
+  category: MasteringProcessorCategory;
+  /**
+   * The processor's construction parameters, the same list
+   * {@link masteringInsertParamInfo} returns. Empty for entries that are not
+   * realtime-insertable.
+   */
+  params: MasteringInsertParamInfo[];
+  /**
+   * The insert's conditional key groups in declaration order, named by each
+   * parameter's `slot`. Empty for entries that are not realtime-insertable.
+   */
+  slots: MasteringInsertSlot[];
 }
 
 /**
@@ -246,9 +429,7 @@ export interface MasteringProcessorCatalogEntry {
  * instead of offering ids the realtime strip would reject.
  */
 export function masteringProcessorCatalog(): MasteringProcessorCatalogEntry[] {
-  const json = (
-    requireModule() as unknown as { masteringProcessorCatalog: () => string }
-  ).masteringProcessorCatalog();
+  const json = requireModule().masteringProcessorCatalog();
   return JSON.parse(json) as MasteringProcessorCatalogEntry[];
 }
 
@@ -405,6 +586,36 @@ export function masteringPairAnalyze(
   );
 }
 
+/**
+ * Gain-match `source` to `reference`'s integrated loudness, so an A/B between
+ * the two is not decided by level. `source` and `reference` may have
+ * independent lengths.
+ *
+ * The gain is applied with no upper bound and `matchedTruePeakDbtp` reports
+ * where that left the peak, rather than the call capping it: a headroom clamp
+ * would return `source` at its own loudness whenever it started near full
+ * scale. Both loudness values are non-finite for a silent or below-gate take,
+ * and `appliedGainDb` is then 0.
+ *
+ * @example
+ * ```ts
+ * const { samples, appliedGainDb, matchedTruePeakDbtp } = masteringAbMatchLoudness({
+ *   source: take,
+ *   reference: master,
+ *   sampleRate: 48000,
+ * });
+ * ```
+ */
+export function masteringAbMatchLoudness(
+  request: MasteringAbMatchLoudnessRequest,
+): LoudnessMatchResult {
+  return requireModule().masteringAbMatchLoudness(
+    request.source,
+    request.reference,
+    request.sampleRate ?? 22050,
+  );
+}
+
 export function masteringStereoAnalyze(request: MasteringStereoAnalyzeRequest): string;
 export function masteringStereoAnalyze(
   analysisName: StereoAnalysis,
@@ -439,16 +650,16 @@ export function masteringStereoAnalyze(
   );
 }
 
-export function masteringAssistantSuggest(request: MasteringSamplesParamsRequest): string;
+export function masteringAssistantSuggest(request: MasteringAssistantParamsRequest): string;
 export function masteringAssistantSuggest(
   samples: Float32Array,
   sampleRate?: number,
-  params?: MasteringProcessorParams,
+  params?: MasteringAssistantParams,
 ): string;
 export function masteringAssistantSuggest(
-  samples: Float32Array | MasteringSamplesParamsRequest,
+  samples: Float32Array | MasteringAssistantParamsRequest,
   sampleRate = 22050,
-  params: MasteringProcessorParams = {},
+  params: MasteringAssistantParams = {},
 ): string {
   const request = samples instanceof Float32Array ? { samples, sampleRate, params } : samples;
   return requireModule().masteringAssistantSuggest(
@@ -458,6 +669,91 @@ export function masteringAssistantSuggest(
   );
 }
 
+/**
+ * Suggest a mastering chain, as the flat `{key: number|boolean}` params map
+ * {@link masteringAssistantSuggest}'s `chainConfig` carries, without needing to
+ * pull it out of the full assistant document. The returned map can be passed
+ * straight through as `overrides` to {@link mastering} / {@link masterAudio}.
+ */
+export function masteringAssistantSuggestChain(
+  request: MasteringAssistantParamsRequest,
+): Record<string, number | boolean> {
+  return requireModule().masteringAssistantSuggestChain(
+    request.samples,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
+/**
+ * The shape {@link masteringAudioProfile}'s JSON parses to.
+ *
+ * The profile crosses as a string, so nothing type-checks it on arrival; this
+ * declaration is what a conformance check compares against the paths the C++
+ * writer publishes, so a field added on one side and not the other fails there
+ * rather than reaching a caller as `undefined`.
+ */
+export interface MasteringAudioProfile {
+  durationSec: number;
+  bpm: number;
+  bpmConfidence: number;
+  loudness: {
+    integratedLufs: number;
+    lraLu: number;
+    truePeakDb: number;
+    crestFactorDb: number;
+  };
+  spectral: {
+    subRmsDb: number;
+    lowRmsDb: number;
+    lowMidRmsDb: number;
+    midRmsDb: number;
+    highMidRmsDb: number;
+    highRmsDb: number;
+    airRmsDb: number;
+    centroidHz: number;
+    flatness: number;
+    rolloffHz: number;
+  };
+  dynamics: {
+    shortTermLufsStd: number;
+    attackDensity: number;
+    sustainRatio: number;
+  };
+  /**
+   * What the repair detectors measured. `measured` is false when nothing ran —
+   * either `detectDefects` was not asked for or the input was too short — and
+   * every other field is then at its default rather than a reading.
+   */
+  defects: {
+    measured: boolean;
+    clickCount: number;
+    clickRejected: number;
+    clickLongestRunSamples: number;
+    clickPerSecond: number;
+    crackleSampleCount: number;
+    crackleSampleFraction: number;
+    cracklePerSecond: number;
+    clipSampleCount: number;
+    clipRunCount: number;
+    clipLongestRunSamples: number;
+    clipSampleFraction: number;
+    clipFlatRunCount: number;
+    clipFlatSampleCount: number;
+    clipLongestFlatRunSamples: number;
+    clipFlatLevel: number;
+    noiseFloorDbfs: number;
+    noiseBandPeakDbfs: number;
+    noiseBandPeakIndex: number;
+    humFundamentalHz: number;
+    humFundamentalProminence: number;
+    humHarmonics: number;
+    humFundamentalDbfs: number;
+    humPeakHarmonicDbfs: number;
+    lateDecayRatioDb: number;
+  };
+}
+
 export function masteringAudioProfile(request: MasteringSamplesParamsRequest): string;
 export function masteringAudioProfile(
   samples: Float32Array,
@@ -503,7 +799,9 @@ export function masteringStreamingPreview(
  * 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 {
+export function masteringAssistantSuggestStereo(
+  request: MasteringAssistantStereoParamsRequest,
+): string {
   return requireModule().masteringAssistantSuggestStereo(
     request.left,
     request.right,
@@ -512,6 +810,22 @@ export function masteringAssistantSuggestStereo(request: MasteringStereoParamsRe
   );
 }
 
+/**
+ * Stereo counterpart of {@link masteringAssistantSuggestChain}: the flat
+ * `{key: number|boolean}` params map without the surrounding assistant
+ * document, ready to pass through as `overrides` to {@link masterAudioStereo}.
+ */
+export function masteringAssistantSuggestChainStereo(
+  request: MasteringAssistantStereoParamsRequest,
+): Record<string, number | boolean> {
+  return requireModule().masteringAssistantSuggestChainStereo(
+    request.left,
+    request.right,
+    request.sampleRate ?? 22050,
+    request.params ?? {},
+  );
+}
+
 /**
  * Mastering assistant profile of a stereo pair, as shared JSON.
  *