@libraz/libsonare 1.2.3 → 1.3.0

package/src/public_types.ts

@@ -1,3 +1,5 @@
+import type { ValidateOptions } from './validation';
+
 /**
  * Pitch class enum (C=0, C#=1, ..., B=11)
  */
@@ -172,6 +174,7 @@ export type SoloProcessor =
   | 'saturation.exciter'
   | 'saturation.hardClipper'
   | 'saturation.multibandExciter'
+  | 'saturation.ampSim'
   | 'saturation.softClipper'
   | 'saturation.tape'
   | 'saturation.transformer'
@@ -230,7 +233,7 @@ export interface Key {
   shortName: string;
 }
 
-export interface KeyDetectionOptions {
+export interface KeyDetectionOptions extends ValidateOptions {
   nFft?: number;
   hopLength?: number;
   useHpss?: boolean;
@@ -251,7 +254,7 @@ export interface KeyCandidate {
   correlation: number;
 }
 
-export interface ChordDetectionOptions {
+export interface ChordDetectionOptions extends ValidateOptions {
   minDuration?: number;
   smoothingWindow?: number;
   threshold?: number;
@@ -268,6 +271,102 @@ export interface ChordDetectionOptions {
   chromaMethod?: 'stft' | 'nnls';
 }
 
+/** 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;
+}
+
+/** Options for `analyzeBpm`. All fields are optional. */
+export interface AnalyzeBpmOptions extends ValidateOptions {
+  /** Lowest BPM to consider. Default 30. */
+  bpmMin?: number;
+  /** Highest BPM to consider. Default 300. */
+  bpmMax?: number;
+  /** Tempo prior the tracker is biased toward. Default 120. */
+  startBpm?: number;
+  /** FFT size for the onset envelope. Default 2048. */
+  nFft?: number;
+  /** Hop length for the onset envelope. Default 512. */
+  hopLength?: number;
+  /** Number of tempo candidates to return. Default 5. */
+  maxCandidates?: number;
+}
+
+/** Options for `analyzeRhythm`. All fields are optional. */
+export interface AnalyzeRhythmOptions extends ValidateOptions {
+  /** Lowest BPM to consider. Default 60. */
+  bpmMin?: number;
+  /** Highest BPM to consider. Default 200. */
+  bpmMax?: number;
+  /** Tempo prior the tracker is biased toward. Default 120. */
+  startBpm?: number;
+  /** FFT size for the onset envelope. Default 2048. */
+  nFft?: number;
+  /** Hop length for the onset envelope. Default 512. */
+  hopLength?: number;
+}
+
+/** Options for `analyzeDynamics`. All fields are optional. */
+export interface AnalyzeDynamicsOptions extends ValidateOptions {
+  /** Loudness-curve window length in seconds. Default 0.4. */
+  windowSec?: number;
+  /** Hop length for the loudness curve. Default 512. */
+  hopLength?: number;
+  /** Crest-factor (dB) below which the signal is flagged as compressed. Default 6. */
+  compressionThreshold?: number;
+}
+
+/** Options for `analyzeTimbre`. All fields are optional. */
+export interface AnalyzeTimbreOptions extends ValidateOptions {
+  /** FFT size. Default 2048. */
+  nFft?: number;
+  /** Hop length. Default 512. */
+  hopLength?: number;
+  /** Number of Mel bands. Default 128. */
+  nMels?: number;
+  /** Number of MFCCs. Default 13. */
+  nMfcc?: number;
+  /** Per-window analysis length in seconds. Default 0.5. */
+  windowSec?: number;
+}
+
+/** Options for `analyzeSections`. All fields are optional. */
+export interface AnalyzeSectionsOptions {
+  /** FFT size. Default 2048. */
+  nFft?: number;
+  /** Hop length. Default 512. */
+  hopLength?: number;
+  /** Minimum section duration in seconds. Default 4. */
+  minSectionSec?: number;
+}
+
+/** 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;
+}
+
+/** Options for `noteStretch`. All fields are optional. */
+export interface NoteStretchOptions {
+  /** Note onset position in samples (selects the region). Default 0. */
+  onsetSample?: number;
+  /** Note offset position in samples (selects the region). Default 0. */
+  offsetSample?: number;
+  /** Stretch ratio (0.5 = double duration, 2.0 = half duration). Default 1. */
+  stretchRatio?: number;
+}
+
 /**
  * Detected beat
  */
@@ -347,6 +446,15 @@ export interface CqtResult {
   frequencies: Float32Array;
 }
 
+/**
+ * Multi-band onset strength matrix result.
+ */
+export interface OnsetStrengthMultiResult {
+  nBands: number;
+  nFrames: number;
+  data: Float32Array;
+}
+
 /**
  * Timbre characteristics
  */
@@ -363,6 +471,8 @@ export interface Timbre {
  */
 export interface Dynamics {
   dynamicRangeDb: number;
+  peakDb: number;
+  rmsDb: number;
   loudnessRangeDb: number;
   crestFactor: number;
   isCompressed: boolean;
@@ -384,6 +494,19 @@ export interface RhythmFeatures {
   syncopation: number;
   grooveType: string;
   patternRegularity: number;
+  tempoStability: number;
+  timeSignature: TimeSignature;
+}
+
+/**
+ * Melody contour from the unified analysis (pitch trajectory + summary stats).
+ */
+export interface MelodyContour {
+  pitchRangeOctaves: number;
+  pitchStability: number;
+  meanFrequency: number;
+  vibratoRate: number;
+  pitches: MelodyPoint[];
 }
 
 /**
@@ -401,6 +524,7 @@ export interface AnalysisResult {
   timbre: Timbre;
   dynamics: Dynamics;
   rhythm: RhythmFeatures;
+  melody: MelodyContour;
   form: string;
 }
 
@@ -426,7 +550,20 @@ 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;
@@ -482,6 +619,15 @@ export interface RoomEstimateResult {
 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;
 }
 
 /**
@@ -714,6 +860,35 @@ export interface MasteringChainConfig {
   };
 }
 
+/**
+ * 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[];
 }