@libraz/libsonare 1.7.2 → 1.8.0

package/src/public_types_mastering.ts

@@ -1,3 +1,25 @@
+/**
+ * Built-in mastering presets. The restoration presets — `vinyl`, `tapeHiss`,
+ * `fieldRecording`, `voiceMemo` and `shellac78` — enable repair stages only and
+ * leave level alone. Every other preset carries an integrated-loudness target
+ * and a true-peak ceiling, which are not equally binding: the ceiling always
+ * holds, while the loudness target is what one normalization pass aims at.
+ *
+ * Reaching a target above the input's loudness costs gain the input's peak
+ * headroom may not have, so the stage drives its true-peak limiter up to
+ * `loudness.maxLimiterGainReductionDb` (12 dB by default) to close the distance
+ * and stops there. Material needing more limiting than that — and material where
+ * the limiter's own gain reduction takes back part of the applied gain, which a
+ * single pass does not re-measure — finishes below target with
+ * `loudnessTargetLimited` set on the result. Peak-normalized input, whose
+ * headroom is ~0 dB, is the common case for both. Read `outputLufs` for what was
+ * achieved rather than assuming the preset's target.
+ *
+ * The restoration presets' repair stages, like every classical denoise
+ * configuration, can mistake a steady tone -- a calibration tone, a drone, a
+ * long held note -- for noise and pull it down by the configured reduction
+ * depth. Check for musical sustained tones before applying one.
+ */
 export type MasteringPreset =
   | 'pop'
   | 'edm'
@@ -23,7 +45,12 @@ export type MasteringPreset =
   | 'jazz'
   | 'kpop'
   | 'trance'
-  | 'gameOst';
+  | 'gameOst'
+  | 'vinyl'
+  | 'tapeHiss'
+  | 'fieldRecording'
+  | 'voiceMemo'
+  | 'shellac78';
 
 export interface StreamingPlatform {
   name: string;
@@ -31,74 +58,103 @@ export interface StreamingPlatform {
   ceilingDb: number;
 }
 
-export type SoloProcessor =
-  | 'dynamics.brickwallLimiter'
-  | 'dynamics.compressor'
-  | 'dynamics.deesser'
-  | 'dynamics.expander'
-  | 'dynamics.gate'
-  | 'dynamics.limiter'
-  | 'dynamics.parallelComp'
-  | 'dynamics.sidechainRouter'
-  | 'dynamics.duckingProcessor'
-  | 'dynamics.transientShaper'
-  | 'dynamics.upwardCompressor'
-  | 'dynamics.upwardExpander'
-  | 'dynamics.vocalRider'
-  | 'eq.apiStyle'
-  | 'eq.bandPass'
-  | 'eq.cutFilter'
-  | 'eq.dynamic'
-  | 'eq.equalizer'
-  | 'eq.graphic'
-  | 'eq.linearPhase'
-  | 'eq.midSide'
-  | 'eq.minimumPhase'
-  | 'eq.parametric'
-  | 'eq.pultec'
-  | 'eq.shelving'
-  | 'eq.tilt'
-  | 'final.bitDepth'
-  | 'final.dither'
-  | 'final.outputChain'
-  | 'maximizer.adaptiveRelease'
-  | 'maximizer.loudnessOptimize'
-  | 'maximizer.maximizer'
-  | 'maximizer.softKneeMax'
-  | 'maximizer.truePeakLimiter'
-  | 'multiband.compressor'
-  | 'multiband.dynamicEq'
-  | 'multiband.expander'
-  | 'multiband.imager'
-  | 'multiband.limiter'
-  | 'multiband.saturation'
-  | 'repair.declick'
-  | 'repair.declip'
-  | 'repair.decrackle'
-  | 'repair.dehum'
-  | 'repair.denoiseClassical'
-  | 'repair.dereverbClassical'
-  | 'repair.trimSilence'
-  | 'saturation.bitcrusher'
-  | 'saturation.exciter'
-  | 'saturation.hardClipper'
-  | 'saturation.multibandExciter'
-  | 'saturation.ampSim'
-  | 'saturation.softClipper'
-  | 'saturation.tape'
-  | 'saturation.transformer'
-  | 'saturation.tube'
-  | 'saturation.waveshaper'
-  | 'spectral.airBand'
-  | 'spectral.lowEndFocus'
-  | 'spectral.presenceEnhancer'
-  | 'spectral.spectralShaper'
-  | 'stereo.autoPan'
-  | 'stereo.haasEnhancer'
-  | 'stereo.imager'
-  | 'stereo.monoMaker'
-  | 'stereo.phaseAlign'
-  | 'stereo.stereoBalance';
+// BEGIN GENERATED SoloProcessor (make processor-types)
+/**
+ * Every processor name `masteringProcessorNames()` can return, and therefore
+ * every name `masteringProcess` / `masteringProcessStereo` accept.
+ */
+export const SOLO_PROCESSORS = [
+  'dynamics.brickwallLimiter',
+  'dynamics.compressor',
+  'dynamics.deesser',
+  'dynamics.duckingProcessor',
+  'dynamics.expander',
+  'dynamics.gate',
+  'dynamics.limiter',
+  'dynamics.parallelComp',
+  'dynamics.sidechainRouter',
+  'dynamics.transientShaper',
+  'dynamics.upwardCompressor',
+  'dynamics.upwardExpander',
+  'dynamics.vocalRider',
+  'effects.acoustic.roomMorph',
+  'effects.delay.stereo',
+  'effects.filter.vowel',
+  'effects.modulation.autoWah',
+  'effects.modulation.chorus',
+  'effects.modulation.ensemble',
+  'effects.modulation.flanger',
+  'effects.modulation.phaser',
+  'effects.modulation.pitchShifter',
+  'effects.modulation.ringModulator',
+  'effects.modulation.rotary',
+  'effects.modulation.wah',
+  'effects.reverb.convolution',
+  'effects.reverb.dattorro',
+  'effects.reverb.fdn',
+  'effects.reverb.plate',
+  'effects.reverb.room',
+  'effects.reverb.velvet',
+  'eq.apiStyle',
+  'eq.bandPass',
+  'eq.cutFilter',
+  'eq.dynamic',
+  'eq.equalizer',
+  'eq.graphic',
+  'eq.linearPhase',
+  'eq.midSide',
+  'eq.minimumPhase',
+  'eq.parametric',
+  'eq.pultec',
+  'eq.shelving',
+  'eq.tilt',
+  'final.bitDepth',
+  'final.dither',
+  'final.outputChain',
+  'maximizer.adaptiveRelease',
+  'maximizer.loudnessOptimize',
+  'maximizer.maximizer',
+  'maximizer.softKneeMax',
+  'maximizer.truePeakLimiter',
+  'multiband.compressor',
+  'multiband.dynamicEq',
+  'multiband.expander',
+  'multiband.imager',
+  'multiband.limiter',
+  'multiband.saturation',
+  'repair.declick',
+  'repair.declip',
+  'repair.decrackle',
+  'repair.dehum',
+  'repair.denoiseClassical',
+  'repair.dereverbClassical',
+  'repair.trimSilence',
+  'saturation.ampSim',
+  'saturation.bitcrusher',
+  'saturation.exciter',
+  'saturation.hardClipper',
+  'saturation.multibandExciter',
+  'saturation.softClipper',
+  'saturation.tape',
+  'saturation.transformer',
+  'saturation.tube',
+  'saturation.waveshaper',
+  'spectral.airBand',
+  'spectral.lowEndFocus',
+  'spectral.presenceEnhancer',
+  'spectral.spectralShaper',
+  'stereo.autoPan',
+  'stereo.binaural',
+  'stereo.haasEnhancer',
+  'stereo.imager',
+  'stereo.monoMaker',
+  'stereo.phaseAlign',
+  'stereo.stereoBalance',
+  'utility.gain',
+] as const;
+
+export type SoloProcessor = (typeof SOLO_PROCESSORS)[number];
+// END GENERATED SoloProcessor
 
 export type PairProcessor =
   | 'match.applyMatchEq'
@@ -129,6 +185,34 @@ export interface MasteringOptions {
   applyGainAtInputRate?: boolean;
 }
 
+/** What gain-matching one take to another's loudness took, and produced. */
+export interface LoudnessMatchResult {
+  /** The source take at the reference's loudness. */
+  samples: Float32Array;
+  sampleRate: number;
+  /**
+   * The reference take's BS.1770 integrated loudness. Non-finite for a silent
+   * or below-gate take — the documented outcome, not a failure.
+   */
+  referenceLufs: number;
+  /** The matched take's, before the gain. Non-finite in the same case. */
+  sourceLufs: number;
+  /**
+   * `referenceLufs - sourceLufs`. Applied with no upper bound, and 0 whenever
+   * either loudness is non-finite.
+   */
+  appliedGainDb: number;
+  /**
+   * The matched take's true peak after the gain, in dBTP.
+   *
+   * The match does not cap the gain, so this can sit above 0 dBTP: clamping to
+   * headroom would leave a near-full-scale source at its own loudness, which is
+   * the one thing a loudness match must not do. Limit downstream if the peak
+   * matters more than the match.
+   */
+  matchedTruePeakDbtp: number;
+}
+
 /**
  * Mastering loudness/true-peak processing result
  */
@@ -141,10 +225,48 @@ export interface MasteringResult {
   /** True when peak headroom prevented the requested LUFS target. */
   loudnessTargetLimited?: boolean;
   latencySamples?: number;
+  /**
+   * Samples the named processor replaced with a finite in-domain one,
+   * keeping the output finite and in range.
+   *
+   * A non-finite sample supplied by the caller is rejected before the
+   * processor runs, so a replacement is always of a value the processor
+   * itself produced.
+   *
+   * Whether this can be non-zero depends on which processor was named: one
+   * that does not substitute reports zero because it has nothing to replace
+   * with, not because nothing needed replacing. The counter saturates rather
+   * than wrapping, because a wrapped total could read as the one value zero
+   * is reserved for.
+   *
+   * @example
+   * ```ts
+   * const result = masteringProcess({
+   *   processorName: 'maximizer.truePeakLimiter',
+   *   samples,
+   *   sampleRate,
+   * });
+   * if (result.nonFiniteSubstitutionCount > 0) {
+   *   // `result.samples` is not derived from `samples` everywhere
+   * }
+   * ```
+   */
+  nonFiniteSubstitutionCount: number;
 }
 
 export type MasteringProcessorParams = Record<string, number | boolean>;
 
+/**
+ * Params accepted by the assistant entry points. Every key is numeric except
+ * two NAMES: `targetPlatform`, a delivery target (`'broadcast'`, `'podcast'`,
+ * `'club'`, ...), and `preset`, the mastering preset the suggestion starts from
+ * (default `'streaming'`; restoration presets are refused). The assistant never
+ * picks a preset from the audio. A number is rejected for either: the numeric
+ * index the C ABI carries is a transport detail for callers that cannot pass a
+ * string, not part of the JavaScript vocabulary.
+ */
+export type MasteringAssistantParams = Record<string, number | boolean | string>;
+
 /**
  * Nested mastering-chain configuration. A boolean toggles a module/processor's
  * `enabled` flag; setting any field implicitly enables its module unless
@@ -163,9 +285,15 @@ export interface MasteringChainConfig {
       | boolean
       | {
           enabled?: boolean;
+          /** 0 = log-MMSE, 1 = MMSE-STSA, 2 = spectral subtraction. */
+          mode?: number;
+          /** 0 = quantile, 1 = MCRA, 2 = IMCRA, 3 = speech-presence probability. */
+          noiseEstimator?: number;
           nFft?: number;
           hopLength?: number;
           ddAlpha?: number;
+          reductionDb?: number;
+          /** @deprecated Use `reductionDb`; converted to it (dB = -20*log10(gainFloor)). */
           gainFloor?: number;
           overSubtraction?: number;
           spectralFloor?: number;
@@ -176,6 +304,8 @@ export interface MasteringChainConfig {
     nFft?: number;
     hopLength?: number;
     ddAlpha?: number;
+    reductionDb?: number;
+    /** @deprecated Use `denoise.reductionDb`; converted to it (dB = -20*log10(gainFloor)). */
     gainFloor?: number;
     declip?: {
       enabled?: boolean;
@@ -201,6 +331,8 @@ export interface MasteringChainConfig {
       adaptation?: number;
       frameSize?: number;
       pllBandwidth?: number;
+      /** 0 = subtract the tracked harmonics, 1 = cascaded notches. */
+      mode?: number;
     };
     declick?: {
       enabled?: boolean;
@@ -301,6 +433,8 @@ export interface MasteringChainConfig {
       headBumpDb?: number;
       bias?: number;
       gapLoss?: number;
+      /** Jiles-Atherton core oversampling: 1 (default), 2, or 4. */
+      oversampleFactor?: number;
     };
     exciter?: {
       enabled?: boolean;
@@ -309,6 +443,12 @@ export interface MasteringChainConfig {
       amount?: number;
       q?: number;
       evenOddMix?: number;
+      /**
+       * Antialiasing mode ordinal: 0 = none, 3 = 4x oversampling. The ADAA
+       * modes (1, 2) name a member the exciter does not implement and are
+       * rejected; an ordinal outside 0-3 is rejected as out of range.
+       */
+      aliasing?: number;
     };
   };
   spectral?: {
@@ -351,6 +491,14 @@ export interface MasteringChainConfig {
     truePeakOversample?: number;
     releaseMs?: number;
     applyGainAtInputRate?: boolean;
+    /**
+     * How deep, in dB, the stage may drive its post-gain true-peak limiter to
+     * reach {@link targetLufs}. Default 12. The static normalization gain may
+     * exceed the peak headroom toward `ceilingDb` by this much; `0` restores a
+     * strict headroom clamp, under which peak-normalized input keeps its input
+     * loudness whatever target is asked for. `ceilingDb` holds at every setting.
+     */
+    maxLimiterGainReductionDb?: number;
   };
   /**
    * Dot-notation spelling of any leaf above, e.g. `'loudness.targetLufs': -20`
@@ -385,7 +533,8 @@ export interface StreamingMasteringChainConfig extends MasteringChainConfig {
   /**
    * Offline-measured true-peak (dBFS) of the source the static gain was
    * computed for. When provided, the static gain is clamped to
-   * `loudness.ceilingDb - loudnessStaticGainPeakDb` so the streaming preview
+   * `(loudness.ceilingDb - loudnessStaticGainPeakDb) +
+   * max(loudness.maxLimiterGainReductionDb, 0)` so the streaming preview
    * does not drive the loudness limiter harder than the offline chain. When
    * omitted (the default) the static gain is applied verbatim.
    */
@@ -432,15 +581,35 @@ export interface MasteringChainResult {
   appliedGainDb: number;
   stages: string[];
   /**
-   * ITU-R BS.1770-4 true peak of the output (dBTP), measured with the chain's
-   * configured loudness true-peak oversample factor (default 4x). Lets callers
-   * verify a preset ceiling was met without a second oversampled scan.
+   * ITU-R BS.1770-4 true peak of the output (dBTP). Lets callers verify a
+   * preset ceiling was met without a second oversampled scan.
+   *
+   * The oversample factor follows the peak-limiting stage the chain actually
+   * applied, so it is not fixed: the loudness stage's true-peak oversample
+   * (default 4x) when loudness is enabled, and the maximizer true-peak
+   * limiter's own oversample factor when loudness is disabled but that stage
+   * ran. The two disagree by roughly 0.02 dB between 4x and 8x, so comparing
+   * this against an independently measured peak needs the same factor.
    */
   outputTruePeakDbtp: number;
   /** EBU Tech 3342 Loudness Range of the output (LU). */
   outputLra: number;
   /** True when peak headroom prevented the requested LUFS target. */
   loudnessTargetLimited: boolean;
+  /**
+   * Samples a stage replaced with a finite in-domain one, keeping the
+   * output finite and in range.
+   *
+   * A non-finite sample supplied by the caller is rejected before any stage
+   * runs, so a replacement is always of a value a stage itself produced.
+   *
+   * Only the true-peak limiters replace anything, so with the maximizer's
+   * limiter and the loudness stage both disabled a zero here means no stage
+   * was able to replace anything rather than that nothing needed replacing.
+   * Aggregated, so it does not identify which one substituted; run a limiter
+   * individually through {@link masteringProcess} to attribute a non-zero count.
+   */
+  nonFiniteSubstitutionCount: number;
   /** Per-stage gain reductions for the dynamics/maximizer stages (a subset of `stages`). */
   stageGainReductions: StageGainReduction[];
   report: MasteringReport;
@@ -458,6 +627,11 @@ export interface MasteringChainStereoResult {
   outputTruePeakDbtp: number;
   outputLra: number;
   loudnessTargetLimited: boolean;
+  /**
+   * See {@link MasteringChainResult.nonFiniteSubstitutionCount}. Aggregated
+   * over both channels, so it does not identify which channel substituted.
+   */
+  nonFiniteSubstitutionCount: number;
   stageGainReductions: StageGainReduction[];
   report: MasteringReport;
 }
@@ -477,4 +651,11 @@ export interface MasteringStereoResult {
   outputLufs: number;
   appliedGainDb: number;
   latencySamples: number;
+  /** True when peak headroom prevented the requested LUFS target. */
+  loudnessTargetLimited: boolean;
+  /**
+   * See {@link MasteringResult.nonFiniteSubstitutionCount}. Aggregated over both
+   * channels, so it does not identify which channel substituted.
+   */
+  nonFiniteSubstitutionCount: number;
 }