@libraz/libsonare 1.3.0 → 1.3.2

package/README.md

@@ -21,6 +21,11 @@ no model weights.
 > If you need to read WAV/MP3/M4A files directly in Node, use the native
 > N-API package [`@libraz/libsonare-native`](https://github.com/libraz/libsonare/tree/main/bindings/node) instead.
 
+> **Platform constraints:** the WebAssembly build is single-threaded (analysis
+> runs to completion on the calling thread — there is no non-blocking variant),
+> has no host filesystem access, and expects pre-decoded `Float32Array` sample
+> buffers. Drive long-running calls from a Web Worker to keep the UI responsive.
+
 ## Installation
 
 ```bash
@@ -124,6 +129,54 @@ const room = analyzeImpulseResponse(irSamples, sampleRate);
 console.log(blind.rt60, room.c50);
 ```
 
+Acoustic simulation adds `synthesizeRir` (synthesize a shoebox-room impulse
+response from geometry), `estimateRoom` (recover an equivalent room from a
+recording or IR), and `roomMorph` (creatively re-reverberate audio toward a
+target room — not dereverberation).
+
+```typescript
+import { init, synthesizeRir, estimateRoom, roomMorph } from '@libraz/libsonare';
+
+await init();
+
+const { rir, hasError } = synthesizeRir({
+  lengthM: 6,
+  widthM: 4,
+  heightM: 3,
+  absorption: 0.2,
+  sampleRate: 48000,
+});
+
+const room = estimateRoom(samples, 48000); // { volume, length, width, height, ... }
+const morphed = roomMorph(samples, sampleRate, { lengthM: 12, widthM: 9, wet: 0.5 });
+```
+
+### Error handling
+
+Native (C++) failures are thrown as a `SonareError` carrying a numeric `code`
+(an `ErrorCode` value) and its canonical `codeName`, so you can branch on the
+cause instead of matching message text. Use the `isSonareError` type guard in a
+`catch`:
+
+```typescript
+import { init, analyze, ErrorCode, isSonareError } from '@libraz/libsonare';
+
+await init();
+
+try {
+  const result = analyze(samples, sampleRate);
+} catch (error) {
+  if (isSonareError(error)) {
+    console.error(`${error.codeName} (${error.code}): ${error.message}`);
+    if (error.code === ErrorCode.InvalidParameter) {
+      // recover...
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
 ### Decoding files in the browser
 
 ```typescript
@@ -331,6 +384,149 @@ try {
 }
 ```
 
+#### Clip warp
+
+A clip can be time-warped during an offline `bounce`. `setClipWarpMode` selects
+the playback mode (`ProjectWarpMode`: `'off'` | `'repitch'` | `'tempo-sync'`),
+`setClipWarpRef` binds it to a warp map, and `setWarpMap` registers a first-class
+warp map (anchors mapping warp-timeline samples to source samples).
+
+```typescript
+project.setWarpMap({
+  id: 1,
+  name: 'main',
+  anchors: [
+    { warpSample: 0, sourceSample: 0 },
+    { warpSample: 48000, sourceSample: 24000 },
+  ],
+});
+project.setClipWarpRef(clipId, 1);
+project.setClipWarpMode(clipId, 'tempo-sync');
+```
+
+> Warp is an offline `Project.bounce` feature only. Realtime warp playback is
+> **not** available in `RealtimeEngine`.
+
+### Instruments and synthesis
+
+MIDI tracks bounce silently unless an instrument is bound. `Project` offers
+three instrument backends, each as a `bounceWith…` variant that takes a binding
+(or array of bindings) plus the usual `ProjectBounceOptions`:
+
+- `bounceWithBuiltinInstrument(binding?, options?)` — simple built-in oscillator
+  synth (`BuiltinSynthConfig` / `BuiltinSynthBinding`: waveform + ADSR + gain).
+- `bounceWithSynthInstrument(patchOrName?, options?)` — patch-driven NativeSynth
+  (`SynthPatch`, or a preset-name string like `'saw-lead'`).
+- `bounceWithSf2Instrument(config?, options?)` — GS-compatible SoundFont player
+  (`Sf2InstrumentConfig`), fed by `loadSoundFont()`.
+
+Discover NativeSynth presets with `synthPresetNames()` and fetch one as an
+editable patch with `synthPresetPatch(name)`.
+
+```typescript
+import { init, Project, synthPresetNames, synthPresetPatch } from '@libraz/libsonare';
+
+await init();
+
+const project = new Project();
+try {
+  const { clipId } = project.addMidiClip(0, 4);
+  project.setMidiEvents(clipId, [
+    Project.midiNoteOn(0, 0, 0, 60, 100),
+    Project.midiNoteOff(1, 0, 0, 60),
+  ]);
+
+  // Built-in oscillator synth.
+  const a = project.bounceWithBuiltinInstrument({ waveform: 'saw' }, { numChannels: 2 });
+
+  // NativeSynth from a named preset, tweaked.
+  const patch = synthPresetPatch(synthPresetNames()[0]);
+  patch.cutoffHz = 4000;
+  const b = project.bounceWithSynthInstrument(patch, { numChannels: 2 });
+
+  // SoundFont player (requires loadSoundFont first).
+  project.loadSoundFont(sf2Bytes);
+  const c = project.bounceWithSf2Instrument({ gain: 0.6 }, { numChannels: 2 });
+} finally {
+  project.delete();
+}
+```
+
+### Real-time engine
+
+`RealtimeEngine` is a control-thread-driven transport + render engine: it plays
+a clip/automation timeline, hosts MIDI instruments, accepts live MIDI, and
+renders blocks (or bounces offline). Bind it to an AudioWorklet for browser
+playback — see the [AudioWorklet bridge](#audioworklet-bridge) below; the engine
+is the offline/headless half, the worklet is the audio-thread half.
+
+```typescript
+import { init, RealtimeEngine } from '@libraz/libsonare';
+
+await init();
+
+const engine = new RealtimeEngine(48000, 128); // sampleRate, maxBlockSize
+try {
+  engine.setSynthInstrument('saw-lead', 0);     // patch (or name), destinationId
+  engine.play();
+  engine.pushMidiNoteOn(0, 0, 0, 60, 100);      // destination, group, channel, note, velocity
+  engine.pushMidiNoteOff(0, 0, 0, 60);
+
+  const blockL = new Float32Array(128);
+  const blockR = new Float32Array(128);
+  const out = engine.process([blockL, blockR]); // Float32Array[] per channel
+  const telemetry = engine.drainTelemetry();
+} finally {
+  engine.destroy();
+}
+```
+
+Capabilities:
+
+- **Transport**: `play` / `stop` / `seekSample` / `seekPpq` / `setTempo` /
+  `setTimeSignature` / `setLoop`, plus `getTransportState`.
+- **Instruments**: `setBuiltinInstrument` / `setSynthInstrument` /
+  `setSf2Instrument` (+ `loadSoundFont`) per MIDI destination id.
+- **Live MIDI**: `pushMidiNoteOn` / `pushMidiNoteOff` / `pushMidiCc` /
+  `pushMidiPanic`, and `bindMidiCc(channel, controller, paramId, options?)` to
+  map a CC to an automation parameter.
+- **Process / bounce**: `process` (real-time blocks), the allocation-free
+  `prepareChannels` + `getChannelBuffer` + `processPrepared` worklet path,
+  `renderOffline`, `bounceOffline`, `freezeOffline`.
+- **Clip page providers**: `createClipPageProvider` + `supplyClipPage` for
+  streaming large clip audio in pages; pair with the OPFS helpers
+  (`createOpfsClipPageProvider`).
+- **Telemetry**: `drainTelemetry` / `drainMeterTelemetry`. Inspect runtime
+  capabilities (ABI compatibility, SharedArrayBuffer/Atomics) via
+  `engineCapabilities()`.
+
+### Real-time voice changer
+
+`RealtimeVoiceChanger` runs a block-by-block voice transformation chain (retune,
+formant shaping, EQ, gate, compressor). Construct it from a preset id (see
+`realtimeVoiceChangerPresetNames()`) or a full config object, then process blocks.
+
+```typescript
+import { init, RealtimeVoiceChanger, voiceChangeRealtime } from '@libraz/libsonare';
+
+await init();
+
+const changer = new RealtimeVoiceChanger('bright-idol');
+try {
+  changer.prepare(48000, 128, 1); // sampleRate, maxBlockSize, channels
+  const out = changer.processMono(block);
+} finally {
+  changer.delete();
+}
+
+// Whole-buffer convenience wrapper (constructs/prepares/disposes internally).
+const processed = voiceChangeRealtime(samples, { preset: 'deep-narrator', sampleRate: 48000 });
+```
+
+For a simple offline pitch + formant shift without the full chain, use
+`voiceChange(samples, sampleRate, { pitchSemitones: -2, formantFactor: 1.1 })`.
+Inspect a preset with `realtimeVoiceChangerPresetJson(name)`.
+
 ### AudioWorklet bridge
 
 The package exposes an optional worklet entry that uses the same `sonare.wasm`
@@ -476,17 +672,50 @@ chain.reset();
 chain.delete(); // release WASM memory
 ```
 
+### Streaming equalizer and retune
+
+`StreamingEqualizer` wraps the unified `EqualizerProcessor` (up to 24 bands,
+RBJ/Vicanek biquads, dynamic EQ, linear-phase FIR, mid/side, auto-gain) with
+state maintained across calls. `StreamingRetune` is a block-by-block mono voice
+retune / pitch shifter.
+
+```typescript
+import { init, StreamingEqualizer, StreamingRetune } from '@libraz/libsonare';
+
+await init();
+
+const eq = new StreamingEqualizer({ sampleRate: 48000, maxBlockSize: 512 });
+try {
+  eq.setBand(0, { type: 'HighShelf', frequencyHz: 8000, gainDb: 6, enabled: true });
+  const { left: eqL, right: eqR } = eq.processStereo(left, right);
+} finally {
+  eq.delete();
+}
+
+const retune = new StreamingRetune({ semitones: 2, mix: 1.0 });
+try {
+  retune.prepare(48000, 512); // sampleRate, maxBlockSize
+  const shifted = retune.processMono(monoBlock);
+} finally {
+  retune.delete();
+}
+```
+
 ## Features
 
-- **Detection**: BPM, key, beats, onsets, chords, sections
+- **Detection**: `detectBeats`, `detectOnsets`, `detectDownbeats`, `detectChords`, `detectKey`, `detectKeyCandidates`, `chordFunctionalAnalysis`, sections
+- **Analysis**: `analyze`, `analyzeWithProgress`, `analyzeBpm`, `analyzeRhythm`, `analyzeDynamics`, `analyzeTimbre`; `hasFfmpegSupport` capability check
 - **Effects**: HPSS, HPSS with residual, time stretch, phase vocoder, pitch shift, normalize, trim, remix
 - **Mastering**: EQ, compressor, tape/exciter, air band, stereo imaging,
   true-peak limiting, loudness optimization
 - **Features**: STFT, mel spectrogram, MFCC, chroma, CQT/VQT, spectral contrast, poly features, zero crossings
 - **Pitch**: YIN, pYIN algorithms with optional `fillNa`
 - **Decomposition & loudness**: NMF decomposition, nearest-neighbour filtering, multichannel LUFS, EBU R128 LRA
-- **Streaming**: Real-time analysis with progressive estimates
-- **Headless DAW**: `Project` arrangement model — audio/MIDI tracks & clips, undo/redo, MIDI sequencing, SMF / MIDI 2.0 Clip File I/O, deterministic JSON, offline `bounce`
+- **Streaming**: Real-time analysis with progressive estimates; streaming mastering chain, equalizer, and retune
+- **Instruments**: built-in synth, patch-driven NativeSynth, SoundFont (SF2) player — bound to `Project` bounces or the `RealtimeEngine`
+- **Real-time**: `RealtimeEngine` transport/MIDI/render, `RealtimeVoiceChanger`, AudioWorklet bridge
+- **Room acoustics**: blind RT60/EDT, impulse-response clarity metrics, RIR synthesis, room estimation, room morphing
+- **Headless DAW**: `Project` arrangement model — audio/MIDI tracks & clips, undo/redo, MIDI sequencing, clip warp, SMF / MIDI 2.0 Clip File I/O, deterministic JSON, offline `bounce`
 - **Conversions**: Hz/mel/MIDI/note, frames/time, resample
 
 ## Also available

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { A as AcousticOptions, a as AcousticResult, b as AnalysisResult, c as AnalyzeBpmOptions, d as AnalyzeDynamicsOptions, e as AnalyzeRhythmOptions, f as AnalyzeSectionsOptions, g as AnalyzeTimbreOptions, h as AnalyzerStats, i as Audio, j as AutomationCurve, B as BarChord, k as Beat, l as BindMicrophoneInputOptions, m as BindWebMidiOptions, n as BpmAnalysisResult, o as BpmCandidate, p as BrowserAudioDecodeOptions, q as BuiltinSynthBinding, r as BuiltinSynthConfig, s as BuiltinSynthWaveform, C as Chord, t as ChordAnalysisResult, u as ChordChange, v as ChordDetectionOptions, w as ChordQuality, x as ChromaResult, y as ClippingRegion, z as ClippingReport, D as CompressorDetector, E as CompressorOptions, F as CqtResult, G as DeclickOptions, H as DeclipOptions, I as DecomposeResult, J as DecrackleMode, K as DecrackleOptions, L as DehumOptions, M as DenoiseClassicalMode, N as DenoiseClassicalNoiseEstimator, O as DenoiseClassicalOptions, P as DereverbClassicalOptions, Q as DynamicRangeReport, R as Dynamics, S as DynamicsAnalysisResult, T as DynamicsResult, U as EXPECTED_ENGINE_ABI_VERSION, V as EXPECTED_PROJECT_ABI_VERSION, W as EngineAutomationPoint, X as EngineBounceOptions, Y as EngineBounceResult, Z as EngineCapabilities, _ as EngineCaptureStatus, $ as EngineClip, a0 as EngineFreezeOptions, a1 as EngineFreezeResult, a2 as EngineGraphSpec, a3 as EngineMarker, a4 as EngineMeterTelemetry, a5 as EngineMetronomeConfig, a6 as EngineParameterInfo, a7 as EngineTelemetry, a8 as EngineTransportState, a9 as EqBand, aa as EqBandPhase, ab as EqBandType, ac as EqCoeffMode, ad as EqMatchOptions, ae as EqSpectrumSnapshot, af as EqStereoPlacement, ag as FrameBuffer, ah as GateOptions, ai as GoniometerPoint, aj as HpssResult, ak as HpssWithResidualResult, al as Key, am as KeyCandidate, an as KeyDetectionOptions, ao as KeyProfile, ap as KeyProfileName, aq as LufsResult, ar as MasteringChainConfig, as as MasteringChainResult, at as MasteringOptions, au as MasteringPreset, av as MasteringProcessorParams, aw as MasteringResult, ax as MasteringStereoChainResult, ay as MasteringStereoResult, az as Matrix2dResult, aA as MelPowerResult, aB as MelSpectrogramResult, aC as MelodyOptions, aD as MelodyPoint, aE as MelodyResult, aF as MeterTap, aG as MeteringDetectClippingOptions, aH as MeteringDynamicRangeOptions, aI as MfccResult, aJ as MicrophoneInputBinding, aK as MidiCcBindOptions, aL as MidiCcLearnOptions, aM as MixMeterSnapshot, aN as MixOptions, aO as MixResult, aP as Mixer, aQ as MixerProcessResult, aR as MixerRealtimeBuffer, aS as Mode, aT as NoteStretchOptions, aU as OpfsClipPageProviderBinding, aV as OpfsClipPageProviderOptions, aW as PairAnalysis, aX as PairProcessor, aY as PanLaw, aZ as PanMode, a_ as PatternScore, a$ as PhaseScopeReport, b0 as Pitch, b0 as PitchClass, b1 as PitchResult, b2 as ProgressiveEstimate, b3 as Project, b4 as ProjectAssistSidecar, b5 as ProjectAutomationCurve, b6 as ProjectAutomationLaneDesc, b7 as ProjectAutomationPoint, b8 as ProjectBounceOptions, b9 as ProjectChordSymbol, ba as ProjectClipCompSegment, bb as ProjectClipDesc, bc as ProjectClipFade, bd as ProjectClipTake, be as ProjectCompileResult, bf as ProjectFadeCurve, bg as ProjectKeySegment, bh as ProjectLoopMode, bi as ProjectLoopRecordingDesc, bj as ProjectLoopRecordingResult, bk as ProjectMidiClipResult, bl as ProjectMidiEvent, bm as ProjectNotePairValidation, bn as ProjectTrackDesc, bo as ProjectTrackKind, bp as ProjectWarpAnchor, bq as ProjectWarpMapDesc, br as RealtimeEngine, bs as RealtimeVoiceChanger, bt as RealtimeVoiceChangerConfigInput, bu as RealtimeVoiceChangerInterleavedBuffer, bv as RealtimeVoiceChangerMonoBuffer, bw as RealtimeVoiceChangerPlanarBuffer, bx as RealtimeVoiceChangerPodConfig, by as RhythmAnalysisResult, bz as RhythmFeatures, bA as RirResult, bB as RirSynthOptions, bC as RoomEstimateOptions, bD as RoomEstimateResult, bE as RoomGeometryOptions, bF as RoomMorphOptions, bG as SYNTH_BODY_TYPES, bH as SYNTH_ENGINE_MODES, bI as SYNTH_FILTER_MODELS, bJ as SYNTH_FILTER_OUTPUTS, bK as SYNTH_MOD_DESTINATIONS, bL as SYNTH_MOD_SOURCES, bM as SYNTH_OSC_WAVEFORMS, bN as Section, bO as SectionType, bP as SendTiming, bQ as Sf2InstrumentConfig, bR as Sf2ProgramStatus, bS as SoloProcessor, bT as SourceBackend, bU as SpectrumOptions, bV as SpectrumReport, bW as StereoAnalysis, bX as StftPowerResult, bY as StftResult, bZ as StreamAnalyzer, b_ as StreamConfig, b$ as StreamConfigDefaults, c0 as StreamFramesI16, c1 as StreamFramesU8, c2 as StreamQuantizeConfig, c3 as StreamingEqualizer, c4 as StreamingEqualizerConfig, c5 as StreamingMasteringChain, c6 as StreamingMasteringChainConfig, c7 as StreamingPlatform, c8 as StreamingRetune, c9 as StreamingRetuneConfig, ca as SynthBodyType, cb as SynthEngineMode, cc as SynthEnumTables, cd as SynthFilterModel, ce as SynthFilterOutput, cf as SynthModDestination, cg as SynthModRouting, ch as SynthModSource, ci as SynthOscWaveform, cj as SynthPatch, ck as TempogramMode, cl as Timbre, cm as TimbreAnalysisResult, cn as TimbreFrame, co as TimeSignature, cp as TransientShaperOptions, cq as TrimSilenceMode, cr as TrimSilenceOptions, cs as ValidateOptions, ct as VectorscopeReport, cu as VoiceChangeOptions, cv as VoiceChangeRealtimeOptions, cw as VoicePresetId, cx as WaveformPeakPyramidOptions, cy as WaveformPeaksOptions, cz as WaveformPeaksReport, cA as WebMidiBinding, cB as WebMidiCcBinding, cC as WebMidiInputInfo, cD as amplitudeToDb, cE as analyze, cF as analyzeBpm, cG as analyzeDynamics, cH as analyzeImpulseResponse, cI as analyzeMelody, cJ as analyzeRhythm, cK as analyzeSections, cL as analyzeTimbre, cM as analyzeWithProgress, cN as bassChroma, cO as bindMicrophoneInput, cP as bindWebMidi, cQ as chordFunctionalAnalysis, cR as chroma, cS as chromaCens, cT as cqt, cU as createOpfsClipPageProvider, cV as createOpfsClipPageWorker, cW as cyclicTempogram, cX as dbToAmplitude, cY as dbToPower, cZ as decompose, c_ as decomposeWithInit, c$ as deemphasis, d0 as detectAcoustic, d1 as detectBeats, d2 as detectBpm, d3 as detectChords, d4 as detectDownbeats, d5 as detectKey, d6 as detectKeyCandidates, d7 as detectOnsets, d8 as ebur128LoudnessRange, d9 as engineAbiVersion, da as engineCapabilities, db as estimateRoom, dc as estimateTuning, dd as fixFrames, de as fixLength, df as fourierTempogram, dg as frameSignal, dh as framesToSamples, di as framesToTime, dj as harmonic, dk as hasFfmpegSupport, dl as hpss, dm as hpssWithResidual, dn as hybridCqt, dp as hzToMel, dq as hzToMidi, dr as hzToNote, init, isInitialized, ds as isWebMidiAvailable, dt as lufs, du as lufsInterleaved, dv as masterAudio, dw as masterAudioStereo, dx as masterAudioStereoWithProgress, dy as masterAudioWithProgress, dz as mastering, dA as masteringAssistantSuggest, dB as masteringAudioProfile, dC as masteringChain, dD as masteringChainStereo, dE as masteringChainStereoWithProgress, dF as masteringChainWithProgress, dG as masteringDynamicsCompressor, dH as masteringDynamicsGate, dI as masteringDynamicsTransientShaper, dJ as masteringInsertNames, dK as masteringPairAnalysisNames, dL as masteringPairAnalyze, dM as masteringPairProcess, dN as masteringPairProcessorNames, dO as masteringPresetNames, dP as masteringProcess, dQ as masteringProcessStereo, dR as masteringProcessorNames, dS as masteringRepairDeclick, dT as masteringRepairDeclip, dU as masteringRepairDecrackle, dV as masteringRepairDehum, dW as masteringRepairDenoiseClassical, dX as masteringRepairDereverbClassical, dY as masteringRepairTrimSilence, dZ as masteringStereoAnalysisNames, d_ as masteringStereoAnalyze, d$ as masteringStreamingPreview, e0 as melSpectrogram, e1 as melToAudio, e2 as melToHz, e3 as melToStft, e4 as meteringCrestFactorDb, e5 as meteringDcOffset, e6 as meteringDetectClipping, e7 as meteringDynamicRange, e8 as meteringPeakDb, e9 as meteringPhaseScope, ea as meteringPhaseScopeDecimated, eb as meteringRmsDb, ec as meteringSpectrum, ed as meteringSpectrumFrame, ee as meteringStereoCorrelation, ef as meteringStereoWidth, eg as meteringTruePeakDb, eh as meteringVectorscope, ei as meteringVectorscopeDecimated, ej as mfcc, ek as mfccToAudio, el as mfccToMel, em as midiToHz, en as mixStereo, eo as mixingScenePresetJson, ep as mixingScenePresetNames, eq as momentaryLufs, er as nnFilter, es as nnlsChroma, et as normalize, eu as noteStretch, ev as noteToHz, ew as onsetEnvelope, ex as onsetStrengthMulti, ey as opfsClipPageWorkerSource, ez as padCenter, eA as pcen, eB as peakPick, eC as percussive, eD as phaseVocoder, eE as pitchCorrectToMidi, eF as pitchCorrectToMidiTimevarying, eG as pitchPyin, eH as pitchShift, eI as pitchTuning, eJ as pitchYin, eK as plp, eL as polyFeatures, eM as powerToDb, eN as preemphasis, eO as projectAbiVersion, eP as pseudoCqt, eQ as realtimeVoiceChangerPresetConfig, eR as realtimeVoiceChangerPresetJson, eS as realtimeVoiceChangerPresetNames, eT as remix, eU as resample, eV as rmsEnergy, eW as roomMorph, eX as samplesToFrames, eY as scaleCorrectionSemitones, eZ as scalePitchClassEnabled, e_ as scaleQuantizeMidi, e$ as shortTermLufs, f0 as spectralBandwidth, f1 as spectralCentroid, f2 as spectralContrast, f3 as spectralFlatness, f4 as spectralRolloff, f5 as splitSilence, f6 as stft, f7 as stftDb, f8 as streamAnalyzerConfigDefaults, f9 as synthEnumTables, fa as synthPresetNames, fb as synthPresetPatch, fc as synthesizeRir, fd as tempogram, fe as tempogramRatio, ff as timeStretch, fg as timeToFrames, fh as tonnetz, fi as trim, fj as trimSilence, fk as validateRealtimeVoiceChangerPresetJson, fl as vectorNormalize, fm as version, fn as voiceChange, fo as voiceChangeRealtime, fp as voiceChangerAbiVersion, fq as voiceCharacterPresetId, fr as vqt, fs as waveformPeakPyramid, ft as waveformPeaks, fu as zeroCrossingRate, fv as zeroCrossings } from './worklet.js';
+export { A as AcousticOptions, a as AcousticResult, b as AnalysisResult, c as AnalyzeBpmOptions, d as AnalyzeDynamicsOptions, e as AnalyzeRhythmOptions, f as AnalyzeSectionsOptions, g as AnalyzeTimbreOptions, h as AnalyzerStats, i as Audio, j as AutomationCurve, B as BarChord, k as Beat, l as BindMicrophoneInputOptions, m as BindWebMidiOptions, n as BpmAnalysisResult, o as BpmCandidate, p as BrowserAudioDecodeOptions, q as BuiltinSynthBinding, r as BuiltinSynthConfig, s as BuiltinSynthWaveform, C as Chord, t as ChordAnalysisResult, u as ChordChange, v as ChordDetectionOptions, w as ChordQuality, x as ChromaResult, y as ClippingRegion, z as ClippingReport, D as CompressorDetector, E as CompressorOptions, F as CqtResult, G as DeclickOptions, H as DeclipOptions, I as DecomposeResult, J as DecrackleMode, K as DecrackleOptions, L as DehumOptions, M as DenoiseClassicalMode, N as DenoiseClassicalNoiseEstimator, O as DenoiseClassicalOptions, P as DereverbClassicalOptions, Q as DynamicRangeReport, R as Dynamics, S as DynamicsAnalysisResult, T as DynamicsResult, U as EXPECTED_ENGINE_ABI_VERSION, V as EXPECTED_PROJECT_ABI_VERSION, W as EngineAutomationPoint, X as EngineBounceOptions, Y as EngineBounceResult, Z as EngineCapabilities, _ as EngineCaptureStatus, $ as EngineClip, a0 as EngineFreezeOptions, a1 as EngineFreezeResult, a2 as EngineGraphSpec, a3 as EngineMarker, a4 as EngineMeterTelemetry, a5 as EngineMetronomeConfig, a6 as EngineParameterInfo, a7 as EngineTelemetry, a8 as EngineTransportState, a9 as EqBand, aa as EqBandPhase, ab as EqBandType, ac as EqCoeffMode, ad as EqMatchOptions, ae as EqSpectrumSnapshot, af as EqStereoPlacement, ag as ErrorCode, ah as FrameBuffer, ai as GateOptions, aj as GoniometerPoint, ak as HpssResult, al as HpssWithResidualResult, am as Key, an as KeyCandidate, ao as KeyDetectionOptions, ap as KeyProfile, aq as KeyProfileName, ar as LufsResult, as as MasteringChainConfig, at as MasteringChainResult, au as MasteringOptions, av as MasteringPreset, aw as MasteringProcessorParams, ax as MasteringResult, ay as MasteringStereoChainResult, az as MasteringStereoResult, aA as Matrix2dResult, aB as MelPowerResult, aC as MelSpectrogramResult, aD as MelodyOptions, aE as MelodyPoint, aF as MelodyResult, aG as MeterTap, aH as MeteringDetectClippingOptions, aI as MeteringDynamicRangeOptions, aJ as MfccResult, aK as MicrophoneInputBinding, aL as MidiCcBindOptions, aM as MidiCcLearnOptions, aN as MixMeterSnapshot, aO as MixOptions, aP as MixResult, aQ as Mixer, aR as MixerProcessResult, aS as MixerRealtimeBuffer, aT as Mode, aU as NoteStretchOptions, aV as OpfsClipPageProviderBinding, aW as OpfsClipPageProviderOptions, aX as PairAnalysis, aY as PairProcessor, aZ as PanLaw, a_ as PanMode, a$ as PatternScore, b0 as PhaseScopeReport, b1 as Pitch, b1 as PitchClass, b2 as PitchResult, b3 as ProgressiveEstimate, b4 as Project, b5 as ProjectAssistSidecar, b6 as ProjectAutomationCurve, b7 as ProjectAutomationLaneDesc, b8 as ProjectAutomationPoint, b9 as ProjectBounceOptions, ba as ProjectChordSymbol, bb as ProjectClipCompSegment, bc as ProjectClipDesc, bd as ProjectClipFade, be as ProjectClipTake, bf as ProjectCompileResult, bg as ProjectFadeCurve, bh as ProjectKeySegment, bi as ProjectLoopMode, bj as ProjectLoopRecordingDesc, bk as ProjectLoopRecordingResult, bl as ProjectMidiClipResult, bm as ProjectMidiEvent, bn as ProjectNotePairValidation, bo as ProjectTrackDesc, bp as ProjectTrackKind, bq as ProjectWarpAnchor, br as ProjectWarpMapDesc, bs as RealtimeEngine, bt as RealtimeVoiceChanger, bu as RealtimeVoiceChangerConfigInput, bv as RealtimeVoiceChangerInterleavedBuffer, bw as RealtimeVoiceChangerMonoBuffer, bx as RealtimeVoiceChangerPlanarBuffer, by as RealtimeVoiceChangerPodConfig, bz as RhythmAnalysisResult, bA as RhythmFeatures, bB as RirResult, bC as RirSynthOptions, bD as RoomEstimateOptions, bE as RoomEstimateResult, bF as RoomGeometryOptions, bG as RoomMorphOptions, bH as SYNTH_BODY_TYPES, bI as SYNTH_ENGINE_MODES, bJ as SYNTH_FILTER_MODELS, bK as SYNTH_FILTER_OUTPUTS, bL as SYNTH_MOD_DESTINATIONS, bM as SYNTH_MOD_SOURCES, bN as SYNTH_OSC_WAVEFORMS, bO as Section, bP as SectionType, bQ as SendTiming, bR as Sf2InstrumentConfig, bS as Sf2ProgramStatus, bT as SoloProcessor, bU as SonareError, bV as SourceBackend, bW as SpectrumOptions, bX as SpectrumReport, bY as StereoAnalysis, bZ as StftPowerResult, b_ as StftResult, b$ as StreamAnalyzer, c0 as StreamConfig, c1 as StreamConfigDefaults, c2 as StreamFramesI16, c3 as StreamFramesU8, c4 as StreamQuantizeConfig, c5 as StreamingEqualizer, c6 as StreamingEqualizerConfig, c7 as StreamingMasteringChain, c8 as StreamingMasteringChainConfig, c9 as StreamingPlatform, ca as StreamingRetune, cb as StreamingRetuneConfig, cc as SynthBodyType, cd as SynthEngineMode, ce as SynthEnumTables, cf as SynthFilterModel, cg as SynthFilterOutput, ch as SynthModDestination, ci as SynthModRouting, cj as SynthModSource, ck as SynthOscWaveform, cl as SynthPatch, cm as TempogramMode, cn as Timbre, co as TimbreAnalysisResult, cp as TimbreFrame, cq as TimeSignature, cr as TransientShaperOptions, cs as TrimSilenceMode, ct as TrimSilenceOptions, cu as ValidateOptions, cv as VectorscopeReport, cw as VoiceChangeOptions, cx as VoiceChangeRealtimeOptions, cy as VoicePresetId, cz as WaveformPeakPyramidOptions, cA as WaveformPeaksOptions, cB as WaveformPeaksReport, cC as WebMidiBinding, cD as WebMidiCcBinding, cE as WebMidiInputInfo, cF as amplitudeToDb, cG as analyze, cH as analyzeBpm, cI as analyzeDynamics, cJ as analyzeImpulseResponse, cK as analyzeMelody, cL as analyzeRhythm, cM as analyzeSections, cN as analyzeTimbre, cO as analyzeWithProgress, cP as bassChroma, cQ as bindMicrophoneInput, cR as bindWebMidi, cS as chordFunctionalAnalysis, cT as chroma, cU as chromaCens, cV as cqt, cW as createOpfsClipPageProvider, cX as createOpfsClipPageWorker, cY as cyclicTempogram, cZ as dbToAmplitude, c_ as dbToPower, c$ as decompose, d0 as decomposeWithInit, d1 as deemphasis, d2 as detectAcoustic, d3 as detectBeats, d4 as detectBpm, d5 as detectChords, d6 as detectDownbeats, d7 as detectKey, d8 as detectKeyCandidates, d9 as detectOnsets, da as ebur128LoudnessRange, db as engineAbiVersion, dc as engineCapabilities, dd as estimateRoom, de as estimateTuning, df as fixFrames, dg as fixLength, dh as fourierTempogram, di as frameSignal, dj as framesToSamples, dk as framesToTime, dl as harmonic, dm as hasFfmpegSupport, dn as hpss, dp as hpssWithResidual, dq as hybridCqt, dr as hzToMel, ds as hzToMidi, dt as hzToNote, init, isInitialized, du as isSonareError, dv as isWebMidiAvailable, dw as lufs, dx as lufsInterleaved, dy as masterAudio, dz as masterAudioStereo, dA as masterAudioStereoWithProgress, dB as masterAudioWithProgress, dC as mastering, dD as masteringAssistantSuggest, dE as masteringAudioProfile, dF as masteringChain, dG as masteringChainStereo, dH as masteringChainStereoWithProgress, dI as masteringChainWithProgress, dJ as masteringDynamicsCompressor, dK as masteringDynamicsGate, dL as masteringDynamicsTransientShaper, dM as masteringInsertNames, dN as masteringInsertParamNames, dO as masteringPairAnalysisNames, dP as masteringPairAnalyze, dQ as masteringPairProcess, dR as masteringPairProcessorNames, dS as masteringPresetNames, dT as masteringProcess, dU as masteringProcessStereo, dV as masteringProcessorNames, dW as masteringRepairDeclick, dX as masteringRepairDeclip, dY as masteringRepairDecrackle, dZ as masteringRepairDehum, d_ as masteringRepairDenoiseClassical, d$ as masteringRepairDereverbClassical, e0 as masteringRepairTrimSilence, e1 as masteringStereoAnalysisNames, e2 as masteringStereoAnalyze, e3 as masteringStreamingPreview, e4 as melSpectrogram, e5 as melToAudio, e6 as melToHz, e7 as melToStft, e8 as meteringCrestFactorDb, e9 as meteringDcOffset, ea as meteringDetectClipping, eb as meteringDynamicRange, ec as meteringPeakDb, ed as meteringPhaseScope, ee as meteringPhaseScopeDecimated, ef as meteringRmsDb, eg as meteringSpectrum, eh as meteringSpectrumFrame, ei as meteringStereoCorrelation, ej as meteringStereoWidth, ek as meteringTruePeakDb, el as meteringVectorscope, em as meteringVectorscopeDecimated, en as mfcc, eo as mfccToAudio, ep as mfccToMel, eq as midiToHz, er as mixStereo, es as mixingScenePresetJson, et as mixingScenePresetNames, eu as momentaryLufs, ev as nnFilter, ew as nnlsChroma, ex as normalize, ey as noteStretch, ez as noteToHz, eA as onsetEnvelope, eB as onsetStrengthMulti, eC as opfsClipPageWorkerSource, eD as padCenter, eE as pcen, eF as peakPick, eG as percussive, eH as phaseVocoder, eI as pitchCorrectToMidi, eJ as pitchCorrectToMidiTimevarying, eK as pitchPyin, eL as pitchShift, eM as pitchTuning, eN as pitchYin, eO as plp, eP as polyFeatures, eQ as powerToDb, eR as preemphasis, eS as projectAbiVersion, eT as pseudoCqt, eU as realtimeVoiceChangerPresetConfig, eV as realtimeVoiceChangerPresetJson, eW as realtimeVoiceChangerPresetNames, eX as remix, eY as resample, eZ as rmsEnergy, e_ as roomMorph, e$ as samplesToFrames, f0 as scaleCorrectionSemitones, f1 as scalePitchClassEnabled, f2 as scaleQuantizeMidi, f3 as shortTermLufs, f4 as spectralBandwidth, f5 as spectralCentroid, f6 as spectralContrast, f7 as spectralFlatness, f8 as spectralRolloff, f9 as splitSilence, fa as stft, fb as stftDb, fc as streamAnalyzerConfigDefaults, fd as synthEnumTables, fe as synthPresetNames, ff as synthPresetPatch, fg as synthesizeRir, fh as tempogram, fi as tempogramRatio, fj as timeStretch, fk as timeToFrames, fl as tonnetz, fm as trim, fn as trimSilence, fo as validateRealtimeVoiceChangerPresetJson, fp as vectorNormalize, fq as version, fr as voiceChange, fs as voiceChangeRealtime, ft as voiceChangerAbiVersion, fu as voiceCharacterPresetId, fv as vqt, fw as waveformPeakPyramid, fx as waveformPeaks, fy as zeroCrossingRate, fz as zeroCrossings } from './worklet.js';
 export { ProgressCallback } from './sonare.js';

package/dist/index.js

@@ -1,13 +1,106 @@
+// src/errors.ts
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2[ErrorCode2["Ok"] = 0] = "Ok";
+  ErrorCode2[ErrorCode2["FileNotFound"] = 1] = "FileNotFound";
+  ErrorCode2[ErrorCode2["InvalidFormat"] = 2] = "InvalidFormat";
+  ErrorCode2[ErrorCode2["DecodeFailed"] = 3] = "DecodeFailed";
+  ErrorCode2[ErrorCode2["InvalidParameter"] = 4] = "InvalidParameter";
+  ErrorCode2[ErrorCode2["OutOfMemory"] = 5] = "OutOfMemory";
+  ErrorCode2[ErrorCode2["NotSupported"] = 6] = "NotSupported";
+  ErrorCode2[ErrorCode2["InvalidState"] = 7] = "InvalidState";
+  ErrorCode2[ErrorCode2["Unknown"] = 99] = "Unknown";
+  return ErrorCode2;
+})(ErrorCode || {});
+var SonareError = class extends Error {
+  constructor(code, codeName, message) {
+    super(message);
+    this.name = "SonareError";
+    this.code = code;
+    this.codeName = codeName;
+  }
+};
+function isSonareError(value) {
+  return value instanceof Error && value.name === "SonareError" && typeof value.code === "number";
+}
+
 // src/module_state.ts
-var wasmModule = null;
+var wrappedModule = null;
+function nativeExceptionPtr(error) {
+  if (typeof error === "number") {
+    return error;
+  }
+  if (error !== null && typeof error === "object") {
+    const ptr = error.excPtr;
+    if (typeof ptr === "number") {
+      return ptr;
+    }
+  }
+  return null;
+}
+function makeSonareError(raw, thrown) {
+  let code = 99 /* Unknown */;
+  let codeName = "Unknown";
+  let message = `libsonare native exception (${thrown})`;
+  try {
+    const info = raw.sonareExceptionInfo?.(thrown);
+    if (info) {
+      code = info.code ?? code;
+      codeName = info.codeName ?? codeName;
+      message = info.message || message;
+    }
+  } catch {
+  }
+  return new SonareError(code, codeName, message);
+}
+function wrapModuleErrors(raw) {
+  const cache = /* @__PURE__ */ new Map();
+  const convert = (error) => {
+    const ptr = nativeExceptionPtr(error);
+    if (ptr !== null) {
+      throw makeSonareError(raw, ptr);
+    }
+    throw error;
+  };
+  return new Proxy(raw, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") {
+        return value;
+      }
+      const cached = cache.get(prop);
+      if (cached) {
+        return cached;
+      }
+      const fn = value;
+      const wrapped = new Proxy(fn, {
+        apply(t, thisArg, args) {
+          try {
+            return Reflect.apply(t, thisArg, args);
+          } catch (error) {
+            return convert(error);
+          }
+        },
+        construct(t, args, newTarget) {
+          try {
+            return Reflect.construct(t, args, newTarget);
+          } catch (error) {
+            return convert(error);
+          }
+        }
+      });
+      cache.set(prop, wrapped);
+      return wrapped;
+    }
+  });
+}
 function setSonareModule(module2) {
-  wasmModule = module2;
+  wrappedModule = wrapModuleErrors(module2);
 }
 function getSonareModule() {
-  if (!wasmModule) {
+  if (!wrappedModule) {
     throw new Error("Module not initialized. Call init() first.");
   }
-  return wasmModule;
+  return wrappedModule;
 }
 
 // src/codes.ts
@@ -82,6 +175,16 @@ var Mixer = class _Mixer {
   compile() {
     this.mixer.compile();
   }
+  /**
+   * Non-fatal warnings captured when this mixer was built from scene JSON: one
+   * entry per channel-strip insert that was handed param keys it does not read
+   * (a likely typo, or a key meant for a different processor). The scene still
+   * loaded; these keys simply took no effect. Empty when every key was consumed.
+   * Use {@link masteringInsertParamNames} to discover the keys an insert accepts.
+   */
+  sceneWarnings() {
+    return this.mixer.sceneWarnings();
+  }
   /**
    * Mix one block of per-strip stereo audio into the stereo master.
    *
@@ -1019,6 +1122,9 @@ function masteringProcessorNames() {
 function masteringInsertNames() {
   return requireModule().masteringInsertNames();
 }
+function masteringInsertParamNames(name) {
+  return requireModule().masteringInsertParamNames(name);
+}
 function masteringPairProcessorNames() {
   return requireModule().masteringPairProcessorNames();
 }
@@ -2354,9 +2460,11 @@ var Audio = class _Audio {
 
 // src/live_audio.ts
 async function bindMicrophoneInput(context, engine, options = {}) {
-  const stream = options.stream ?? await navigator.mediaDevices.getUserMedia({
-    audio: options.audio ?? true,
-    video: false
+  const { stream: providedStream, stopTracksOnClose = true, ...constraints } = options;
+  const stream = providedStream ?? await navigator.mediaDevices.getUserMedia({
+    ...constraints,
+    audio: constraints.audio ?? true,
+    video: constraints.video ?? false
   });
   const source = context.createMediaStreamSource(stream);
   const node = "node" in engine ? engine.node : engine;
@@ -2371,7 +2479,7 @@ async function bindMicrophoneInput(context, engine, options = {}) {
       }
       closed = true;
       source.disconnect();
-      if (options.stopTracksOnClose !== false) {
+      if (stopTracksOnClose) {
         for (const track of stream.getAudioTracks()) {
           track.stop();
         }
@@ -2527,12 +2635,22 @@ self.onmessage = async (event) => {
       const frames = Math.min(pageFrames, numSamples - startFrame);
       const frameBytes = numChannels * 4;
       const bytes = new Uint8Array(frames * frameBytes);
-      const bytesRead = access.read(bytes, { at: dataOffsetBytes + startFrame * frameBytes });
-      const framesRead = Math.floor(bytesRead / frameBytes);
-      if (framesRead <= 0) {
+      let bytesReadTotal = 0;
+      const readOffset = dataOffsetBytes + startFrame * frameBytes;
+      while (bytesReadTotal < bytes.byteLength) {
+        const bytesRead = access.read(bytes.subarray(bytesReadTotal), {
+          at: readOffset + bytesReadTotal,
+        });
+        if (bytesRead <= 0) {
+          break;
+        }
+        bytesReadTotal += bytesRead;
+      }
+      if (bytesReadTotal !== bytes.byteLength || bytesReadTotal % frameBytes !== 0) {
         self.postMessage({ type: 'sonare:clip-page', requestId, pageIndex, ok: false });
         return;
       }
+      const framesRead = bytesReadTotal / frameBytes;
       const view = new DataView(bytes.buffer, 0, framesRead * frameBytes);
       const channelBuffers = Array.from({ length: numChannels }, () => new ArrayBuffer(framesRead * 4));
       for (let ch = 0; ch < numChannels; ++ch) {
@@ -2598,7 +2716,12 @@ function createOpfsClipPageProvider(engine, options) {
       entry.resolve(false);
       return;
     }
-    provider.supply(response.pageIndex, channels);
+    try {
+      provider.supply(response.pageIndex, channels);
+    } catch {
+      entry.resolve(false);
+      return;
+    }
     entry.resolve(true);
   };
   worker.addEventListener("message", onMessage);
@@ -3964,15 +4087,15 @@ function isWebMidiAvailable() {
   return typeof globalThis.navigator?.requestMIDIAccess === "function";
 }
 async function bindWebMidi(engine, options = {}) {
-  const requestMIDIAccess = globalThis.navigator?.requestMIDIAccess;
-  if (typeof requestMIDIAccess !== "function") {
+  const navigatorWithMidi = globalThis.navigator;
+  if (typeof navigatorWithMidi?.requestMIDIAccess !== "function") {
     throw new Error("Web MIDI is not available in this environment");
   }
   const group = options.group ?? 0;
   assertNibble("bindWebMidi", group, "group");
   const destinationId = options.destinationId ?? 0;
   const selectedIds = new Set(options.inputIds ?? []);
-  const access = await requestMIDIAccess({
+  const access = await navigatorWithMidi.requestMIDIAccess({
     sysex: options.sysex ?? false,
     software: options.software ?? true
   });
@@ -4003,9 +4126,7 @@ async function bindWebMidi(engine, options = {}) {
         runningStatus,
         options.timestampToSamples
       );
-      if (status !== 0) {
-        runningStatus = status;
-      }
+      runningStatus = status;
     };
     if (input.addEventListener) {
       input.addEventListener("midimessage", listener);
@@ -4103,18 +4224,18 @@ function dispatchMidiMessage(engine, event, group, runningStatus, timestampToSam
   const message = status & 240;
   const channel = status & 15;
   if (message < 128 || message > 224) {
-    return status;
+    return status >= 248 ? runningStatus : 0;
   }
   const a = readU7(data, offset);
   const b = readU7(data, offset + 1);
-  if (a < 0) {
+  if (a < 0 || b < 0) {
     return status;
   }
   const portTimeSamples = timestampToSamples ? timestampToSamples(event.receivedTime ?? event.timeStamp ?? 0) : 0;
   if (message === 128) {
-    engine.pushMidiInputNoteOff(group, channel, a, b < 0 ? 0 : b, portTimeSamples);
+    engine.pushMidiInputNoteOff(group, channel, a, b, portTimeSamples);
   } else if (message === 144) {
-    if ((b < 0 ? 0 : b) === 0) {
+    if (b === 0) {
       engine.pushMidiInputNoteOff(group, channel, a, 0, portTimeSamples);
     } else {
       engine.pushMidiInputNoteOn(group, channel, a, b, portTimeSamples);
@@ -4263,6 +4384,7 @@ export {
   ChordQuality,
   EXPECTED_ENGINE_ABI_VERSION,
   EXPECTED_PROJECT_ABI_VERSION,
+  ErrorCode,
   KeyProfile,
   Mixer,
   Mode,
@@ -4279,6 +4401,7 @@ export {
   SYNTH_MOD_SOURCES,
   SYNTH_OSC_WAVEFORMS,
   SectionType,
+  SonareError,
   StreamAnalyzer,
   StreamingEqualizer,
   StreamingMasteringChain,
@@ -4337,6 +4460,7 @@ export {
   hzToNote,
   init,
   isInitialized,
+  isSonareError,
   isWebMidiAvailable,
   lufs,
   lufsInterleaved,
@@ -4355,6 +4479,7 @@ export {
   masteringDynamicsGate,
   masteringDynamicsTransientShaper,
   masteringInsertNames,
+  masteringInsertParamNames,
   masteringPairAnalysisNames,
   masteringPairAnalyze,
   masteringPairProcess,