@libraz/libsonare 1.5.5 → 1.6.0

package/src/feature_spectrogram.ts

@@ -4,6 +4,7 @@ import type {
   MelPowerResult,
   MelSpectrogramResult,
   MfccResult,
+  ReassignedSpectrogramResult,
   StftPowerResult,
   StftResult,
 } from './public_types';
@@ -49,6 +50,17 @@ export interface MfccRequest extends MelSpectrogramRequest {
   lifter?: number;
 }
 
+export interface MelDeltaRequest extends GuardedOptions {
+  features: Float32Array;
+  nFeatures: number;
+  nFrames: number;
+  width?: number;
+}
+export interface ReassignedSpectrogramRequest extends SpectrogramRequest {
+  refPower?: number;
+  fillNan?: boolean;
+}
+
 export interface MfccToMelRequest extends GuardedOptions {
   mfccCoefficients: Float32Array;
   nMfcc: number;
@@ -75,6 +87,16 @@ export interface MelToAudioRequest extends MelToStftRequest {
   hopLength?: number;
   nIter?: number;
 }
+export interface GriffinLimRequest extends GuardedOptions {
+  magnitude: Float32Array;
+  nBins: number;
+  nFrames: number;
+  sampleRate?: number;
+  nFft?: number;
+  hopLength?: number;
+  nIter?: number;
+  momentum?: number;
+}
 
 /** Canonical request form for Griffin-Lim reconstruction from MFCCs. */
 export interface MfccToAudioRequest extends MfccToMelRequest {
@@ -524,6 +546,90 @@ export function mfcc(
   );
 }
 
+/** First-order regression delta of a row-major feature matrix. */
+export function melDelta(request: MelDeltaRequest): Float32Array;
+export function melDelta(
+  features: Float32Array,
+  nFeatures: number,
+  nFrames: number,
+  width?: number,
+): Float32Array;
+export function melDelta(
+  features: Float32Array | MelDeltaRequest,
+  nFeatures?: number,
+  nFrames?: number,
+  width = 9,
+): Float32Array {
+  const request: MelDeltaRequest =
+    features instanceof Float32Array
+      ? { features, nFeatures: nFeatures ?? 0, nFrames: nFrames ?? 0, width }
+      : features;
+  assertPositiveInteger('melDelta', request.nFeatures, 'nFeatures');
+  assertPositiveInteger('melDelta', request.nFrames, 'nFrames');
+  assertPositiveInteger('melDelta', request.width ?? 9, 'width');
+  if ((request.width ?? 9) < 3 || (request.width ?? 9) % 2 === 0) {
+    throw new RangeError('melDelta: width must be an odd integer of at least 3');
+  }
+  if (request.features.length !== request.nFeatures * request.nFrames) {
+    throw new RangeError('melDelta: feature matrix length must equal nFeatures * nFrames');
+  }
+  return requireModule().melDelta(
+    request.features,
+    request.nFeatures,
+    request.nFrames,
+    request.width ?? 9,
+  );
+}
+
+/** Auger-Flandrin reassigned spectrogram (row-major [nBins x nFrames] arrays). */
+export function reassignedSpectrogram(
+  request: ReassignedSpectrogramRequest,
+): ReassignedSpectrogramResult;
+export function reassignedSpectrogram(
+  samples: Float32Array,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  refPower?: number,
+  fillNan?: boolean,
+): ReassignedSpectrogramResult;
+export function reassignedSpectrogram(
+  samples: Float32Array | ReassignedSpectrogramRequest,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  refPower = 1e-6,
+  fillNan = false,
+): ReassignedSpectrogramResult {
+  if (!(samples instanceof Float32Array)) {
+    const request = samples;
+    return reassignedSpectrogram(
+      request.samples,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.refPower,
+      request.fillNan,
+    );
+  }
+  assertSamples('reassignedSpectrogram', samples, true);
+  assertSampleRate('reassignedSpectrogram', sampleRate);
+  assertPositiveInteger('reassignedSpectrogram', nFft, 'nFft');
+  assertPositiveInteger('reassignedSpectrogram', hopLength, 'hopLength');
+  assertFiniteScalar('reassignedSpectrogram', refPower, 'refPower');
+  if (refPower < 0) {
+    throw new RangeError('reassignedSpectrogram: refPower must be non-negative');
+  }
+  return requireModule().reassignedSpectrogram(
+    samples,
+    sampleRate,
+    nFft,
+    hopLength,
+    refPower,
+    fillNan,
+  );
+}
+
 // ============================================================================
 // Features - Inverse reconstruction
 // ============================================================================
@@ -663,6 +769,59 @@ export function melToAudio(
   );
 }
 
+/** Reconstruct audio from an STFT magnitude matrix via Griffin-Lim. */
+export function griffinLim(request: GriffinLimRequest): Float32Array;
+export function griffinLim(
+  magnitude: Float32Array,
+  nBins: number,
+  nFrames: number,
+  sampleRate?: number,
+  nFft?: number,
+  hopLength?: number,
+  nIter?: number,
+  momentum?: number,
+  options?: GuardedOptions,
+): Float32Array;
+export function griffinLim(
+  magnitude: Float32Array | GriffinLimRequest,
+  nBins = 0,
+  nFrames = 0,
+  sampleRate = 22050,
+  nFft = 2048,
+  hopLength = 512,
+  nIter = 32,
+  momentum = 0.99,
+  options: GuardedOptions = {},
+): Float32Array {
+  if (!(magnitude instanceof Float32Array)) {
+    const request = magnitude;
+    return griffinLim(
+      request.magnitude,
+      request.nBins,
+      request.nFrames,
+      request.sampleRate,
+      request.nFft,
+      request.hopLength,
+      request.nIter,
+      request.momentum,
+      request,
+    );
+  }
+  assertSampleRate('griffinLim', sampleRate);
+  validateMatrix('griffinLim', magnitude, nBins, nFrames, 'magnitude', 'nBins', options);
+  validatePositiveIntegers('griffinLim', { nFft, hopLength, nIter });
+  return requireModule().griffinLim(
+    magnitude,
+    nBins,
+    nFrames,
+    sampleRate,
+    nFft,
+    hopLength,
+    nIter,
+    momentum,
+  );
+}
+
 /**
  * Invert MFCC coefficients back to a Mel power spectrogram. Mirrors
  * `feature::mfcc_to_mel`.

package/src/features.ts

@@ -1,5 +1,7 @@
 export {
   amplitudeToDb,
+  chirp,
+  clicks,
   cyclicTempogram,
   dbToAmplitude,
   dbToPower,
@@ -15,6 +17,7 @@ export {
   melToHz,
   midiToHz,
   noteToHz,
+  onsetBacktrack,
   padCenter,
   pcen,
   peakPick,
@@ -25,6 +28,7 @@ export {
   splitSilence,
   tempogram,
   timeToFrames,
+  tone,
   tonnetz,
   trimSilence,
   vectorNormalize,
@@ -47,7 +51,7 @@ export {
   vqt,
   vqtToAudio,
 } from './feature_music';
-export { pitchPyin, pitchYin } from './feature_pitch';
+export { noteSegments, piptrack, pitchPyin, pitchYin } from './feature_pitch';
 export { resample } from './feature_resample';
 export {
   decompose,
@@ -62,10 +66,18 @@ export {
   polyFeatures,
   remix,
   rmsEnergy,
+  segmentAgglomerative,
+  segmentCrossSimilarity,
+  segmentLagToRecurrence,
+  segmentPathEnhance,
+  segmentRecurrenceMatrix,
+  segmentRecurrenceToLag,
+  segmentSubsegment,
   spectralBandwidth,
   spectralCentroid,
   spectralContrast,
   spectralFlatness,
+  spectralFlux,
   spectralRolloff,
   zeroCrossingRate,
   zeroCrossings,
@@ -75,12 +87,15 @@ export {
   chroma,
   chromaCens,
   chromaCqt,
+  griffinLim,
+  melDelta,
   melSpectrogram,
   melToAudio,
   melToStft,
   mfcc,
   mfccToAudio,
   mfccToMel,
+  reassignedSpectrogram,
   stft,
   stftDb,
   trim,

package/src/index.ts

@@ -19,7 +19,12 @@
  */
 
 import { setSonareModule } from './module_state';
-import type { RealtimeVoiceChangerPodConfig, VoicePresetId } from './public_types';
+import type {
+  CapabilityCatalog,
+  RealtimeVoiceChangerPodConfig,
+  SonareCapabilities,
+  VoicePresetId,
+} from './public_types';
 import type {
   SonareModule,
   WasmDecomposeResult,
@@ -32,9 +37,11 @@ export { Audio } from './audio';
 export type {
   ClipPageStreamerEngine,
   ClipPageStreamerOptions,
+  ClipPageStreamerRequest,
   ClipPageStreamSource,
   OpfsClipStream,
   OpfsClipStreamOptions,
+  WorkletOpfsClipStreamHost,
 } from './clip_page_streamer';
 export { attachOpfsClipStream, ClipPageStreamer } from './clip_page_streamer';
 export type {
@@ -61,6 +68,7 @@ export type {
   MasteringProcessorCatalogEntry,
   MasteringProcessRequest,
   MasteringProcessStereoRequest,
+  MasteringRealtimeCost,
   MasteringRepairDeclickRequest,
   MasteringRepairDeclipRequest,
   MasteringRepairDecrackleRequest,
@@ -151,18 +159,22 @@ export type {
 } from './effects_transform';
 export { ErrorCode, isSonareError, SonareError } from './errors';
 export type {
+  ChirpRequest,
+  ClicksRequest,
   CyclicTempogramRequest,
   DbConversionRequest,
   EmphasisRequest,
   FixFramesRequest,
   FixLengthRequest,
   FrameSignalRequest,
+  OnsetBacktrackRequest,
   PadCenterRequest,
   PcenRequest,
   PeakPickRequest,
   PlpRequest,
   SilenceRequest,
   TempogramRequest,
+  ToneRequest,
   TonnetzRequest,
   VectorNormalizeRequest,
 } from './feature_core';
@@ -181,7 +193,12 @@ export type {
   VqtRequest,
   VqtToAudioRequest,
 } from './feature_music';
-export type { PitchPyinRequest, PitchYinRequest } from './feature_pitch';
+export type {
+  NoteSegmentsRequest,
+  PiptrackRequest,
+  PitchPyinRequest,
+  PitchYinRequest,
+} from './feature_pitch';
 export type { ResampleRequest } from './feature_resample';
 export type {
   DecomposeRequest,
@@ -195,6 +212,13 @@ export type {
   PitchTuningRequest,
   PolyFeaturesRequest,
   RemixRequest,
+  SegmentAgglomerativeRequest,
+  SegmentCrossSimilarityRequest,
+  SegmentLagToRecurrenceRequest,
+  SegmentPathEnhanceRequest,
+  SegmentRecurrenceMatrixRequest,
+  SegmentRecurrenceToLagRequest,
+  SegmentSubsegmentRequest,
   SpectralContrastRequest,
   SpectralFrameRequest,
   SpectralRolloffRequest,
@@ -203,12 +227,15 @@ export type {
 } from './feature_spectral';
 export type {
   ChromaSpectrogramRequest,
+  GriffinLimRequest,
+  MelDeltaRequest,
   MelSpectrogramRequest,
   MelToAudioRequest,
   MelToStftRequest,
   MfccRequest,
   MfccToAudioRequest,
   MfccToMelRequest,
+  ReassignedSpectrogramRequest,
   SpectrogramRequest,
   TrimRequest,
 } from './feature_spectrogram';
@@ -217,9 +244,11 @@ export {
   analyzeMelody,
   analyzeSections,
   bassChroma,
+  chirp,
   chroma,
   chromaCens,
   chromaCqt,
+  clicks,
   cqt,
   cqtToAudio,
   cyclicTempogram,
@@ -236,6 +265,7 @@ export {
   frameSignal,
   framesToSamples,
   framesToTime,
+  griffinLim,
   hpssWithResidual,
   hybridCqt,
   hzToMel,
@@ -243,6 +273,7 @@ export {
   hzToNote,
   lufs,
   lufsInterleaved,
+  melDelta,
   melSpectrogram,
   melToAudio,
   melToHz,
@@ -254,13 +285,16 @@ export {
   momentaryLufs,
   nnFilter,
   nnlsChroma,
+  noteSegments,
   noteToHz,
+  onsetBacktrack,
   onsetEnvelope,
   onsetStrengthMulti,
   padCenter,
   pcen,
   peakPick,
   phaseVocoder,
+  piptrack,
   pitchPyin,
   pitchTuning,
   pitchYin,
@@ -269,15 +303,24 @@ export {
   powerToDb,
   preemphasis,
   pseudoCqt,
+  reassignedSpectrogram,
   remix,
   resample,
   rmsEnergy,
   samplesToFrames,
+  segmentAgglomerative,
+  segmentCrossSimilarity,
+  segmentLagToRecurrence,
+  segmentPathEnhance,
+  segmentRecurrenceMatrix,
+  segmentRecurrenceToLag,
+  segmentSubsegment,
   shortTermLufs,
   spectralBandwidth,
   spectralCentroid,
   spectralContrast,
   spectralFlatness,
+  spectralFlux,
   spectralRolloff,
   splitSilence,
   stft,
@@ -285,6 +328,7 @@ export {
   tempogram,
   tempogramRatio,
   timeToFrames,
+  tone,
   tonnetz,
   trim,
   trimSilence,
@@ -361,6 +405,9 @@ export type {
   BuiltinSynthBinding,
   BuiltinSynthConfig,
   BuiltinSynthWaveform,
+  ExternalSeparatedStem,
+  ExternalSeparatedStemImportRequest,
+  ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
   ProjectAutomationCurve,
@@ -368,6 +415,7 @@ export type {
   ProjectAutomationPoint,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -382,6 +430,8 @@ export type {
   ProjectMidiClipResult,
   ProjectMidiEvent,
   ProjectNotePairValidation,
+  ProjectSource,
+  ProjectTrack,
   ProjectTrackDesc,
   ProjectTrackKind,
   ProjectWarpAnchor,
@@ -401,6 +451,7 @@ export type {
   SynthPatch,
 } from './project';
 export {
+  BUILTIN_SYNTH_WAVEFORMS,
   EXPECTED_PROJECT_ABI_VERSION,
   MarkerKind,
   Project,
@@ -427,6 +478,7 @@ export type {
   AnalyzeTimbreOptions,
   AutomationCurve,
   Beat,
+  BpmHypothesis,
   Chord,
   ChordAnalysisResult,
   ChordDetectionOptions,
@@ -450,9 +502,11 @@ export type {
   MasteringChainConfig,
   MasteringChainResult,
   MasteringChainStereoResult,
+  MasteringLoudnessSummary,
   MasteringOptions,
   MasteringPreset,
   MasteringProcessorParams,
+  MasteringReport,
   MasteringResult,
   MasteringStereoChainResult,
   MasteringStereoResult,
@@ -466,6 +520,7 @@ export type {
   MixMeterSnapshot,
   MixOptions,
   MixResult,
+  NoteSegment,
   NoteStretchOptions,
   PairAnalysis,
   PairProcessor,
@@ -483,8 +538,10 @@ export type {
   RoomGeometryOptions,
   RoomMorphOptions,
   Section,
+  SegmentMatrix,
   SendTiming,
   SoloProcessor,
+  SonareCapabilities,
   SpectralEditMode,
   SpectralEditOptions,
   SpectralEditWindow,
@@ -522,6 +579,7 @@ export type {
   DetectAcousticRequest,
   DetectChordsRequest,
   DetectKeyRequest,
+  DetectOnsetsRequest,
   DynamicsAnalysisResult,
   EstimateRoomRequest,
   MusicAnalyzeRequest,
@@ -560,6 +618,7 @@ export type {
   EngineBounceResult,
   EngineBus,
   EngineCapabilities,
+  EngineCaptureSource,
   EngineCaptureStatus,
   EngineClip,
   EngineFreezeOptions,
@@ -582,7 +641,12 @@ export type {
   ExternalMidiEvent,
   MidiCcBindOptions,
 } from './realtime_engine';
-export { EXPECTED_ENGINE_ABI_VERSION, engineCapabilities, RealtimeEngine } from './realtime_engine';
+export {
+  ClipPageProvider,
+  EXPECTED_ENGINE_ABI_VERSION,
+  engineCapabilities,
+  RealtimeEngine,
+} from './realtime_engine';
 export { scaleCorrectionSemitones, scalePitchClassEnabled, scaleQuantizeMidi } from './scale';
 export type { ProgressCallback } from './sonare.js';
 export { StreamAnalyzer, streamAnalyzerConfigDefaults } from './stream_analyzer';
@@ -623,6 +687,13 @@ export type {
   WebMidiInputInfo,
 } from './web_midi';
 export { bindWebMidi, isWebMidiAvailable } from './web_midi';
+export type {
+  OfflineWorker,
+  OfflineWorkerCallOptions,
+  OfflineWorkerClientOptions,
+  OfflineWorkerProgress,
+} from './worker_client';
+export { OfflineWorkerClient, OfflineWorkerTask } from './worker_client';
 
 /** Row-major 2-D matrix as a flat buffer plus its dimensions. */
 export type Matrix2dResult = WasmMatrix2dResult;
@@ -696,6 +767,26 @@ export function version(): string {
   return module.version();
 }
 
+/**
+ * Return the capabilities of the loaded WASM build.
+ *
+ * This is synchronous and only describes the already-initialized module.
+ */
+export function capabilities(): SonareCapabilities {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return module.capabilities();
+}
+
+/** Return the initialized module's processors, parameters, and presets. */
+export function capabilityCatalog(): CapabilityCatalog {
+  if (!module) {
+    throw new Error('Module not initialized. Call init() first.');
+  }
+  return JSON.parse(module.capabilityCatalog()) as CapabilityCatalog;
+}
+
 /**
  * Aggregate native ABI version: the per-subsystem ABI macros folded into one
  * 32-bit value. It bumps whenever any flat C POD layout changes, so callers can
@@ -735,6 +826,9 @@ const VOICE_PRESET_ORDINALS: readonly VoicePresetId[] = [
 
 function resolveVoicePresetOrdinal(preset: VoicePresetId | number): number {
   if (typeof preset === 'number') {
+    if (!Number.isSafeInteger(preset) || preset < 0 || preset >= VOICE_PRESET_ORDINALS.length) {
+      throw new RangeError(`Unknown voice-character preset ordinal: ${String(preset)}`);
+    }
     return preset;
   }
   const ordinal = VOICE_PRESET_ORDINALS.indexOf(preset);
@@ -746,9 +840,9 @@ function resolveVoicePresetOrdinal(preset: VoicePresetId | number): number {
 
 /**
  * Map a voice-character preset ordinal (or canonical id) to its canonical id
- * string (e.g. `'bright-idol'`). Returns `null` for an out-of-range ordinal.
+ * string (e.g. `'bright-idol'`). Invalid ordinals throw.
  */
-export function voiceCharacterPresetId(preset: VoicePresetId | number): string | null {
+export function voiceCharacterPresetId(preset: VoicePresetId | number): string {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }
@@ -758,11 +852,11 @@ export function voiceCharacterPresetId(preset: VoicePresetId | number): string |
 /**
  * Return the canonical (normalized) flat POD config for a built-in voice
  * preset, skipping the JSON round-trip. Accepts a canonical preset id or its
- * integer ordinal. Returns `null` for an out-of-range ordinal.
+ * integer ordinal. Invalid ordinals throw.
  */
 export function realtimeVoiceChangerPresetConfig(
   preset: VoicePresetId | number,
-): RealtimeVoiceChangerPodConfig | null {
+): RealtimeVoiceChangerPodConfig {
   if (!module) {
     throw new Error('Module not initialized. Call init() first.');
   }