@libraz/libsonare 1.4.1 → 1.5.1

package/src/public_types_music.ts

@@ -0,0 +1,352 @@
+import type { ValidateOptions } from './validation';
+
+/**
+ * Pitch class enum (C=0, C#=1, ..., B=11)
+ */
+export const PitchClass = {
+  C: 0,
+  Cs: 1,
+  D: 2,
+  Ds: 3,
+  E: 4,
+  F: 5,
+  Fs: 6,
+  G: 7,
+  Gs: 8,
+  A: 9,
+  As: 10,
+  B: 11,
+} as const;
+
+export type PitchClass = (typeof PitchClass)[keyof typeof PitchClass];
+
+/**
+ * Musical mode
+ */
+export const Mode = {
+  Major: 0,
+  Minor: 1,
+  Dorian: 2,
+  Phrygian: 3,
+  Lydian: 4,
+  Mixolydian: 5,
+  Locrian: 6,
+} as const;
+
+export type Mode = (typeof Mode)[keyof typeof Mode];
+
+export type TempogramMode = 'autocorrelation' | 'auto' | 'ac' | 'cosine' | 0 | 1;
+
+export const KeyProfile = {
+  KrumhanslSchmuckler: 0,
+  Temperley: 1,
+  Shaath: 2,
+  FaraldoEDMT: 3,
+  FaraldoEDMA: 4,
+  FaraldoEDMM: 5,
+  BellmanBudge: 6,
+} as const;
+
+export type KeyProfile = (typeof KeyProfile)[keyof typeof KeyProfile];
+
+export type KeyProfileName =
+  | 'ks'
+  | 'krumhansl'
+  | 'temperley'
+  | 'shaath'
+  | 'keyfinder'
+  | 'faraldo-edmt'
+  | 'edmt'
+  | 'faraldo-edma'
+  | 'edma'
+  | 'faraldo-edmm'
+  | 'edmm'
+  | 'bellman-budge'
+  | 'bellman';
+
+/**
+ * Chord quality
+ */
+export const ChordQuality = {
+  Major: 0,
+  Minor: 1,
+  Diminished: 2,
+  Augmented: 3,
+  Dominant7: 4,
+  Major7: 5,
+  Minor7: 6,
+  Sus2: 7,
+  Sus4: 8,
+  Unknown: 9,
+  Add9: 10,
+  MinorAdd9: 11,
+  Dim7: 12,
+  HalfDim7: 13,
+  Major9: 14,
+  Dominant9: 15,
+  Sus2Add4: 16,
+} as const;
+
+export type ChordQuality = (typeof ChordQuality)[keyof typeof ChordQuality];
+
+/**
+ * Section type
+ */
+export const SectionType = {
+  Intro: 0,
+  Verse: 1,
+  PreChorus: 2,
+  Chorus: 3,
+  Bridge: 4,
+  Instrumental: 5,
+  Outro: 6,
+  Unknown: 7,
+} as const;
+
+export type SectionType = (typeof SectionType)[keyof typeof SectionType];
+
+/**
+ * Detected musical key
+ */
+export interface Key {
+  root: PitchClass;
+  mode: Mode;
+  confidence: number;
+  name: string;
+  shortName: string;
+}
+
+export interface KeyDetectionOptions extends ValidateOptions {
+  nFft?: number;
+  hopLength?: number;
+  useHpss?: boolean;
+  loudnessWeighted?: boolean;
+  highPassHz?: number;
+  modes?:
+    | Mode[]
+    | ('major' | 'minor' | 'dorian' | 'phrygian' | 'lydian' | 'mixolydian' | 'locrian')[]
+    | 'major-minor'
+    | 'all'
+    | 'modal';
+  profile?: KeyProfile | KeyProfileName;
+  genreHint?: 'auto' | 'edm' | 'electronic' | 'dance' | 'pop' | 'classical' | 'jazz' | string;
+}
+
+export interface KeyCandidate {
+  key: Key;
+  correlation: number;
+}
+
+export interface ChordDetectionOptions extends ValidateOptions {
+  minDuration?: number;
+  smoothingWindow?: number;
+  threshold?: number;
+  useTriadsOnly?: boolean;
+  nFft?: number;
+  hopLength?: number;
+  useBeatSync?: boolean;
+  useHmm?: boolean;
+  hmmBeamWidth?: number;
+  useKeyContext?: boolean;
+  keyRoot?: PitchClass;
+  keyMode?: Mode;
+  detectInversions?: boolean;
+  chromaMethod?: 'stft' | 'nnls';
+}
+
+/** 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;
+}
+
+/**
+ * Detected beat
+ */
+export interface Beat {
+  time: number;
+  strength: number;
+}
+
+/**
+ * Detected chord
+ */
+export interface Chord {
+  root: PitchClass;
+  bass: PitchClass;
+  quality: ChordQuality;
+  start: number;
+  end: number;
+  confidence: number;
+  name: string;
+}
+
+export interface ChordAnalysisResult {
+  chords: Chord[];
+}
+
+/**
+ * Detected section
+ */
+export interface Section {
+  type: SectionType;
+  start: number;
+  end: number;
+  energyLevel: number;
+  confidence: number;
+  name: string;
+}
+
+/**
+ * A single melody contour point (mirrors the C `SonareMelodyPoint`).
+ */
+export interface MelodyPoint {
+  /** Frame time in seconds. */
+  time: number;
+  /** Estimated fundamental frequency in Hz (0 when unvoiced). */
+  frequency: number;
+  /** Voicing confidence in `[0, 1]`. */
+  confidence: number;
+}
+
+/**
+ * Melody analysis result (mirrors the C `SonareMelodyResult`).
+ */
+export interface MelodyResult {
+  points: MelodyPoint[];
+  pitchRangeOctaves: number;
+  pitchStability: number;
+  meanFrequency: number;
+  vibratoRate: number;
+}
+
+/**
+ * Timbre characteristics
+ */
+export interface Timbre {
+  brightness: number;
+  warmth: number;
+  density: number;
+  roughness: number;
+  complexity: number;
+}
+
+/**
+ * Dynamics characteristics
+ */
+export interface Dynamics {
+  dynamicRangeDb: number;
+  peakDb: number;
+  rmsDb: number;
+  loudnessRangeDb: number;
+  crestFactor: number;
+  isCompressed: boolean;
+}
+
+/**
+ * Time signature
+ */
+export interface TimeSignature {
+  numerator: number;
+  denominator: number;
+  confidence: number;
+}
+
+/**
+ * Rhythm features
+ */
+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[];
+}
+
+/**
+ * Complete analysis result
+ */
+export interface AnalysisResult {
+  bpm: number;
+  bpmConfidence: number;
+  key: Key;
+  timeSignature: TimeSignature;
+  beatTimes: Float32Array;
+  beats: Beat[];
+  chords: Chord[];
+  sections: Section[];
+  timbre: Timbre;
+  dynamics: Dynamics;
+  rhythm: RhythmFeatures;
+  melody: MelodyContour;
+  form: string;
+}

package/src/public_types_realtime.ts

@@ -0,0 +1,163 @@
+/**
+ * Realtime equalizer spectrum snapshot.
+ *
+ * Mirrors the C++ `EqualizerSpectrumSnapshot`: `preLeft`/`preRight` and
+ * `postLeft`/`postRight` are the pre- and post-EQ spectrum streams (trimmed to
+ * their valid count). `bandGainDb` holds per-band applied gain (24 entries),
+ * `profileDb` the smoothed magnitude profile (16 entries), `lastAutoGainDb`
+ * the latest auto-gain compensation, and `seq` increments each time a new
+ * snapshot is published.
+ */
+export interface EqSpectrumSnapshot {
+  preLeft: Float32Array;
+  preRight: Float32Array;
+  postLeft: Float32Array;
+  postRight: Float32Array;
+  bandGainDb: Float32Array;
+  profileDb: Float32Array;
+  lastAutoGainDb: number;
+  seq: number;
+}
+
+/**
+ * Equalizer band type (string union mirroring `sonare::mastering::eq::EqBandType`).
+ */
+export type EqBandType =
+  | 'Peak'
+  | 'LowShelf'
+  | 'HighShelf'
+  | 'LowPass'
+  | 'HighPass'
+  | 'BandPass'
+  | 'Notch'
+  | 'TiltShelf'
+  | 'FlatTilt';
+
+/** Biquad coefficient design mode. */
+export type EqCoeffMode = 'Rbj' | 'Vicanek';
+
+/** Stereo placement for an EQ band. */
+export type EqStereoPlacement = 'Stereo' | 'Left' | 'Right' | 'Mid' | 'Side';
+
+/** Per-band phase behaviour. */
+export type EqBandPhase = 'Inherit' | 'ZeroLatency' | 'NaturalPhase' | 'LinearPhase';
+
+/**
+ * Equalizer band configuration accepted by {@link StreamingEqualizer.setBand}.
+ *
+ * All fields are optional; omitted values fall back to the C++ band defaults
+ * (Peak, 1000 Hz, 0 dB gain, Butterworth Q, disabled).
+ */
+export interface EqBand {
+  type?: EqBandType;
+  frequencyHz?: number;
+  gainDb?: number;
+  q?: number;
+  enabled?: boolean;
+  coeffMode?: EqCoeffMode;
+  slopeDbOct?: number;
+  placement?: EqStereoPlacement;
+  phase?: EqBandPhase;
+  soloed?: boolean;
+  bypassed?: boolean;
+  proportionalQ?: boolean;
+  proportionalQStrength?: number;
+  dynamic?: boolean;
+  thresholdDb?: number;
+  autoThreshold?: boolean;
+  ratio?: number;
+  rangeDb?: number;
+  attackMs?: number;
+  releaseMs?: number;
+  lookaheadMs?: number;
+  externalSidechain?: boolean;
+  sidechainFreqHz?: number;
+  sidechainQ?: number;
+}
+
+/** Construction options for {@link StreamingEqualizer}. */
+export interface StreamingEqualizerConfig {
+  sampleRate?: number;
+  maxBlockSize?: number;
+}
+
+/** Configuration for {@link StreamingRetune}. */
+export interface StreamingRetuneConfig {
+  /** Pitch shift in semitones, clamped by the native processor to +/-24. */
+  semitones?: number;
+  /** Wet/dry mix, clamped by the native processor to 0..1. */
+  mix?: number;
+  /** Grain size in samples. Use 0/omit to derive it from the sample rate. */
+  grainSize?: number;
+}
+
+/** Options for {@link StreamingEqualizer.match}. */
+export interface EqMatchOptions {
+  sampleRate?: number;
+  maxBands?: number;
+}
+
+export type VoicePresetId =
+  | 'neutral-monitor'
+  | 'bright-idol'
+  | 'soft-whisper'
+  | 'deep-narrator'
+  | 'robot-mascot'
+  | 'dark-villain';
+
+export interface RealtimeVoiceChangerPreset {
+  schemaVersion: 1;
+  id?: string;
+  name?: string;
+  description?: string;
+  macros?: Record<string, number>;
+  dsp?: Record<string, unknown>;
+}
+
+export type RealtimeVoiceChangerConfigInput = VoicePresetId | RealtimeVoiceChangerPreset;
+
+/**
+ * Flat (POD) realtime voice-changer configuration. Keys are camelCase to match
+ * the Node addon getter, so a preset config reads identically across both JS
+ * surfaces (the underlying C ABI / Python POD uses the snake_case equivalents).
+ */
+export interface RealtimeVoiceChangerPodConfig {
+  inputGainDb: number;
+  outputGainDb: number;
+  wetMix: number;
+  retuneSemitones: number;
+  retuneMix: number;
+  retuneGrainSize: number;
+  formantFactor: number;
+  formantAmount: number;
+  formantBody: number;
+  formantBrightness: number;
+  formantNasal: number;
+  eqHighpassHz: number;
+  eqBodyDb: number;
+  eqPresenceDb: number;
+  eqAirDb: number;
+  gateThresholdDb: number;
+  gateAttackMs: number;
+  gateReleaseMs: number;
+  gateRangeDb: number;
+  compressorThresholdDb: number;
+  compressorRatio: number;
+  compressorAttackMs: number;
+  compressorReleaseMs: number;
+  compressorMakeupGainDb: number;
+  deesserFrequencyHz: number;
+  deesserThresholdDb: number;
+  deesserRatio: number;
+  deesserRangeDb: number;
+  reverbMix: number;
+  reverbTimeMs: number;
+  reverbDamping: number;
+  reverbSeed: number;
+  limiterCeilingDb: number;
+  limiterReleaseMs: number;
+  /** Non-zero enables the 4x-oversampled inter-sample-peak limiter (default enabled). */
+  limiterEnableIspLimiter: boolean;
+  /** True-peak ceiling in dBTP applied by the ISP limiter (default -1.0). */
+  limiterIspCeilingDbtp: number;
+}

package/src/public_types_spectral.ts

@@ -0,0 +1,194 @@
+import type { ValidateOptions } from './validation';
+
+/** Options for `pitchCorrectTimevarying`. All fields are optional. */
+export interface PitchCorrectOptions extends ValidateOptions {
+  /** `'midi'` retunes toward `targetMidi`; `'scale'` snaps to the key. Default `'midi'`. */
+  mode?: 'midi' | 'scale';
+  /** Fixed target note when `mode` is `'midi'`, in `[0, 127]`. Default 69 (A4). */
+  targetMidi?: number;
+  /** Scale root pitch class (0=C .. 11=B) when `mode` is `'scale'`. Default 0. */
+  scaleRoot?: number;
+  /** 12-bit degree mask, bit `i` = semitone `i` above the root enabled. Default C major. */
+  scaleModeMask?: number;
+  /** Reference MIDI anchoring the scale grid. Default 69 (A4). */
+  referenceMidi?: number;
+  /** Correction strength in `[0, 1]`; 1 = full snap, 0 = bypass. Default 1. */
+  retuneAmount?: number;
+  /** Hard clamp on per-frame correction magnitude (semitones). Default 12. */
+  maxCorrectionSemitones?: number;
+  /** Retune IIR time constant (ms); larger = slower glide. Default 50. */
+  retuneSpeedMs?: number;
+  /** Corrections below this are bypassed to preserve vibrato (cents). Default 20. */
+  vibratoThresholdCents?: number;
+  /** Per-frame voiced flags (non-zero = voiced); omit to treat all frames as voiced. */
+  voiced?: Int32Array;
+  /** Per-frame voicing probability in `[0, 1]`; omit to derive from `voiced`. */
+  voicedProb?: Float32Array;
+}
+
+/** 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;
+}
+
+/** How a `spectralEdit` region op modifies the masked bins. */
+export type SpectralEditMode = 'gain' | 'attenuate' | 'mute' | 'heal';
+
+/** Analysis/synthesis window used by `spectralEdit`. */
+export type SpectralEditWindow = 'hann' | 'hamming' | 'blackman' | 'rectangular';
+
+/** One time x frequency rectangle edit op for `spectralEdit`. */
+export interface SpectralRegionOp {
+  /** Region time start (input samples); clamped to [0, length]. Default 0. */
+  startSample?: number;
+  /** Region time end, exclusive (input samples); clamped to [0, length]. Default = signal length. */
+  endSample?: number;
+  /** Region frequency low edge in Hz; clamped to [0, nyquist]. Default 0. */
+  lowHz?: number;
+  /** Region frequency high edge in Hz; <=0 or >= nyquist means nyquist. Default 0. */
+  highHz?: number;
+  /** Linear gain in dB for 'gain'/'attenuate'; ignored by 'mute'/'heal'. Default 0. */
+  gainDb?: number;
+  /** Edit mode. Default 'gain'. */
+  mode?: SpectralEditMode;
+}
+
+/** STFT + heal parameters for `spectralEdit`. All fields are optional. */
+export interface SpectralEditOptions {
+  /** FFT size; must be a power of two (>= 2). Default 2048. */
+  nFft?: number;
+  /** Hop length; must satisfy 0 < hop <= nFft/2. Default 512. */
+  hopLength?: number;
+  /** Analysis + synthesis window. Default 'hann'. */
+  window?: SpectralEditWindow;
+  /** Neighbour frames each side used by 'heal' (>= 1). Default 2. */
+  healRadiusFrames?: number;
+}
+
+/**
+ * Constant-Q / Variable-Q transform magnitude result (mirrors the C
+ * `SonareCqtResult`).
+ */
+export interface CqtResult {
+  /** Number of frequency bins. */
+  nBins: number;
+  /** Number of time frames. */
+  nFrames: number;
+  /** Hop length in samples. */
+  hopLength: number;
+  /** Sample rate in Hz. */
+  sampleRate: number;
+  /** Row-major `[nBins x nFrames]` magnitude matrix. */
+  magnitude: Float32Array;
+  /** Center frequency (Hz) of each of the `nBins` bins. */
+  frequencies: Float32Array;
+}
+
+/**
+ * Multi-band onset strength matrix result.
+ */
+export interface OnsetStrengthMultiResult {
+  nBands: number;
+  nFrames: number;
+  data: Float32Array;
+}
+
+/**
+ * STFT (Short-Time Fourier Transform) result
+ */
+export interface StftResult {
+  nBins: number;
+  nFrames: number;
+  nFft: number;
+  hopLength: number;
+  sampleRate: number;
+  magnitude: Float32Array;
+  power: Float32Array;
+}
+
+/**
+ * Mel spectrogram result
+ */
+export interface MelSpectrogramResult {
+  nMels: number;
+  nFrames: number;
+  sampleRate: number;
+  hopLength: number;
+  power: Float32Array;
+  db: Float32Array;
+}
+
+/**
+ * MFCC result
+ */
+export interface MfccResult {
+  nMfcc: number;
+  nFrames: number;
+  coefficients: Float32Array;
+}
+
+/**
+ * STFT power spectrogram result (from inverse Mel reconstruction)
+ */
+export interface StftPowerResult {
+  nBins: number;
+  nFrames: number;
+  power: Float32Array;
+}
+
+/**
+ * Mel power spectrogram result (from inverse MFCC reconstruction)
+ */
+export interface MelPowerResult {
+  nMels: number;
+  nFrames: number;
+  power: Float32Array;
+}
+
+/**
+ * Chroma features result
+ */
+export interface ChromaResult {
+  nChroma: number;
+  nFrames: number;
+  sampleRate: number;
+  hopLength: number;
+  features: Float32Array;
+  meanEnergy: number[];
+}
+
+/**
+ * Pitch detection result
+ */
+export interface PitchResult {
+  f0: Float32Array;
+  voicedProb: Float32Array;
+  voicedFlag: boolean[];
+  nFrames: number;
+  medianF0: number;
+  meanF0: number;
+}
+
+/**
+ * Loudness measurement result (EBU R128 / ITU-R BS.1770)
+ */
+export interface LufsResult {
+  integratedLufs: number;
+  momentaryLufs: number;
+  shortTermLufs: number;
+  loudnessRange: number;
+}
+
+/**
+ * HPSS (Harmonic-Percussive Source Separation) result
+ */
+export interface HpssResult {
+  harmonic: Float32Array;
+  percussive: Float32Array;
+  sampleRate: number;
+}