@libraz/libsonare 1.7.2 → 1.8.0

package/src/public_types_mixing.ts

@@ -1,3 +1,5 @@
+import type { EqBand } from './public_types_realtime';
+
 export type PanMode =
   | 'balance'
   | 'pan'
@@ -48,8 +50,18 @@ export interface MixMeterSnapshot {
   shortTermLufs: number;
   integratedLufs: number;
   gainReductionDb: number;
+  /**
+   * Left-channel inter-sample (true) peak in dB, from the ITU-R BS.1770-4
+   * polyphase reconstruction at 4x. A streaming measurement: the centered
+   * reconstruction stencil needs a few future samples a realtime path does not
+   * have, so each block's last samples read marginally low (about 0.1 dB across
+   * 64..8192-sample blocks on a near-Nyquist tone, always under-reading). Use
+   * `meteringTruePeakDb` over the whole signal for an exact dBTP number.
+   */
   truePeakDbL: number;
+  /** Right-channel inter-sample (true) peak in dB. See {@link truePeakDbL}. */
   truePeakDbR: number;
+  /** Maximum inter-sample peak across channels in dB. See {@link truePeakDbL}. */
   maxTruePeakDb: number;
   seq: number;
   /** Number of valid surround planes (5.1/7.1); 0 before the meter sees audio. */
@@ -58,7 +70,10 @@ export interface MixMeterSnapshot {
   peakDb: number[];
   /** Per-plane RMS dB, length channelCount; [0]/[1] mirror rmsDbL/rmsDbR. */
   rmsDb: number[];
-  /** Per-plane true-peak dB, length channelCount; [0]/[1] mirror truePeakDbL/R. */
+  /**
+   * Per-plane true-peak dB, length channelCount; [0]/[1] mirror
+   * {@link truePeakDbL}/R and carry the same streaming caveat.
+   */
   truePeakDb: number[];
 }
 
@@ -115,8 +130,355 @@ export type MeterTap = 'preFader' | 'postFader';
 /** Pre/post-fader send timing (see {@link Mixer.addSend}). */
 export type SendTiming = 'preFader' | 'postFader';
 
+/**
+ * Source a bus or master insert's sidechain key is taken from: a track lane's
+ * post-strip signal, or a bus's signal before its `gainDb`.
+ */
+export type SidechainSourceKind = 'track' | 'bus';
+
 /** A single goniometer (left/right) sample returned by {@link Mixer.readGoniometerLatest}. */
 export interface GoniometerPoint {
   left: number;
   right: number;
 }
+
+/** One analysis band of the mixing assistant's shared 7-band split. */
+export type MixAnalysisBand = 'sub' | 'low' | 'lowMid' | 'mid' | 'highMid' | 'high' | 'air';
+
+/** Share of a track's energy in each analysis band; sums to 1, or to 0 when silent. */
+export type MixBandOccupancy = Record<MixAnalysisBand, number>;
+
+/**
+ * One track handed to {@link suggestMixScene}.
+ *
+ * Planar and per-track: tracks in one call may differ in length, and each is
+ * mono (`right` omitted) or stereo independently of the others. A stereo
+ * track's `right` must be the same length as its `left`.
+ */
+export interface MixAssistantTrack {
+  /** Strip id the suggestion is written against. Must be unique and non-empty. */
+  id: string;
+  /**
+   * Optional display name, used as a source-classification hint.
+   *
+   * Naming the class the classifier measured raises its confidence. Naming
+   * another class switches to it when the measurement does not contradict it:
+   * a class the classifier measures needs its own feature rule satisfied by the
+   * track, and one it cannot measure needs the track not to have been measured
+   * as a drum (a drum is never renamed `keys` or `vocal`). For the six classes
+   * it cannot separate by measurement — `keys`, `strings`, `lead`, `vocal`,
+   * `backing` and `fx` — the name is the only thing that can supply the class,
+   * so an unnamed voice, pad or lead line comes back `unknown`. A compound name
+   * states its last hint word (`'Lead Vox'` is `vocal`, `'Synth Lead'` is
+   * `lead`); hint words joined by anything else (`'Strings and Keys'`) state
+   * none.
+   */
+  name?: string;
+  /** Left/mono plane. */
+  left: Float32Array;
+  /** Right plane; omit for a mono track. */
+  right?: Float32Array;
+}
+
+/**
+ * Tunables for {@link suggestMixScene}. Every field is optional and falls back
+ * to the core default noted on it; the same field names and defaults are used
+ * by the Node and Python surfaces.
+ */
+export interface MixAssistantOptions {
+  /** Absolute integrated-loudness target each track is staged towards, in LUFS. Defaults to -18. */
+  targetTrackLufs?: number;
+  /**
+   * Overall strength of the suggestion in `[0, 1]`, scaling every level-like
+   * decision: trims, fader offsets, send levels, EQ cut depths, compression
+   * ratios and ranges, and how far a track is spread from the centre. Defaults
+   * to 1.
+   *
+   * `0` is not an empty suggestion. It is every one of those taken and set to
+   * zero, plus the decisions that are not levels and so do not scale: the bus
+   * topology and routing, and the physical corrections for a measured
+   * cancellation (polarity, alignment delay, low-end mono fold). To suggest
+   * nothing, switch the domains off instead — that also skips the work.
+   */
+  suggestionStrength?: number;
+  /** Largest cut a single suggested EQ band may apply, in dB. Defaults to 4. */
+  eqMaxCutDb?: number;
+  /** Headroom the summed mix is left with on the master bus, in dBTP. Defaults to -6. */
+  mixBusHeadroomDbtp?: number;
+  /**
+   * Tempo the suggested delay times are voiced against, in BPM.
+   *
+   * Defaults to 0, which selects the transport's own fallback tempo: the
+   * assistant is handed bare stems and cannot measure a tempo the set as a
+   * whole agrees on. Pass the song's tempo and the delay lands on the beat.
+   *
+   * A positive value outside 20–400 BPM is rejected rather than clamped.
+   */
+  tempoBpm?: number;
+  /** Evaluate the structure domain. Defaults to true. */
+  enableStructure?: boolean;
+  /** Evaluate the gain-staging domain. Defaults to true. */
+  enableGain?: boolean;
+  /** Evaluate the balance domain. Defaults to true. */
+  enableBalance?: boolean;
+  /** Evaluate the EQ domain. Defaults to true. */
+  enableEq?: boolean;
+  /** Evaluate the dynamics domain. Defaults to true. */
+  enableDynamics?: boolean;
+  /** Evaluate the stereo-image domain. Defaults to true. */
+  enableImage?: boolean;
+  /**
+   * Suggest a high-pass filter on tracks carrying residue below their register.
+   * Defaults to false.
+   *
+   * Off by default: a survey of mixing best practices found the rule that every
+   * track without low-frequency content should be high-passed to be seldom used
+   * in studio mixing and unsupported by subjective testing. Switched on, the
+   * filter is proposed from the track's measured low-frequency content rather
+   * than from its source class, so a part playing below its class's usual
+   * register keeps what it plays.
+   */
+  enableHighPass?: boolean;
+  /** Shared STFT size for every track. Defaults to 2048. */
+  nFft?: number;
+  /** Shared STFT hop for every track. Defaults to 512. */
+  hopLength?: number;
+}
+
+/** One processor slot on a scene strip or bus. */
+export interface MixSceneInsert {
+  slot: string;
+  processor: string;
+  /**
+   * Processor parameters, keyed by the parameter name the processor's catalog
+   * entry declares. Numbers and booleans throughout, except for the two keys a
+   * processor reads itself: a string for a named rig or an embedded impulse
+   * response, and a per-band array for the acoustic room morph.
+   */
+  params: Record<string, number | boolean | string | number[]>;
+  /** Present only when the insert is keyed off another strip. */
+  sidechainKey?: string;
+}
+
+/** A strip send to a destination bus. */
+export interface MixSceneSend {
+  id: string;
+  destinationBusId: string;
+  sendDb: number;
+  /** Send tap point; one of {@link SendTiming}. */
+  timing: string;
+}
+
+/** A channel strip in a mixer scene. */
+export interface MixSceneStrip {
+  id: string;
+  inputTrimDb: number;
+  faderDb: number;
+  vcaOffsetDb: number;
+  pan: number;
+  width: number;
+  muted: boolean;
+  soloed: boolean;
+  soloSafe: boolean;
+  /** Pan mode as its raw ordinal; the named forms are {@link PanMode}. */
+  panMode: number;
+  dualPanLeft: number;
+  dualPanRight: number;
+  polarityInvertLeft: boolean;
+  polarityInvertRight: boolean;
+  /** Pan law as its raw ordinal; the named forms are {@link PanLaw}. */
+  panLaw: number;
+  channelDelaySamples: number;
+  /** Present only for a non-stereo source. */
+  sourceLayout?: string;
+  /** Present only when the surround pan has moved off its centered default. */
+  surroundPan?: {
+    azimuth: number;
+    elevation: number;
+    divergence: number;
+    lfe: number;
+    distance: number;
+  };
+  /**
+   * Meter configuration for this strip's pre/post taps. Present only when the
+   * strip has opted out of some of its metering; absent means the full default
+   * (LUFS + true peak at 4x).
+   *
+   * Fixed when the mixer is built from the scene: a strip's meters size their
+   * buffers up front, so there is no setter for this. A full meter costs about
+   * 646 KB at 48 kHz and a strip carries two, so `lufs: false` (about 83 KB per
+   * meter) or `enabled: false` (about 145 KB for the whole strip instead of
+   * 1.4 MB) is worth setting for strips whose meters are never read.
+   */
+  metering?: {
+    enabled: boolean;
+    lufs: boolean;
+    truePeak: boolean;
+    /** Requested factor; the meter resolves it to the nearest of 2x / 4x / 8x. */
+    truePeakOversample: number;
+  };
+  inserts: MixSceneInsert[];
+  sends: MixSceneSend[];
+  /**
+   * This strip's dedicated equalizer. Present only when it carries something
+   * other than the identity (enabled with no bands set), so an existing scene
+   * that never touched its EQ stays byte-identical.
+   */
+  eq?: {
+    enabled?: boolean;
+    bands: EqBand[];
+  };
+}
+
+/** A bus in a mixer scene. Defaulted fields are omitted from the document. */
+export interface MixSceneBus {
+  id: string;
+  role: string;
+  layout?: string;
+  inputTrimDb?: number;
+  width?: number;
+  polarityInvertLeft?: boolean;
+  polarityInvertRight?: boolean;
+  /**
+   * Pan, same field names/defaults/ranges as a strip's. Rejected rather than
+   * stored when this bus's layout carries more than two channels: a surround
+   * bus has no pan of its own.
+   */
+  pan?: number;
+  panMode?: number;
+  dualPanLeft?: number;
+  dualPanRight?: number;
+  panLaw?: number;
+  inserts: MixSceneInsert[];
+  /** This bus's dedicated equalizer, applied before its inserts. See {@link MixSceneStrip.eq}. */
+  eq?: {
+    enabled?: boolean;
+    bands: EqBand[];
+  };
+}
+
+/** A VCA group in a mixer scene. */
+export interface MixSceneVcaGroup {
+  id: string;
+  gainDb: number;
+  members: string[];
+}
+
+/** A routing edge in a mixer scene. */
+export interface MixSceneConnection {
+  source: string;
+  destination: string;
+}
+
+/**
+ * A mixer scene document, in the schema {@link Mixer.fromSceneJson} reads.
+ * {@link suggestMixSceneJson} returns the same document as its JSON text.
+ */
+export interface MixSceneDocument {
+  version: number;
+  strips: MixSceneStrip[];
+  buses: MixSceneBus[];
+  vcaGroups: MixSceneVcaGroup[];
+  connections: MixSceneConnection[];
+}
+
+/** What the assistant measured about one input track. */
+export interface MixAssistantTrackProfile {
+  stripId: string;
+  name: string;
+  /** Source class identifier; one of {@link mixSourceClassNames}. */
+  source: string;
+  /** Classifier confidence in `[0, 1]`. */
+  sourceConfidence: number;
+  /**
+   * False when the track could not be measured: it has no samples, a
+   * non-positive sample rate, a NaN or Inf sample, is shorter than a gated
+   * loudness needs, is silent, or has no energy in the analysis bands. An
+   * excluded track gets no suggestions at all rather than suggestions of zero,
+   * and the call still succeeds — {@link exclusionReason} names which it was.
+   * A non-finite sample is reported as itself rather than as silence, so the
+   * reason describes the buffer instead of the material.
+   */
+  usable: boolean;
+  /** Why the track was excluded; empty when {@link usable} is true. */
+  exclusionReason: string;
+  channelCount: number;
+  durationSec: number;
+  /**
+   * BS.1770 integrated loudness in LUFS, or `null` for a track with no gated
+   * block to measure — a silent stem, or one muted before it was handed over.
+   * The measurement is `-Infinity` there, which JSON has no number for, so the
+   * document carries `null` rather than a finite value that would read as a
+   * real level. Such a track always carries an `exclusionReason` as well.
+   */
+  integratedLufs: number | null;
+  truePeakDb: number;
+  crestFactorDb: number;
+  spectralCentroidHz: number;
+  spectralFlatness: number;
+  attackDensity: number;
+  sustainRatio: number;
+  bandOccupancy: MixBandOccupancy;
+}
+
+/** One informative band-masking relationship between two tracks. */
+export interface MixBandDominance {
+  /** Strip id of the masking track. */
+  masker: string;
+  /** Strip id of the masked track. */
+  maskee: string;
+  band: MixAnalysisBand;
+  ratio: number;
+  validFrames: number;
+}
+
+/** A time/polarity relationship between two related tracks. */
+export interface MixTrackAlignment {
+  reference: string;
+  target: string;
+  lagSamples: number;
+  correlation: number;
+  polarityOpposed: boolean;
+}
+
+/** A band several tracks are competing for. */
+export interface MixCrowdedBand {
+  band: MixAnalysisBand;
+  crowding: number;
+}
+
+/** A track whose stereo treatment risks collapsing in mono. */
+export interface MixMonoRisk {
+  stripId: string;
+  correlation: number;
+  width: number;
+  wideLowEnd: boolean;
+}
+
+/** Cross-track measurements the suggestions were made from. */
+export interface MixAssistantMixProfile {
+  trackCount: number;
+  bandDominance: MixBandDominance[];
+  alignment: MixTrackAlignment[];
+  crowdedBands: MixCrowdedBand[];
+  monoRisks: MixMonoRisk[];
+}
+
+/**
+ * What {@link suggestMixScene} produces. Nothing has been applied: feeding
+ * `scene` to {@link Mixer.fromSceneJson} is the caller's separate step, and
+ * {@link suggestMixSceneJson} returns it already serialized for that.
+ */
+export interface MixAssistantResult {
+  /** The suggested scene, in the schema {@link Mixer.fromSceneJson} reads. */
+  scene: MixSceneDocument;
+  /** One entry per input track, in input order. */
+  tracks: MixAssistantTrackProfile[];
+  mix: MixAssistantMixProfile;
+  /**
+   * Human-readable reasons in the order the changes were applied; reading it
+   * top to bottom retraces how the scene was built. Empty when nothing was
+   * suggested (no usable tracks, or every domain switched off).
+   */
+  explanation: string[];
+}