@libraz/libsonare 1.7.2 → 1.8.1

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.
  *