@libraz/libsonare 1.2.3 → 1.3.0

package/src/stream_analyzer.ts

@@ -0,0 +1,275 @@
+import { getSonareModule } from './module_state';
+import type { ChordQuality, PitchClass } from './public_types';
+import type { WasmStreamAnalyzer } from './sonare.js';
+import type {
+  AnalyzerStats,
+  FrameBuffer,
+  StreamConfig,
+  StreamConfigDefaults,
+  StreamFramesI16,
+  StreamFramesU8,
+  StreamQuantizeConfig,
+} from './stream_types';
+
+// ============================================================================
+// StreamAnalyzer Class
+// ============================================================================
+
+export function streamAnalyzerConfigDefaults(): StreamConfigDefaults {
+  return getSonareModule().streamAnalyzerConfigDefault();
+}
+
+/**
+ * Real-time streaming audio analyzer.
+ *
+ * @example
+ * ```typescript
+ * import { init, StreamAnalyzer } from '@libraz/libsonare';
+ *
+ * await init();
+ *
+ * const analyzer = new StreamAnalyzer({ sampleRate: 44100 });
+ *
+ * // In audio processing callback
+ * analyzer.process(samples);
+ *
+ * // Get current analysis state
+ * const stats = analyzer.stats();
+ * console.log('BPM:', stats.estimate.bpm);
+ * console.log('Key:', stats.estimate.key);
+ * console.log('Chord progression:', stats.estimate.chordProgression);
+ * ```
+ */
+export class StreamAnalyzer {
+  private analyzer: WasmStreamAnalyzer;
+
+  /**
+   * Create a new StreamAnalyzer.
+   *
+   * @param config - Configuration options
+   */
+  constructor(config: StreamConfig = {}) {
+    if (config.computeMagnitude) {
+      throw new Error(
+        'computeMagnitude is not supported because magnitude frames are not exposed by StreamAnalyzer read paths.',
+      );
+    }
+    const module = getSonareModule();
+    const defaults = streamAnalyzerConfigDefaults();
+    this.analyzer = new module.StreamAnalyzer(
+      config.sampleRate ?? defaults.sampleRate,
+      config.nFft ?? defaults.nFft,
+      config.hopLength ?? defaults.hopLength,
+      config.nMels ?? defaults.nMels,
+      config.fmin ?? defaults.fmin,
+      config.fmax ?? defaults.fmax,
+      config.tuningRefHz ?? defaults.tuningRefHz,
+      config.computeMagnitude ?? defaults.computeMagnitude,
+      config.computeMel ?? defaults.computeMel,
+      config.computeChroma ?? defaults.computeChroma,
+      config.computeOnset ?? defaults.computeOnset,
+      config.computeSpectral ?? defaults.computeSpectral,
+      config.emitEveryNFrames ?? defaults.emitEveryNFrames,
+      config.magnitudeDownsample ?? defaults.magnitudeDownsample,
+      config.keyUpdateIntervalSec ?? defaults.keyUpdateIntervalSec,
+      config.bpmUpdateIntervalSec ?? defaults.bpmUpdateIntervalSec,
+      config.window ?? defaults.window,
+      config.outputFormat ?? defaults.outputFormat,
+    );
+  }
+
+  /**
+   * Process audio samples.
+   *
+   * @param samples - Audio samples (mono, float32)
+   */
+  process(samples: Float32Array): void {
+    this.analyzer.process(samples);
+  }
+
+  /**
+   * Process audio samples with explicit sample offset.
+   *
+   * @param samples - Audio samples (mono, float32)
+   * @param sampleOffset - Cumulative sample count at start of this chunk
+   */
+  processWithOffset(samples: Float32Array, sampleOffset: number): void {
+    this.analyzer.processWithOffset(samples, sampleOffset);
+  }
+
+  /**
+   * Flush the final partial frame with zero-padding.
+   */
+  finalize(): void {
+    this.analyzer.finalize();
+  }
+
+  /**
+   * Get the number of frames available to read.
+   */
+  availableFrames(): number {
+    return this.analyzer.availableFrames();
+  }
+
+  /**
+   * Read processed frames as Structure of Arrays.
+   *
+   * @param maxFrames - Maximum number of frames to read
+   * @returns Frame buffer with analysis results
+   */
+  readFrames(maxFrames: number): FrameBuffer {
+    return this.analyzer.readFramesSoa(maxFrames);
+  }
+
+  /**
+   * Read frames as uint8-quantized arrays.
+   *
+   * @param maxFrames - Maximum number of frames to read
+   * @param quantizeConfig - Optional quantization ranges; widen these for a
+   *   stream louder or quieter than the defaults (omitted keeps the defaults)
+   */
+  readFramesU8(maxFrames: number, quantizeConfig?: StreamQuantizeConfig): StreamFramesU8 {
+    return this.analyzer.readFramesU8(maxFrames, quantizeConfig) as StreamFramesU8;
+  }
+
+  /**
+   * Read frames as int16-quantized arrays.
+   *
+   * @param maxFrames - Maximum number of frames to read
+   * @param quantizeConfig - Optional quantization ranges; widen these for a
+   *   stream louder or quieter than the defaults (omitted keeps the defaults)
+   */
+  readFramesI16(maxFrames: number, quantizeConfig?: StreamQuantizeConfig): StreamFramesI16 {
+    return this.analyzer.readFramesI16(maxFrames, quantizeConfig) as StreamFramesI16;
+  }
+
+  /**
+   * Reset the analyzer state.
+   *
+   * @param baseSampleOffset - Starting sample offset (default 0)
+   */
+  reset(baseSampleOffset = 0): void {
+    this.analyzer.reset(baseSampleOffset);
+  }
+
+  /**
+   * Get current statistics and progressive estimates.
+   *
+   * @returns Analyzer statistics including BPM, key, and chord progression
+   */
+  stats(): AnalyzerStats {
+    const s = this.analyzer.stats();
+    return {
+      totalFrames: s.totalFrames,
+      totalSamples: s.totalSamples,
+      durationSeconds: s.durationSeconds,
+      estimate: {
+        bpm: s.estimate.bpm,
+        bpmConfidence: s.estimate.bpmConfidence,
+        bpmCandidateCount: s.estimate.bpmCandidateCount,
+        key: s.estimate.key as PitchClass,
+        keyMinor: s.estimate.keyMinor,
+        keyConfidence: s.estimate.keyConfidence,
+        chordRoot: s.estimate.chordRoot as PitchClass,
+        chordQuality: s.estimate.chordQuality as ChordQuality,
+        chordConfidence: s.estimate.chordConfidence,
+        chordStartTime: s.estimate.chordStartTime,
+        chordProgression: s.estimate.chordProgression.map((c) => ({
+          root: c.root as PitchClass,
+          quality: c.quality as ChordQuality,
+          startTime: c.startTime,
+          confidence: c.confidence,
+        })),
+        barChordProgression: s.estimate.barChordProgression.map((c) => ({
+          barIndex: c.barIndex,
+          root: c.root as PitchClass,
+          quality: c.quality as ChordQuality,
+          startTime: c.startTime,
+          confidence: c.confidence,
+        })),
+        currentBar: s.estimate.currentBar,
+        barDuration: s.estimate.barDuration,
+        votedPattern: (s.estimate.votedPattern || []).map((c) => ({
+          barIndex: c.barIndex,
+          root: c.root as PitchClass,
+          quality: c.quality as ChordQuality,
+          startTime: c.startTime,
+          confidence: c.confidence,
+        })),
+        patternLength: s.estimate.patternLength,
+        detectedPatternName: s.estimate.detectedPatternName || '',
+        detectedPatternScore: s.estimate.detectedPatternScore || 0,
+        allPatternScores: (s.estimate.allPatternScores || []).map((p) => ({
+          name: p.name,
+          score: p.score,
+        })),
+        accumulatedSeconds: s.estimate.accumulatedSeconds,
+        usedFrames: s.estimate.usedFrames,
+        updated: s.estimate.updated,
+      },
+    };
+  }
+
+  /**
+   * Get total frames processed.
+   */
+  frameCount(): number {
+    return this.analyzer.frameCount();
+  }
+
+  /**
+   * Get current time position in seconds.
+   */
+  currentTime(): number {
+    return this.analyzer.currentTime();
+  }
+
+  /**
+   * Get the sample rate.
+   */
+  sampleRate(): number {
+    return this.analyzer.sampleRate();
+  }
+
+  /**
+   * Set the expected total duration for pattern lock timing.
+   *
+   * @param durationSeconds - Total duration in seconds
+   */
+  setExpectedDuration(durationSeconds: number): void {
+    this.analyzer.setExpectedDuration(durationSeconds);
+  }
+
+  /**
+   * Set normalization gain for loud/compressed audio.
+   *
+   * @param gain - Gain factor to apply (e.g., 0.5 for -6dB reduction)
+   */
+  setNormalizationGain(gain: number): void {
+    this.analyzer.setNormalizationGain(gain);
+  }
+
+  /**
+   * Set tuning reference frequency for non-standard tuning.
+   *
+   * @param refHz - Reference frequency for A4 (default 440 Hz)
+   * @example
+   * // If audio is 1 semitone sharp (A4 = 466.16 Hz)
+   * analyzer.setTuningRefHz(466.16);
+   * // If audio is 1 semitone flat (A4 = 415.30 Hz)
+   * analyzer.setTuningRefHz(415.30);
+   */
+  setTuningRefHz(refHz: number): void {
+    this.analyzer.setTuningRefHz(refHz);
+  }
+
+  /** Release the underlying WASM object. Safe to call only once. */
+  delete(): void {
+    this.analyzer.delete();
+  }
+
+  /** Alias for {@link delete}, kept for backward compatibility (historical name). */
+  dispose(): void {
+    this.delete();
+  }
+}

package/src/stream_types.ts

@@ -86,6 +86,25 @@ export interface FrameBuffer {
   chordConfidence: Float32Array;
 }
 
+/**
+ * Quantization ranges for the uint8/int16 bandwidth-reduction read paths
+ * (`StreamAnalyzer.readFramesU8` / `readFramesI16`). Omitted fields fall back to
+ * the library defaults shown below; widen any range whose source values exceed
+ * the defaults, otherwise a louder/quieter stream saturates to the endpoints.
+ */
+export interface StreamQuantizeConfig {
+  /** dB floor for mel quantization (default -80). */
+  melDbMin?: number;
+  /** dB ceiling for mel quantization (default 0). */
+  melDbMax?: number;
+  /** Max expected onset strength (default 50). */
+  onsetMax?: number;
+  /** Max expected RMS energy (default 1). */
+  rmsMax?: number;
+  /** Max expected spectral centroid in Hz (default 11025). */
+  centroidMax?: number;
+}
+
 export interface StreamFramesU8 {
   nFrames: number;
   nMels: number;
@@ -112,9 +131,12 @@ export interface StreamFramesI16 {
 
 /**
  * Configuration for StreamAnalyzer
+ *
+ * Omitted values are read from the native StreamConfig defaults via
+ * streamAnalyzerConfigDefault(), keeping the WASM wrapper in sync with core.
  */
 export interface StreamConfig {
-  /** Sample rate in Hz. Optional for parity with the Node/Python bindings (default 44100). */
+  /** Sample rate in Hz. Optional for parity with the Node/Python bindings. */
   sampleRate?: number;
   nFft?: number;
   hopLength?: number;
@@ -122,6 +144,7 @@ export interface StreamConfig {
   fmin?: number;
   fmax?: number;
   tuningRefHz?: number;
+  /** Unsupported: no read path surfaces per-frame magnitude spectra. */
   computeMagnitude?: boolean;
   computeMel?: boolean;
   computeChroma?: boolean;
@@ -134,3 +157,5 @@ export interface StreamConfig {
   window?: number;
   outputFormat?: number;
 }
+
+export type StreamConfigDefaults = Required<StreamConfig>;

package/src/streaming_mixing.ts

@@ -0,0 +1,18 @@
+export type { MixerRealtimeBuffer } from './mixer';
+export { Mixer } from './mixer';
+export type {
+  RealtimeVoiceChangerInterleavedBuffer,
+  RealtimeVoiceChangerMonoBuffer,
+  RealtimeVoiceChangerPlanarBuffer,
+} from './realtime_voice_changer';
+export {
+  RealtimeVoiceChanger,
+  realtimeVoiceChangerPresetJson,
+  realtimeVoiceChangerPresetNames,
+  validateRealtimeVoiceChangerPresetJson,
+} from './realtime_voice_changer';
+export {
+  StreamingEqualizer,
+  StreamingMasteringChain,
+  StreamingRetune,
+} from './streaming_processors';

package/src/streaming_processors.ts

@@ -0,0 +1,335 @@
+import { getSonareModule } from './module_state';
+import type {
+  EqBand,
+  EqMatchOptions,
+  EqSpectrumSnapshot,
+  StreamingEqualizerConfig,
+  StreamingMasteringChainConfig,
+  StreamingRetuneConfig,
+} from './public_types';
+
+type EqPhaseMode =
+  | 'zero'
+  | 'zero-latency'
+  | 'zero_latency'
+  | 'natural'
+  | 'natural-phase'
+  | 'natural_phase'
+  | 'linear'
+  | 'linear-phase'
+  | 'linear_phase'
+  | number;
+
+const EQ_PHASE_MODES: Record<string, number> = {
+  zero: 1,
+  'zero-latency': 1,
+  zero_latency: 1,
+  natural: 2,
+  'natural-phase': 2,
+  natural_phase: 2,
+  linear: 3,
+  'linear-phase': 3,
+  linear_phase: 3,
+};
+
+// ============================================================================
+// StreamingMasteringChain Class
+// ============================================================================
+
+/**
+ * Block-by-block streaming variant of {@link masteringChain}.
+ *
+ * Maintains processor state across {@link processMono}/{@link processStereo}
+ * calls. Only ProcessorBase-backed stages are supported. Configurations that
+ * enable `repair.denoise` throw at construction. An enabled `loudness` stage
+ * also throws unless {@link StreamingMasteringChainConfig.loudnessStaticGainDb}
+ * supplies a precomputed normalization gain.
+ *
+ * Call {@link delete} (or use a `try/finally`) to release the underlying WASM
+ * object — the embind handle is not garbage-collected automatically.
+ *
+ * @example
+ * ```typescript
+ * const chain = new StreamingMasteringChain({ eq: { tiltDb: 1.0 } });
+ * try {
+ *   chain.prepare(44100, 512, 1);
+ *   const out = chain.processMono(blockSamples);
+ * } finally {
+ *   chain.delete();
+ * }
+ * ```
+ */
+export class StreamingMasteringChain {
+  private chain: import('./sonare.js').WasmStreamingMasteringChain;
+
+  constructor(config: StreamingMasteringChainConfig) {
+    const module = getSonareModule();
+    this.chain = module.createStreamingMasteringChain(config as Record<string, unknown>);
+  }
+
+  /**
+   * Initialize processors for the given sample rate and block layout.
+   *
+   * @param sampleRate - Sample rate in Hz
+   * @param maxBlockSize - Maximum block size per process call
+   * @param numChannels - 1 (mono) or 2 (stereo)
+   */
+  prepare(sampleRate: number, maxBlockSize: number, numChannels: number): void {
+    this.chain.prepare(sampleRate, maxBlockSize, numChannels);
+  }
+
+  /**
+   * Process one mono block, returning the processed samples (same length).
+   */
+  processMono(samples: Float32Array): Float32Array {
+    return this.chain.processMono(samples);
+  }
+
+  /**
+   * Process one stereo block, returning the processed channels.
+   */
+  processStereo(
+    left: Float32Array,
+    right: Float32Array,
+  ): { left: Float32Array; right: Float32Array } {
+    if (left.length !== right.length) {
+      throw new Error('Stereo channel lengths must match.');
+    }
+    return this.chain.processStereo(left, right);
+  }
+
+  /** Reset all processor state without rebuilding. */
+  reset(): void {
+    this.chain.reset();
+  }
+
+  /** Total reported latency in samples across all active processors. */
+  latencySamples(): number {
+    return this.chain.latencySamples();
+  }
+
+  /** Ordered stage names that will run (e.g. `"eq.tilt"`). */
+  stageNames(): string[] {
+    return this.chain.stageNames();
+  }
+
+  /** Release the underlying WASM object. Safe to call only once. */
+  delete(): void {
+    this.chain.delete();
+  }
+}
+
+// ============================================================================
+// StreamingEqualizer Class
+// ============================================================================
+
+/**
+ * Block-by-block streaming equalizer wrapping the unified C++
+ * `EqualizerProcessor` (up to 24 bands, RBJ/Vicanek biquads, dynamic EQ,
+ * linear-phase FIR, mid/side processing, and auto-gain).
+ *
+ * State is maintained across {@link processMono}/{@link processStereo} calls.
+ * Call {@link delete} (or use `try/finally`) to release the underlying WASM
+ * object — the embind handle is not garbage-collected automatically.
+ *
+ * @example
+ * ```typescript
+ * const eq = new StreamingEqualizer({ sampleRate: 48000, maxBlockSize: 512 });
+ * try {
+ *   eq.setBand(0, { type: 'HighShelf', frequencyHz: 8000, gainDb: 6, enabled: true });
+ *   const out = eq.processStereo(left, right);
+ *   const snapshot = eq.spectrum();
+ * } finally {
+ *   eq.delete();
+ * }
+ * ```
+ */
+export class StreamingEqualizer {
+  private eq: import('./sonare.js').WasmStreamingEqualizer;
+
+  constructor(config: StreamingEqualizerConfig = {}) {
+    const module = getSonareModule();
+    this.eq = module.createEqualizer(config as Record<string, unknown>);
+  }
+
+  /**
+   * Configure the band at `index` (0..23). Omitted fields use C++ defaults.
+   */
+  setBand(index: number, band: EqBand): void {
+    this.eq.setBand(index, band as Record<string, unknown>);
+  }
+
+  /** Disable and reset every band. */
+  clear(): void {
+    this.eq.clear();
+  }
+
+  /**
+   * Set the global phase mode: `'zero'` | `'natural'` | `'linear'` or 1/2/3.
+   */
+  setPhaseMode(mode: EqPhaseMode): void {
+    const value = typeof mode === 'number' ? mode : EQ_PHASE_MODES[mode.toLowerCase()];
+    if (value === undefined) {
+      throw new Error(`unknown EQ phase mode: ${mode}`);
+    }
+    this.eq.setPhaseMode(value);
+  }
+
+  /** Enable or disable output auto-gain compensation. */
+  setAutoGain(enabled: boolean): void {
+    this.eq.setAutoGain(enabled);
+  }
+
+  /** Set all-band EQ gain scale as a 0.0..2.0 multiplier. */
+  setGainScale(scale: number): void {
+    this.eq.setGainScale(scale);
+  }
+
+  /** Set post-EQ output gain in dB. */
+  setOutputGainDb(gainDb: number): void {
+    this.eq.setOutputGainDb(gainDb);
+  }
+
+  /** Set post-EQ stereo balance in -1.0..1.0; mono input ignores pan. */
+  setOutputPan(pan: number): void {
+    this.eq.setOutputPan(pan);
+  }
+
+  /**
+   * Provide a mono external sidechain key for dynamic bands that opt into
+   * `external_sidechain`. The samples are copied into an owned buffer.
+   */
+  setSidechainMono(samples: Float32Array): void {
+    this.eq.setSidechainMono(samples);
+  }
+
+  /**
+   * Provide a stereo external sidechain key. Both channels must match length.
+   */
+  setSidechainStereo(left: Float32Array, right: Float32Array): void {
+    if (left.length !== right.length) {
+      throw new Error('Sidechain channel lengths must match.');
+    }
+    this.eq.setSidechainStereo(left, right);
+  }
+
+  /** Release any borrowed external sidechain buffers. */
+  clearSidechain(): void {
+    this.eq.clearSidechain();
+  }
+
+  /** Auto-gain applied on the most recent block, in dB. */
+  lastAutoGainDb(): number {
+    return this.eq.lastAutoGainDb();
+  }
+
+  /** Reported processing latency in samples (non-zero for linear-phase bands). */
+  latencySamples(): number {
+    return this.eq.latencySamples();
+  }
+
+  /**
+   * Process one mono block, returning the equalized samples (same length).
+   */
+  processMono(samples: Float32Array): Float32Array {
+    return this.eq.processMono(samples);
+  }
+
+  /**
+   * Process one stereo block, returning the equalized channels.
+   */
+  processStereo(
+    left: Float32Array,
+    right: Float32Array,
+  ): { left: Float32Array; right: Float32Array } {
+    if (left.length !== right.length) {
+      throw new Error('Stereo channel lengths must match.');
+    }
+    return this.eq.processStereo(left, right);
+  }
+
+  /**
+   * Read the latest pre/post spectrum snapshot for metering. `seq` increments
+   * each time a new snapshot is published.
+   */
+  spectrum(): EqSpectrumSnapshot {
+    return this.eq.spectrum();
+  }
+
+  /**
+   * Configure bands so the source spectrum matches the reference spectrum.
+   *
+   * @param source - Source audio (mono samples)
+   * @param reference - Reference audio (mono samples)
+   * @param options - `sampleRate` (default 48000) and `maxBands` (default 8)
+   */
+  match(source: Float32Array, reference: Float32Array, options: EqMatchOptions = {}): void {
+    this.eq.match(source, reference, options as Record<string, unknown>);
+  }
+
+  /** Release the underlying WASM object. Safe to call only once. */
+  delete(): void {
+    this.eq.delete();
+  }
+}
+
+// ============================================================================
+// StreamingRetune Class
+// ============================================================================
+
+/**
+ * Block-by-block mono voice retune / pitch shifter.
+ *
+ * State is maintained across {@link processMono} calls. Call {@link prepare}
+ * before processing, and call {@link delete} (or use `try/finally`) to release
+ * the underlying WASM object.
+ */
+export class StreamingRetune {
+  private retune: import('./sonare.js').WasmStreamingRetune;
+
+  constructor(config: StreamingRetuneConfig = {}) {
+    const module = getSonareModule();
+    this.retune = module.createStreamingRetune(config as Record<string, unknown>);
+  }
+
+  /**
+   * Allocate and initialize native state for the given sample rate and maximum
+   * process block size.
+   */
+  prepare(sampleRate: number, maxBlockSize: number): void {
+    this.retune.prepare(sampleRate, maxBlockSize);
+  }
+
+  /** Reset delay, grain, and overlap-add state without changing config. */
+  reset(): void {
+    this.retune.reset();
+  }
+
+  /**
+   * Update retune settings. Changing `grainSize` takes effect after the next
+   * {@link prepare} call.
+   */
+  setConfig(config: StreamingRetuneConfig): void {
+    this.retune.setConfig(config as Record<string, unknown>);
+  }
+
+  /** Current native config. */
+  config(): Required<StreamingRetuneConfig> {
+    return this.retune.config();
+  }
+
+  /** Resolved grain size in samples after {@link prepare}. */
+  grainSize(): number {
+    return this.retune.grainSize();
+  }
+
+  /** Process one mono block, returning the shifted samples (same length). */
+  processMono(samples: Float32Array): Float32Array {
+    return this.retune.processMono(samples);
+  }
+
+  /** Release the underlying WASM object. Safe to call only once. */
+  delete(): void {
+    this.retune.delete();
+  }
+}