@libraz/libsonare 1.4.0 → 1.5.0

package/src/effects_transform.ts

@@ -0,0 +1,286 @@
+import { getSonareModule } from './module_state';
+import type {
+  HpssResult,
+  NoteStretchOptions,
+  PitchCorrectOptions,
+  SpectralEditOptions,
+  SpectralRegionOp,
+} from './public_types';
+import type { ValidateOptions } from './validation';
+import { assertSampleRate, assertSamples } from './validation';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+// ============================================================================
+// Effects
+// ============================================================================
+
+/**
+ * Perform Harmonic-Percussive Source Separation (HPSS).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param kernelHarmonic - Horizontal median filter size for harmonic (default: 31)
+ * @param kernelPercussive - Vertical median filter size for percussive (default: 31)
+ * @returns Separated harmonic and percussive components
+ */
+export function hpss(
+  samples: Float32Array,
+  sampleRate = 22050,
+  kernelHarmonic = 31,
+  kernelPercussive = 31,
+): HpssResult {
+  return requireModule().hpss(samples, sampleRate, kernelHarmonic, kernelPercussive);
+}
+
+/**
+ * Extract harmonic component from audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @returns Harmonic component
+ */
+export function harmonic(
+  samples: Float32Array,
+  sampleRate: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('harmonic', samples, options.validate !== false);
+  return requireModule().harmonic(samples, sampleRate);
+}
+
+/**
+ * Extract percussive component from audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @returns Percussive component
+ */
+export function percussive(
+  samples: Float32Array,
+  sampleRate: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('percussive', samples, options.validate !== false);
+  return requireModule().percussive(samples, sampleRate);
+}
+
+/**
+ * Time-stretch audio without changing pitch.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
+ * @returns Time-stretched audio
+ */
+export function timeStretch(
+  samples: Float32Array,
+  sampleRate: number,
+  rate: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('timeStretch', samples, options.validate !== false);
+  return requireModule().timeStretch(samples, sampleRate, rate);
+}
+
+/**
+ * Pitch-shift audio without changing duration.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param semitones - Pitch shift in semitones (+12 = one octave up, -12 = one octave down)
+ * @returns Pitch-shifted audio
+ */
+export function pitchShift(
+  samples: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('pitchShift', samples, options.validate !== false);
+  return requireModule().pitchShift(samples, sampleRate, semitones);
+}
+
+/**
+ * Pitch-correct audio from a current MIDI note to a target MIDI note.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param currentMidi - Detected/current MIDI note number
+ * @param targetMidi - Desired MIDI note number
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectToMidi(
+  samples: Float32Array,
+  sampleRate = 22050,
+  currentMidi = 69.0,
+  targetMidi = 69.0,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('pitchCorrectToMidi', samples, options.validate !== false);
+  return requireModule().pitchCorrectToMidi(samples, sampleRate, currentMidi, targetMidi);
+}
+
+/**
+ * Contour-following ("time-varying") pitch correction toward a MIDI target.
+ *
+ * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
+ * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
+ * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
+ * flattened. `voiced` (non-zero = voiced) and `voicedProb` ([0,1]) are optional;
+ * omitting them treats every frame as voiced.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
+ * @param targetMidi - Desired MIDI note number
+ * @param sampleRate - Sample rate in Hz
+ * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
+ * @param voiced - Optional per-frame voiced flags (non-zero = voiced)
+ * @param voicedProb - Optional per-frame voicing probability in [0, 1]
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectToMidiTimevarying(
+  samples: Float32Array,
+  f0Hz: Float32Array,
+  targetMidi: number,
+  sampleRate = 22050,
+  hopLength = 512,
+  voiced?: Int32Array,
+  voicedProb?: Float32Array,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('pitchCorrectToMidiTimevarying', samples, options.validate !== false);
+  if (voiced && voiced.length !== f0Hz.length) {
+    throw new RangeError('pitchCorrectToMidiTimevarying: voiced length must match f0Hz length');
+  }
+  if (voicedProb && voicedProb.length !== f0Hz.length) {
+    throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
+  }
+  // The embind layer reads the companion arrays as Float32Array (voiced uses
+  // 0.0/1.0); convert here so a single native conversion path suffices.
+  const voicedF32 = voiced ? Float32Array.from(voiced) : undefined;
+  return requireModule().pitchCorrectToMidiTimevarying(
+    samples,
+    sampleRate,
+    f0Hz,
+    targetMidi,
+    hopLength,
+    voicedF32,
+    voicedProb,
+  );
+}
+
+/**
+ * Contour-following pitch correction toward a fixed MIDI note OR a musical
+ * scale, with tunable retune strength and vibrato preservation.
+ *
+ * Generalises {@link pitchCorrectToMidiTimevarying}: the same caller-supplied
+ * per-frame `f0Hz` contour drives correction, but `options.mode` selects between
+ * a fixed-MIDI target (`'midi'`, default) and scale quantisation (`'scale'`),
+ * and the retune knobs shape natural-vs-robotic correction.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
+ * @param sampleRate - Sample rate in Hz
+ * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
+ * @param options - Target mode + retune knobs + optional voiced/voicedProb arrays
+ * @returns Pitch-corrected audio
+ */
+export function pitchCorrectTimevarying(
+  samples: Float32Array,
+  f0Hz: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  options: PitchCorrectOptions = {},
+): Float32Array {
+  assertSamples('pitchCorrectTimevarying', samples, options.validate !== false);
+  if (options.voiced && options.voiced.length !== f0Hz.length) {
+    throw new RangeError('pitchCorrectTimevarying: voiced length must match f0Hz length');
+  }
+  if (options.voicedProb && options.voicedProb.length !== f0Hz.length) {
+    throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
+  }
+  // The embind layer reads the companion arrays as Float32Array (voiced uses
+  // 0.0/1.0); convert here so a single native conversion path suffices.
+  const nativeOptions = {
+    ...options,
+    voiced: options.voiced ? Float32Array.from(options.voiced) : undefined,
+  };
+  return requireModule().pitchCorrectTimevarying(
+    samples,
+    sampleRate,
+    f0Hz,
+    hopLength,
+    nativeOptions,
+  );
+}
+
+/**
+ * Time-stretch a note region between two sample offsets without changing pitch.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param onsetSample - Note onset position in samples
+ * @param offsetSample - Note offset position in samples
+ * @param stretchRatio - Stretch ratio (0.5 = double duration, 2.0 = half duration)
+ * @returns Audio with the note region stretched
+ */
+export function noteStretch(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: NoteStretchOptions & ValidateOptions = {},
+): Float32Array {
+  assertSamples('noteStretch', samples, options.validate !== false);
+  return requireModule().noteStretch(
+    samples,
+    sampleRate,
+    options.onsetSample ?? 0,
+    options.offsetSample ?? 0,
+    options.stretchRatio ?? 1.0,
+  );
+}
+
+/**
+ * Normalize audio to target peak level.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
+ * @returns Normalized audio
+ */
+export function normalize(
+  samples: Float32Array,
+  sampleRate: number,
+  targetDb = 0.0,
+  options: ValidateOptions = {},
+): Float32Array {
+  assertSamples('normalize', samples, options.validate !== false);
+  return requireModule().normalize(samples, sampleRate, targetDb);
+}
+
+/**
+ * Apply region-based spectral edits (gain/attenuate/mute/heal) to mono audio.
+ *
+ * Each op is a time x frequency rectangle applied in array order over a single
+ * STFT buffer, so a later op observes the result of earlier ops. The output has
+ * the same length and sample rate as the input; an empty `ops` list is an
+ * identity transform (within the iSTFT's own tolerance).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param ops - Region edit ops applied in order ({@link SpectralRegionOp})
+ * @param options - STFT + heal configuration ({@link SpectralEditOptions})
+ * @returns Edited audio
+ */
+export function spectralEdit(
+  samples: Float32Array,
+  sampleRate: number,
+  ops: SpectralRegionOp[] = [],
+  options: SpectralEditOptions & ValidateOptions = {},
+): Float32Array {
+  assertSamples('spectralEdit', samples, options.validate !== false);
+  assertSampleRate('spectralEdit', sampleRate);
+  return requireModule().spectralEdit(samples, sampleRate, ops, options as Record<string, unknown>);
+}

package/src/effects_voice_change.ts

@@ -0,0 +1,118 @@
+import { getSonareModule } from './module_state';
+import type { RealtimeVoiceChangerConfigInput } from './public_types';
+import { RealtimeVoiceChanger } from './streaming_mixing';
+import type { ValidateOptions } from './validation';
+import { assertSamples } from './validation';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+/** Options for {@link voiceChange}. All fields are optional. */
+export interface VoiceChangeOptions extends ValidateOptions {
+  /** Pitch shift in semitones (negative = down). Default 0. */
+  pitchSemitones?: number;
+  /** Formant scale factor (>1 brightens, <1 darkens). Default 1. */
+  formantFactor?: number;
+}
+
+/**
+ * Apply a voice change by shifting pitch and formants independently.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param options - Pitch/formant settings ({@link VoiceChangeOptions})
+ * @returns Voice-changed audio
+ */
+export function voiceChange(
+  samples: Float32Array,
+  sampleRate = 22050,
+  options: VoiceChangeOptions = {},
+): Float32Array {
+  assertSamples('voiceChange', samples, options.validate !== false);
+  return requireModule().voiceChange(
+    samples,
+    sampleRate,
+    options.pitchSemitones ?? 0.0,
+    options.formantFactor ?? 1.0,
+  );
+}
+
+/** Options for the offline {@link voiceChangeRealtime} convenience wrapper. */
+export interface VoiceChangeRealtimeOptions extends ValidateOptions {
+  sampleRate?: number;
+  /** Voice-changer preset id or full config object. */
+  preset?: RealtimeVoiceChangerConfigInput;
+  /** Channel count (1 = mono, 2 = interleaved stereo). */
+  channels?: 1 | 2;
+  /** Block size for the internal render loop (default 512). */
+  blockSize?: number;
+}
+
+function latencyCompensatedVoiceChange(
+  changer: RealtimeVoiceChanger,
+  samples: Float32Array,
+  channels: 1 | 2,
+  blockFrames: number,
+): Float32Array {
+  const latencyFrames = Math.max(0, changer.latencySamples());
+  if (channels === 1) {
+    const total = samples.length + latencyFrames;
+    const input = new Float32Array(total);
+    input.set(samples);
+    const processed = new Float32Array(total);
+    for (let offset = 0; offset < total; offset += blockFrames) {
+      const block = input.subarray(offset, Math.min(offset + blockFrames, total));
+      processed.set(changer.processMono(block), offset);
+    }
+    return processed.slice(latencyFrames, latencyFrames + samples.length);
+  }
+
+  const frames = samples.length / 2;
+  const totalFrames = frames + latencyFrames;
+  const input = new Float32Array(totalFrames * 2);
+  input.set(samples);
+  const processed = new Float32Array(totalFrames * 2);
+  const frameStride = blockFrames * 2;
+  for (let offset = 0; offset < input.length; offset += frameStride) {
+    const block = input.subarray(offset, Math.min(offset + frameStride, input.length));
+    processed.set(changer.processInterleaved(block, 2), offset);
+  }
+  const start = latencyFrames * 2;
+  return processed.slice(start, start + samples.length);
+}
+
+/**
+ * Applies the realtime voice-changer chain to a whole buffer in one call.
+ *
+ * Constructs and prepares a {@link RealtimeVoiceChanger}, runs the block loop
+ * for the caller, then disposes it — matching the Python `voice_change_realtime`
+ * and Node `voiceChangeRealtime` convenience wrappers. For mono, `samples` is a
+ * plain mono buffer; for stereo, `samples` is interleaved (L0,R0,L1,R1,...).
+ *
+ * @returns The processed buffer (same layout/length as the input).
+ */
+export function voiceChangeRealtime(
+  samples: Float32Array,
+  options: VoiceChangeRealtimeOptions = {},
+): Float32Array {
+  assertSamples('voiceChangeRealtime', samples, options.validate !== false);
+  const channels = options.channels ?? 1;
+  if (channels !== 1 && channels !== 2) {
+    throw new Error('voiceChangeRealtime: channels must be 1 or 2.');
+  }
+  if (channels === 2 && samples.length % 2 !== 0) {
+    throw new Error('voiceChangeRealtime: stereo input length must be a multiple of 2.');
+  }
+  // 48000 matches the Python voice_change_realtime and Node voiceChangeRealtime
+  // convenience wrappers (and the RealtimeVoiceChanger default).
+  const sampleRate = options.sampleRate ?? 48000;
+  const blockSize = Math.max(1, Math.floor(options.blockSize ?? 512));
+  const changer = new RealtimeVoiceChanger(options.preset ?? 'neutral-monitor');
+  try {
+    changer.prepare(sampleRate, blockSize, channels);
+    return latencyCompensatedVoiceChange(changer, samples, channels, blockSize);
+  } finally {
+    changer.delete();
+  }
+}

package/src/feature_music.ts

@@ -204,15 +204,19 @@ export function analyzeSections(
   if ((options.minSectionSec ?? 4.0) <= 0) {
     throw new RangeError('analyzeSections: minSectionSec must be positive');
   }
-  return requireModule()
-    .analyzeSections(
-      samples,
-      sampleRate,
-      options.nFft ?? 2048,
-      options.hopLength ?? 512,
-      options.minSectionSec ?? 4.0,
-    )
-    .map((s) => ({ ...s, type: s.type as SectionType }));
+  // The embind value marshalling returns an array whose constructor is not this
+  // realm's Array; chaining .map() onto it propagates that constructor via
+  // Symbol.species, leaving a result that structuredClone (and so postMessage to
+  // a Worker) rejects with "could not be cloned". Array.from() re-roots it as a
+  // plain Array before mapping.
+  const sections = requireModule().analyzeSections(
+    samples,
+    sampleRate,
+    options.nFft ?? 2048,
+    options.hopLength ?? 512,
+    options.minSectionSec ?? 4.0,
+  );
+  return Array.from(sections, (s) => ({ ...s, type: s.type as SectionType }));
 }
 
 /** Options for {@link analyzeMelody}. All fields are optional. */

package/src/feature_spectrogram.ts

@@ -160,6 +160,27 @@ export function chromaCens(
   return requireModule().chromaCens(samples, sampleRate, hopLength, nChroma);
 }
 
+/**
+ * Compute a constant-Q chromagram (librosa.feature.chroma_cqt).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param hopLength - Hop length (default: 512)
+ * @param nChroma - Number of chroma bins (default: 12)
+ * @returns Chroma result
+ */
+export function chromaCqt(
+  samples: Float32Array,
+  sampleRate = 22050,
+  hopLength = 512,
+  nChroma = 12,
+  options: GuardedOptions = {},
+): ChromaResult {
+  validateSpectrogramSamples('chromaCqt', samples, sampleRate, options);
+  validatePositiveIntegers('chromaCqt', { hopLength, nChroma });
+  return requireModule().chromaCqt(samples, sampleRate, hopLength, nChroma);
+}
+
 /**
  * Compute low-frequency bass chroma.
  *
@@ -237,6 +258,7 @@ export function melSpectrogram(
  * @param fmin - Minimum Mel frequency in Hz (default: 0 = librosa default)
  * @param fmax - Maximum Mel frequency in Hz (default: 0 = sampleRate / 2)
  * @param htk - Use the HTK Mel formula instead of Slaney (default: false)
+ * @param lifter - Cepstral liftering coefficient (default: 0 = no liftering)
  * @returns MFCC result
  */
 export function mfcc(
@@ -249,12 +271,24 @@ export function mfcc(
   fmin = 0,
   fmax = 0,
   htk = false,
+  lifter = 0,
   options: GuardedOptions = {},
 ): MfccResult {
   validateSpectrogramSamples('mfcc', samples, sampleRate, options);
   validatePositiveIntegers('mfcc', { nFft, hopLength, nMels, nMfcc });
   validateMelFrequencyRange('mfcc', fmin, fmax, sampleRate);
-  return requireModule().mfcc(samples, sampleRate, nFft, hopLength, nMels, nMfcc, fmin, fmax, htk);
+  return requireModule().mfcc(
+    samples,
+    sampleRate,
+    nFft,
+    hopLength,
+    nMels,
+    nMfcc,
+    fmin,
+    fmax,
+    htk,
+    lifter,
+  );
 }
 
 // ============================================================================
@@ -433,7 +467,13 @@ export function mfccToAudio(
 // ============================================================================
 
 /**
- * Compute chromagram (pitch class distribution).
+ * Compute STFT chromagram (librosa.feature.chroma_stft).
+ *
+ * The chroma filterbank uses a fixed tuning of 0 (concert A440). Unlike
+ * librosa.feature.chroma_stft — which estimates tuning from the signal when none
+ * is given — this does NOT auto-estimate and exposes no tuning argument, so
+ * sharp/flat (non-A440) recordings smear across pitch classes. Estimate tuning
+ * separately via {@link estimateTuning} if a non-A440 reference matters.
  *
  * @param samples - Audio samples (mono, float32)
  * @param sampleRate - Sample rate in Hz (default: 22050)

package/src/features.ts

@@ -72,6 +72,7 @@ export {
   bassChroma,
   chroma,
   chromaCens,
+  chromaCqt,
   melSpectrogram,
   melToAudio,
   melToStft,

package/src/index.ts

@@ -29,6 +29,14 @@ import type {
 
 export type { BrowserAudioDecodeOptions } from './audio';
 export { Audio } from './audio';
+export type {
+  ClipPageStreamerEngine,
+  ClipPageStreamerOptions,
+  ClipPageStreamSource,
+  OpfsClipStream,
+  OpfsClipStreamOptions,
+} from './clip_page_streamer';
+export { attachOpfsClipStream, ClipPageStreamer } from './clip_page_streamer';
 export type {
   CompressorDetector,
   CompressorOptions,
@@ -97,6 +105,7 @@ export {
   normalize,
   noteStretch,
   percussive,
+  pitchCorrectTimevarying,
   pitchCorrectToMidi,
   pitchCorrectToMidiTimevarying,
   pitchShift,
@@ -114,6 +123,7 @@ export {
   bassChroma,
   chroma,
   chromaCens,
+  chromaCqt,
   cqt,
   cyclicTempogram,
   dbToAmplitude,
@@ -343,6 +353,7 @@ export type {
   PairProcessor,
   PanLaw,
   PanMode,
+  PitchCorrectOptions,
   PitchResult,
   RealtimeVoiceChangerConfigInput,
   RealtimeVoiceChangerPodConfig,