@libraz/libsonare 1.0.3 → 1.1.0

package/src/sonare.js.d.ts

@@ -0,0 +1,624 @@
+/**
+ * Type declarations for the Emscripten-generated WASM module with embind
+ */
+
+interface SonareModuleOptions {
+  locateFile?: (path: string, prefix: string) => string;
+  onRuntimeInitialized?: () => void;
+  print?: (text: string) => void;
+  printErr?: (text: string) => void;
+}
+
+// Result types
+interface WasmKeyResult {
+  root: number;
+  mode: number;
+  confidence: number;
+  name: string;
+  shortName: string;
+}
+
+interface WasmBeatResult {
+  time: number;
+  strength: number;
+}
+
+interface WasmChordResult {
+  root: number;
+  quality: number;
+  start: number;
+  end: number;
+  confidence: number;
+  name: string;
+}
+
+interface WasmSectionResult {
+  type: number;
+  start: number;
+  end: number;
+  energyLevel: number;
+  confidence: number;
+  name: string;
+}
+
+interface WasmTimbreResult {
+  brightness: number;
+  warmth: number;
+  density: number;
+  roughness: number;
+  complexity: number;
+}
+
+interface WasmDynamicsResult {
+  dynamicRangeDb: number;
+  loudnessRangeDb: number;
+  crestFactor: number;
+  isCompressed: boolean;
+}
+
+interface WasmRhythmResult {
+  syncopation: number;
+  grooveType: string;
+  patternRegularity: number;
+}
+
+interface WasmTimeSignatureResult {
+  numerator: number;
+  denominator: number;
+  confidence: number;
+}
+
+interface WasmAnalysisResult {
+  bpm: number;
+  bpmConfidence: number;
+  key: WasmKeyResult;
+  timeSignature: WasmTimeSignatureResult;
+  beats: WasmBeatResult[];
+  chords: WasmChordResult[];
+  sections: WasmSectionResult[];
+  timbre: WasmTimbreResult;
+  dynamics: WasmDynamicsResult;
+  rhythm: WasmRhythmResult;
+  form: string;
+}
+
+interface WasmHpssResult {
+  harmonic: Float32Array;
+  percussive: Float32Array;
+  sampleRate: number;
+}
+
+interface WasmStftResult {
+  nBins: number;
+  nFrames: number;
+  nFft: number;
+  hopLength: number;
+  sampleRate: number;
+  magnitude: Float32Array;
+  power: Float32Array;
+}
+
+interface WasmStftDbResult {
+  nBins: number;
+  nFrames: number;
+  db: Float32Array;
+}
+
+interface WasmMelResult {
+  nMels: number;
+  nFrames: number;
+  sampleRate: number;
+  hopLength: number;
+  power: Float32Array;
+  db: Float32Array;
+}
+
+interface WasmMfccResult {
+  nMfcc: number;
+  nFrames: number;
+  coefficients: Float32Array;
+}
+
+interface WasmChromaResult {
+  nChroma: number;
+  nFrames: number;
+  sampleRate: number;
+  hopLength: number;
+  features: Float32Array;
+  meanEnergy: number[];
+}
+
+interface WasmPitchResult {
+  f0: Float32Array;
+  voicedProb: Float32Array;
+  voicedFlag: boolean[];
+  nFrames: number;
+  medianF0: number;
+  meanF0: number;
+}
+
+interface WasmTrimResult {
+  audio: Float32Array;
+  startSample: number;
+  endSample: number;
+}
+
+interface WasmFrameResult {
+  nFrames: number;
+  frames: Float32Array;
+}
+
+interface WasmTempogramResult {
+  nFrames: number;
+  winLength: number;
+  data: Float32Array;
+}
+
+interface WasmMasteringResult {
+  samples: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  latencySamples?: number;
+}
+
+interface WasmMasteringChainResult extends WasmMasteringResult {
+  stages: string[];
+}
+
+interface WasmMasteringStereoChainResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  stages: string[];
+}
+
+interface WasmMasteringStereoResult {
+  left: Float32Array;
+  right: Float32Array;
+  sampleRate: number;
+  inputLufs: number;
+  outputLufs: number;
+  appliedGainDb: number;
+  latencySamples: number;
+}
+
+type ProgressCallback = (progress: number, stage: string) => void;
+
+interface SonareModule {
+  // Quick API (high-level)
+  detectBpm: (samples: Float32Array, sampleRate: number) => number;
+  detectKey: (samples: Float32Array, sampleRate: number) => WasmKeyResult;
+  detectOnsets: (samples: Float32Array, sampleRate: number) => Float32Array;
+  detectBeats: (samples: Float32Array, sampleRate: number) => Float32Array;
+  analyze: (samples: Float32Array, sampleRate: number) => WasmAnalysisResult;
+  analyzeWithProgress: (
+    samples: Float32Array,
+    sampleRate: number,
+    progressCallback: ProgressCallback | null,
+  ) => WasmAnalysisResult;
+  version: () => string;
+
+  // Effects
+  hpss: (
+    samples: Float32Array,
+    sampleRate: number,
+    kernelHarmonic: number,
+    kernelPercussive: number,
+  ) => WasmHpssResult;
+  harmonic: (samples: Float32Array, sampleRate: number) => Float32Array;
+  percussive: (samples: Float32Array, sampleRate: number) => Float32Array;
+  timeStretch: (samples: Float32Array, sampleRate: number, rate: number) => Float32Array;
+  pitchShift: (samples: Float32Array, sampleRate: number, semitones: number) => Float32Array;
+  normalize: (samples: Float32Array, sampleRate: number, targetDb: number) => Float32Array;
+  mastering: (
+    samples: Float32Array,
+    sampleRate: number,
+    targetLufs: number,
+    ceilingDb: number,
+    truePeakOversample: number,
+  ) => WasmMasteringResult;
+  masteringProcessorNames: () => string[];
+  masteringPairProcessorNames: () => string[];
+  masteringPairAnalysisNames: () => string[];
+  masteringStereoAnalysisNames: () => string[];
+  masteringProcess: (
+    processorName: string,
+    samples: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => WasmMasteringResult;
+  masteringProcessStereo: (
+    processorName: string,
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => WasmMasteringStereoResult;
+  masteringPairProcess: (
+    processorName: string,
+    source: Float32Array,
+    reference: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => WasmMasteringResult;
+  masteringPairAnalyze: (
+    analysisName: string,
+    source: Float32Array,
+    reference: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringStereoAnalyze: (
+    analysisName: string,
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    params: Record<string, number | boolean>,
+  ) => string;
+  masteringChain: (
+    samples: Float32Array,
+    sampleRate: number,
+    config: Record<string, unknown>,
+  ) => WasmMasteringChainResult;
+  masteringChainStereo: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    config: Record<string, unknown>,
+  ) => WasmMasteringStereoChainResult;
+  masteringChainWithProgress: (
+    samples: Float32Array,
+    sampleRate: number,
+    config: Record<string, unknown>,
+    progressCallback: ProgressCallback | null,
+  ) => WasmMasteringChainResult;
+  masteringChainStereoWithProgress: (
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    config: Record<string, unknown>,
+    progressCallback: ProgressCallback | null,
+  ) => WasmMasteringStereoChainResult;
+  masteringPresetNames: () => string[];
+  masterAudio: (
+    presetName: string,
+    samples: Float32Array,
+    sampleRate: number,
+    overrides: Record<string, number | boolean> | null,
+  ) => WasmMasteringChainResult;
+  masterAudioStereo: (
+    presetName: string,
+    left: Float32Array,
+    right: Float32Array,
+    sampleRate: number,
+    overrides: Record<string, number | boolean> | null,
+  ) => WasmMasteringStereoChainResult;
+  trim: (samples: Float32Array, sampleRate: number, thresholdDb: number) => Float32Array;
+
+  // Features - Spectrogram
+  stft: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => WasmStftResult;
+  stftDb: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => WasmStftDbResult;
+
+  // Features - Mel Spectrogram
+  melSpectrogram: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    nMels: number,
+  ) => WasmMelResult;
+  mfcc: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    nMels: number,
+    nMfcc: number,
+  ) => WasmMfccResult;
+
+  // Features - Chroma
+  chroma: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => WasmChromaResult;
+
+  // Features - Spectral
+  spectralCentroid: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => Float32Array;
+  spectralBandwidth: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => Float32Array;
+  spectralRolloff: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    rollPercent: number,
+  ) => Float32Array;
+  spectralFlatness: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+  ) => Float32Array;
+  zeroCrossingRate: (
+    samples: Float32Array,
+    sampleRate: number,
+    frameLength: number,
+    hopLength: number,
+  ) => Float32Array;
+  rmsEnergy: (
+    samples: Float32Array,
+    sampleRate: number,
+    frameLength: number,
+    hopLength: number,
+  ) => Float32Array;
+
+  // Features - Pitch
+  pitchYin: (
+    samples: Float32Array,
+    sampleRate: number,
+    frameLength: number,
+    hopLength: number,
+    fmin: number,
+    fmax: number,
+    threshold: number,
+  ) => WasmPitchResult;
+  pitchPyin: (
+    samples: Float32Array,
+    sampleRate: number,
+    frameLength: number,
+    hopLength: number,
+    fmin: number,
+    fmax: number,
+    threshold: number,
+  ) => WasmPitchResult;
+
+  // Core - Conversion
+  hzToMel: (hz: number) => number;
+  melToHz: (mel: number) => number;
+  hzToMidi: (hz: number) => number;
+  midiToHz: (midi: number) => number;
+  hzToNote: (hz: number) => string;
+  noteToHz: (note: string) => number;
+  framesToTime: (frames: number, sr: number, hopLength: number) => number;
+  timeToFrames: (time: number, sr: number, hopLength: number) => number;
+  framesToSamples: (frames: number, hopLength: number, nFft: number) => number;
+  samplesToFrames: (samples: number, hopLength: number, nFft: number) => number;
+  powerToDb: (values: Float32Array, ref: number, amin: number, topDb: number) => Float32Array;
+  amplitudeToDb: (values: Float32Array, ref: number, amin: number, topDb: number) => Float32Array;
+  dbToPower: (values: Float32Array, ref: number) => Float32Array;
+  dbToAmplitude: (values: Float32Array, ref: number) => Float32Array;
+  preemphasis: (samples: Float32Array, coef: number, zi?: number | null) => Float32Array;
+  deemphasis: (samples: Float32Array, coef: number, zi?: number | null) => Float32Array;
+  trimSilence: (
+    samples: Float32Array,
+    topDb: number,
+    frameLength: number,
+    hopLength: number,
+  ) => WasmTrimResult;
+  splitSilence: (
+    samples: Float32Array,
+    topDb: number,
+    frameLength: number,
+    hopLength: number,
+  ) => Int32Array;
+  frameSignal: (samples: Float32Array, frameLength: number, hopLength: number) => WasmFrameResult;
+  padCenter: (values: Float32Array, size: number, padValue: number) => Float32Array;
+  fixLength: (values: Float32Array, size: number, padValue: number) => Float32Array;
+  fixFrames: (frames: Int32Array, xMin: number, xMax: number, pad: boolean) => Int32Array;
+  peakPick: (
+    values: Float32Array,
+    preMax: number,
+    postMax: number,
+    preAvg: number,
+    postAvg: number,
+    delta: number,
+    wait: number,
+  ) => Int32Array;
+  vectorNormalize: (values: Float32Array, normType: number, threshold: number) => Float32Array;
+  pcen: (
+    values: Float32Array,
+    nBins: number,
+    nFrames: number,
+    options?: Record<string, number> | null,
+  ) => Float32Array;
+  tonnetz: (chromagram: Float32Array, nChroma: number, nFrames: number) => Float32Array;
+  tempogram: (
+    onsetEnvelope: Float32Array,
+    sampleRate: number,
+    hopLength: number,
+    winLength: number,
+  ) => WasmTempogramResult;
+  plp: (
+    onsetEnvelope: Float32Array,
+    sampleRate: number,
+    hopLength: number,
+    tempoMin: number,
+    tempoMax: number,
+    winLength: number,
+  ) => Float32Array;
+
+  // Core - Resample
+  resample: (samples: Float32Array, srcSr: number, targetSr: number) => Float32Array;
+
+  // Embind-exposed enums
+  PitchClass: {
+    C: { value: 0 };
+    Cs: { value: 1 };
+    D: { value: 2 };
+    Ds: { value: 3 };
+    E: { value: 4 };
+    F: { value: 5 };
+    Fs: { value: 6 };
+    G: { value: 7 };
+    Gs: { value: 8 };
+    A: { value: 9 };
+    As: { value: 10 };
+    B: { value: 11 };
+  };
+  Mode: {
+    Major: { value: 0 };
+    Minor: { value: 1 };
+  };
+  ChordQuality: {
+    Major: { value: 0 };
+    Minor: { value: 1 };
+    Diminished: { value: 2 };
+    Augmented: { value: 3 };
+    Dominant7: { value: 4 };
+    Major7: { value: 5 };
+    Minor7: { value: 6 };
+    Sus2: { value: 7 };
+    Sus4: { value: 8 };
+  };
+  SectionType: {
+    Intro: { value: 0 };
+    Verse: { value: 1 };
+    PreChorus: { value: 2 };
+    Chorus: { value: 3 };
+    Bridge: { value: 4 };
+    Instrumental: { value: 5 };
+    Outro: { value: 6 };
+  };
+
+  // Streaming - StreamAnalyzer
+  StreamAnalyzer: new (
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    nMels: number,
+    computeMel: boolean,
+    computeChroma: boolean,
+    computeOnset: boolean,
+    emitEveryNFrames: number,
+  ) => WasmStreamAnalyzer;
+
+  // Streaming - StreamingMasteringChain
+  createStreamingMasteringChain: (config: Record<string, unknown>) => WasmStreamingMasteringChain;
+}
+
+interface WasmStreamingMasteringChain {
+  prepare: (sampleRate: number, maxBlockSize: number, numChannels: number) => void;
+  processMono: (samples: Float32Array) => Float32Array;
+  processStereo: (
+    left: Float32Array,
+    right: Float32Array,
+  ) => { left: Float32Array; right: Float32Array };
+  reset: () => void;
+  latencySamples: () => number;
+  stageNames: () => string[];
+  delete: () => void;
+}
+
+// Streaming types for StreamAnalyzer
+interface WasmChordChange {
+  root: number;
+  quality: number;
+  startTime: number;
+  confidence: number;
+}
+
+interface WasmBarChord {
+  barIndex: number;
+  root: number;
+  quality: number;
+  startTime: number;
+  confidence: number;
+}
+
+interface WasmPatternScore {
+  name: string;
+  score: number;
+}
+
+interface WasmProgressiveEstimate {
+  bpm: number;
+  bpmConfidence: number;
+  bpmCandidateCount: number;
+  key: number;
+  keyMinor: boolean;
+  keyConfidence: number;
+  chordRoot: number;
+  chordQuality: number;
+  chordConfidence: number;
+  chordProgression: WasmChordChange[];
+  barChordProgression: WasmBarChord[];
+  currentBar: number;
+  barDuration: number;
+  votedPattern: WasmBarChord[];
+  patternLength: number;
+  detectedPatternName: string;
+  detectedPatternScore: number;
+  allPatternScores: WasmPatternScore[];
+  accumulatedSeconds: number;
+  usedFrames: number;
+  updated: boolean;
+}
+
+interface WasmAnalyzerStats {
+  totalFrames: number;
+  totalSamples: number;
+  durationSeconds: number;
+  estimate: WasmProgressiveEstimate;
+}
+
+interface WasmFrameBuffer {
+  nFrames: number;
+  timestamps: Float32Array;
+  mel: Float32Array;
+  chroma: Float32Array;
+  onsetStrength: Float32Array;
+  rmsEnergy: Float32Array;
+  spectralCentroid: Float32Array;
+  spectralFlatness: Float32Array;
+  chordRoot: Int32Array;
+  chordQuality: Int32Array;
+  chordConfidence: Float32Array;
+}
+
+interface WasmStreamAnalyzer {
+  process: (samples: Float32Array) => void;
+  processWithOffset: (samples: Float32Array, sampleOffset: number) => void;
+  availableFrames: () => number;
+  readFramesSoa: (maxFrames: number) => WasmFrameBuffer;
+  readFramesU8: (maxFrames: number) => unknown;
+  readFramesI16: (maxFrames: number) => unknown;
+  reset: (baseSampleOffset?: number) => void;
+  stats: () => WasmAnalyzerStats;
+  frameCount: () => number;
+  currentTime: () => number;
+  sampleRate: () => number;
+  setExpectedDuration: (durationSeconds: number) => void;
+  setNormalizationGain: (gain: number) => void;
+  setTuningRefHz: (refHz: number) => void;
+  delete: () => void;
+}
+
+declare function createModule(options?: SonareModuleOptions): Promise<SonareModule>;
+
+export default createModule;

package/src/stream_types.ts

@@ -0,0 +1,98 @@
+import type { ChordQuality, PitchClass } from './public_types';
+
+/**
+ * A detected chord change in the progression
+ */
+export interface ChordChange {
+  root: PitchClass;
+  quality: ChordQuality;
+  startTime: number;
+  confidence: number;
+}
+
+/**
+ * A chord detected at bar boundary (beat-synchronized)
+ */
+export interface BarChord {
+  barIndex: number;
+  root: PitchClass;
+  quality: ChordQuality;
+  startTime: number;
+  confidence: number;
+}
+
+/**
+ * Pattern score for known chord progressions
+ */
+export interface PatternScore {
+  name: string;
+  score: number;
+}
+
+/**
+ * Progressive estimation results for BPM, Key, and Chord
+ */
+export interface ProgressiveEstimate {
+  bpm: number;
+  bpmConfidence: number;
+  bpmCandidateCount: number;
+  key: PitchClass;
+  keyMinor: boolean;
+  keyConfidence: number;
+  chordRoot: PitchClass;
+  chordQuality: ChordQuality;
+  chordConfidence: number;
+  chordProgression: ChordChange[];
+  barChordProgression: BarChord[];
+  currentBar: number;
+  barDuration: number;
+  votedPattern: BarChord[];
+  patternLength: number;
+  detectedPatternName: string;
+  detectedPatternScore: number;
+  allPatternScores: PatternScore[];
+  accumulatedSeconds: number;
+  usedFrames: number;
+  updated: boolean;
+}
+
+/**
+ * Statistics and current state of the analyzer
+ */
+export interface AnalyzerStats {
+  totalFrames: number;
+  totalSamples: number;
+  durationSeconds: number;
+  estimate: ProgressiveEstimate;
+}
+
+/**
+ * Frame buffer with analysis results
+ */
+export interface FrameBuffer {
+  nFrames: number;
+  timestamps: Float32Array;
+  mel: Float32Array;
+  chroma: Float32Array;
+  onsetStrength: Float32Array;
+  rmsEnergy: Float32Array;
+  spectralCentroid: Float32Array;
+  spectralFlatness: Float32Array;
+  chordRoot: Int32Array;
+  chordQuality: Int32Array;
+  chordConfidence: Float32Array;
+}
+
+/**
+ * Configuration for StreamAnalyzer
+ */
+export interface StreamConfig {
+  sampleRate: number;
+  nFft?: number;
+  hopLength?: number;
+  nMels?: number;
+  computeMel?: boolean;
+  computeChroma?: boolean;
+  computeOnset?: boolean;
+  emitEveryNFrames?: number;
+}