@libraz/libsonare 1.4.1 → 1.5.1

package/src/public_types_acoustic.ts

@@ -0,0 +1,115 @@
+import type { ValidateOptions } from './validation';
+
+/** Options for `detectAcoustic`. All fields are optional. */
+export interface AcousticOptions extends ValidateOptions {
+  /** Number of octave bands. Default 6. */
+  nOctaveBands?: number;
+  /** Number of 1/3-octave sub-bands. Default 24. */
+  nThirdOctaveSubbands?: number;
+  /** Minimum decay range (dB) for a valid RT60 fit. Default 30. */
+  minDecayDb?: number;
+  /** Margin (dB) above the noise floor for the decay fit. Default 10. */
+  noiseFloorMarginDb?: number;
+}
+
+/**
+ * Room acoustic parameters from an impulse response
+ */
+export interface AcousticResult {
+  rt60: number;
+  edt: number;
+  c50: number;
+  c80: number;
+  d50: number;
+  rt60Bands: Float32Array;
+  edtBands: Float32Array;
+  c50Bands: Float32Array;
+  c80Bands: Float32Array;
+  confidence: number;
+  isBlind: boolean;
+}
+
+/** Shoebox geometry + placement shared by RIR synthesis and the room morph. */
+export interface RoomGeometryOptions {
+  lengthM?: number;
+  widthM?: number;
+  heightM?: number;
+  /** Uniform wall absorption, clamped to [0, 0.999] (the back-compat scalar). */
+  absorption?: number;
+  /**
+   * Optional per-octave-band wall absorption (125/250/500/1k/2k/4k.. Hz). When
+   * provided it overrides `absorption` unless `materialPreset` is set.
+   */
+  bandAbsorption?: Float32Array | number[];
+  /** Optional per-band wall scattering; missing bands default to 0. */
+  bandScattering?: Float32Array | number[];
+  /**
+   * Named wall-material preset (0 none; 1 concrete, 2 wood, 3 curtain,
+   * 4 carpet, 5 glass). A non-zero preset wins over `bandAbsorption`/`absorption`.
+   */
+  materialPreset?: number;
+  sourceX?: number;
+  sourceY?: number;
+  sourceZ?: number;
+  listenerX?: number;
+  listenerY?: number;
+  listenerZ?: number;
+  ismOrder?: number;
+  seed?: number;
+  maxSeconds?: number;
+}
+
+export interface RirSynthOptions extends RoomGeometryOptions {
+  sampleRate?: number;
+  /** Use the Eyring statistical late-tail model (default true); false = Sabine. */
+  preferEyring?: boolean;
+  /** Early/late crossover in ms (0 = auto, ~sqrt(V) ms). */
+  mixingTimeMs?: number;
+  /** Equal-power crossfade width around the mixing time in ms (0 = default). */
+  crossfadeMs?: number;
+}
+
+export interface RirResult {
+  rir: Float32Array;
+  sampleRate: number;
+  hasError: boolean;
+}
+
+export interface RoomEstimateOptions {
+  aspectHintLw?: number;
+  aspectHintLh?: number;
+  referenceAbsorption?: number;
+  preferEyring?: boolean;
+  nOctaveBands?: number;
+  /** Analyzer routing: 0 = auto, 1 = blind, 2 = impulse-response. */
+  mode?: number;
+  /** Analyzer decay-fit span in dB (0 = library default). */
+  minDecayDb?: number;
+  /** Analyzer noise-floor margin in dB (0 = library default). */
+  noiseFloorMarginDb?: number;
+}
+
+export interface RoomEstimateResult {
+  volume: number;
+  length: number;
+  width: number;
+  height: number;
+  drrDb: number;
+  confidence: number;
+  absorptionBands: Float32Array;
+  rt60Bands: Float32Array;
+}
+
+export interface RoomMorphOptions extends RoomGeometryOptions {
+  wet?: number;
+  sourceTailSuppression?: number;
+  /**
+   * Use the Eyring statistical late-tail model for the target room (default
+   * true); false = Sabine. Matches {@link RirSynthOptions.preferEyring}.
+   */
+  preferEyring?: boolean;
+  /** Early/late crossover in ms (0 = auto, ~sqrt(V) ms). */
+  mixingTimeMs?: number;
+  /** Equal-power crossfade width around the mixing time in ms (0 = default). */
+  crossfadeMs?: number;
+}

package/src/public_types_mastering.ts

@@ -0,0 +1,333 @@
+export type MasteringPreset =
+  | 'pop'
+  | 'edm'
+  | 'acoustic'
+  | 'hipHop'
+  | 'aiMusic'
+  | 'speech'
+  | 'streaming'
+  | 'youtube'
+  | 'broadcast'
+  | 'podcast'
+  | 'audiobook'
+  | 'cinema'
+  | 'jpop'
+  | 'ambient'
+  | 'lofi'
+  | 'classical'
+  | 'drumAndBass'
+  | 'techno'
+  | 'metal'
+  | 'trap'
+  | 'rnb'
+  | 'jazz'
+  | 'kpop'
+  | 'trance'
+  | 'gameOst';
+
+export interface StreamingPlatform {
+  name: string;
+  targetLufs: number;
+  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';
+
+export type PairProcessor =
+  | 'match.applyMatchEq'
+  | 'match.alignReferenceToSource'
+  | 'match.abSwitch'
+  | 'match.abCrossfade';
+
+export type PairAnalysis =
+  | 'match.referenceLoudness'
+  | 'match.tonalBalance'
+  | 'match.tonalBalanceLogBands'
+  | 'match.matchEqCurve'
+  | 'match.estimateReferenceDelaySamples';
+
+export type StereoAnalysis = 'stereo.monoCompatCheck' | 'stereo.monoCompatCheckLogBands';
+
+/** Options for `mastering`. All fields are optional. */
+export interface MasteringOptions {
+  /** Target integrated LUFS. Default -14. */
+  targetLufs?: number;
+  /** True/sample peak ceiling in dBFS. Default -1. */
+  ceilingDb?: number;
+  /** Oversampling factor used for peak estimation. Default 4. */
+  truePeakOversample?: number;
+  /** Post true-peak limiter release in ms. Default 0 => library default (50 ms). */
+  releaseMs?: number;
+  /** Apply the static loudness gain at the input (pre-oversample) rate. Default false. */
+  applyGainAtInputRate?: boolean;
+}
+
+/**
+ * Mastering loudness/true-peak processing result
+ */
+export interface MasteringResult {
+  samples: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  latencySamples?: number;
+}
+
+export type MasteringProcessorParams = Record<string, number | boolean>;
+
+export interface MasteringChainConfig {
+  repair?: {
+    denoise?: boolean;
+    nFft?: number;
+    hopLength?: number;
+    ddAlpha?: number;
+    gainFloor?: number;
+    declick?: {
+      threshold?: number;
+      neighborRatio?: number;
+      maxClickSamples?: number;
+      lpcOrder?: number;
+      residualRatio?: number;
+    };
+    dereverb?: {
+      threshold?: number;
+      attenuation?: number;
+      nFft?: number;
+      hopLength?: number;
+      t60Sec?: number;
+      lateDelayMs?: number;
+      overSubtraction?: number;
+      spectralFloor?: number;
+      wpeEnabled?: boolean;
+      wpeIterations?: number;
+      wpeTaps?: number;
+      wpeStrength?: number;
+    };
+  };
+  eq?: {
+    tiltDb?: number;
+    pivotHz?: number;
+  };
+  dynamics?: {
+    compressor?: {
+      thresholdDb?: number;
+      ratio?: number;
+      attackMs?: number;
+      releaseMs?: number;
+      kneeDb?: number;
+      makeupGainDb?: number;
+      autoMakeup?: boolean;
+    };
+    deesser?: {
+      frequencyHz?: number;
+      thresholdDb?: number;
+      ratio?: number;
+      attackMs?: number;
+      releaseMs?: number;
+      rangeDb?: number;
+      bandpassQ?: number;
+    };
+    transientShaper?: {
+      attackGainDb?: number;
+      sustainGainDb?: number;
+      fastAttackMs?: number;
+      fastReleaseMs?: number;
+      slowAttackMs?: number;
+      slowReleaseMs?: number;
+      sensitivity?: number;
+      maxGainDb?: number;
+      gainSmoothingMs?: number;
+      lookaheadMs?: number;
+    };
+    multibandComp?: {
+      lowCutoffHz?: number;
+      highCutoffHz?: number;
+      lowThresholdDb?: number;
+      lowRatio?: number;
+      lowAttackMs?: number;
+      lowReleaseMs?: number;
+      midThresholdDb?: number;
+      midRatio?: number;
+      midAttackMs?: number;
+      midReleaseMs?: number;
+      highThresholdDb?: number;
+      highRatio?: number;
+      highAttackMs?: number;
+      highReleaseMs?: number;
+    };
+  };
+  saturation?: {
+    tape?: {
+      driveDb?: number;
+      saturation?: number;
+      hysteresis?: number;
+      outputGainDb?: number;
+      speedIps?: number;
+      headBumpDb?: number;
+      bias?: number;
+      gapLoss?: number;
+    };
+    exciter?: {
+      frequencyHz?: number;
+      driveDb?: number;
+      amount?: number;
+      q?: number;
+      evenOddMix?: number;
+    };
+  };
+  spectral?: {
+    airBand?: {
+      amount?: number;
+      shelfFrequencyHz?: number;
+      dynamicThresholdDb?: number;
+      dynamicRangeDb?: number;
+    };
+  };
+  stereo?: {
+    imager?: {
+      width?: number;
+      outputGainDb?: number;
+      decorrelationAmount?: number;
+      preserveEnergy?: boolean;
+    };
+    monoMaker?: {
+      amount?: number;
+    };
+  };
+  maximizer?: {
+    truePeakLimiter?: {
+      ceilingDb?: number;
+      lookaheadMs?: number;
+      releaseMs?: number;
+      oversampleFactor?: number;
+      applyGainAtInputRate?: boolean;
+    };
+  };
+  loudness?: {
+    targetLufs?: number;
+    ceilingDb?: number;
+    truePeakOversample?: number;
+  };
+}
+
+/**
+ * Configuration for the block-by-block {@link StreamingMasteringChain}.
+ *
+ * Extends {@link MasteringChainConfig} with optional precomputed loudness
+ * parameters. The streaming chain cannot measure whole-signal integrated LUFS,
+ * so an enabled `loudness` stage normally throws at construction. To let a
+ * preset's streaming preview match its offline render, the caller may
+ * precompute the loudness normalization gain offline (e.g.
+ * `targetLufs - measuredIntegratedLufs`) and supply it here.
+ */
+export interface StreamingMasteringChainConfig extends MasteringChainConfig {
+  /**
+   * Precomputed static loudness gain in dB. When omitted (the default), an
+   * enabled `loudness` stage still throws. When provided and `loudness.enabled`
+   * is set, the chain applies this fixed gain per block before the loudness
+   * stage's true-peak limiter instead of throwing.
+   */
+  loudnessStaticGainDb?: number;
+
+  /**
+   * 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
+   * does not drive the loudness limiter harder than the offline chain. When
+   * omitted (the default) the static gain is applied verbatim.
+   */
+  loudnessStaticGainPeakDb?: number;
+}
+
+export interface MasteringChainResult extends MasteringResult {
+  stages: string[];
+}
+
+export interface MasteringStereoChainResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  stages: string[];
+  latencySamples?: number;
+}
+
+export interface MasteringStereoResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  latencySamples: number;
+}

package/src/public_types_mixing.ts

@@ -0,0 +1,97 @@
+export type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
+
+/**
+ * Surround pan position for a strip feeding a >2-channel bus. Phase 1 honors
+ * `azimuth`/`divergence`/`lfe`; `elevation`/`distance` are reserved. All fields
+ * are optional and default to a centered point source.
+ */
+export interface SurroundPan {
+  /** -180..180 deg, 0 = front-center, positive = right. */
+  azimuth?: number;
+  /** Reserved (no height beds in phase 1). */
+  elevation?: number;
+  /** 0 = point source, 1 = spread across the front. */
+  divergence?: number;
+  /** 0..1 scalar send into the LFE plane. */
+  lfe?: number;
+  /** Reserved (focus/spread), defaults to 1. */
+  distance?: number;
+}
+
+export interface MixOptions {
+  inputTrimDb?: number | number[];
+  faderDb?: number | number[];
+  pan?: number | number[];
+  panMode?: PanMode | PanMode[];
+  width?: number | number[];
+  muted?: boolean | boolean[];
+}
+
+export interface MixMeterSnapshot {
+  peakDbL: number;
+  peakDbR: number;
+  rmsDbL: number;
+  rmsDbR: number;
+  correlation: number;
+  monoCompatWidth: number;
+  monoCompatPeak: number;
+  monoCompatSideRms: number;
+  likelyMonoCompatible: boolean;
+  momentaryLufs: number;
+  shortTermLufs: number;
+  integratedLufs: number;
+  gainReductionDb: number;
+  truePeakDbL: number;
+  truePeakDbR: number;
+  maxTruePeakDb: number;
+  seq: number;
+  /** Number of valid surround planes (5.1/7.1); 0 before the meter sees audio. */
+  channelCount: number;
+  /** Per-plane peak dB, length channelCount; [0]/[1] mirror peakDbL/peakDbR. */
+  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. */
+  truePeakDb: number[];
+}
+
+export interface MixResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+  meters: MixMeterSnapshot[];
+}
+
+/** Mixed stereo master returned by {@link Mixer.processStereo}. */
+export interface MixerProcessResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+}
+
+/**
+ * Interpolation curve for scheduled automation events
+ * (see {@link Mixer.scheduleInsertAutomation}).
+ */
+export type AutomationCurve = 'linear' | 'exponential' | 'hold' | 's-curve';
+
+/**
+ * Pan law applied when computing left/right gains from a pan position
+ * (see {@link Mixer.setPanLaw}). Maps to the underlying integer code.
+ */
+export type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';
+
+/**
+ * Meter tap point for reading a strip's meter snapshot
+ * (see {@link Mixer.meterTap} and {@link Mixer.stripMeter}).
+ */
+export type MeterTap = 'preFader' | 'postFader';
+
+/** Pre/post-fader send timing (see {@link Mixer.addSend}). */
+export type SendTiming = 'preFader' | 'postFader';
+
+/** A single goniometer (left/right) sample returned by {@link Mixer.readGoniometerLatest}. */
+export interface GoniometerPoint {
+  left: number;
+  right: number;
+}