@libraz/libsonare 1.4.1 → 1.5.1

package/README.md

@@ -7,13 +7,14 @@
 [![License](https://img.shields.io/github/license/libraz/libsonare)](https://github.com/libraz/libsonare/blob/main/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/libsonare?label=PyPI)](https://pypi.org/project/libsonare/)
 
-A dependency-free audio DSP toolkit for browser and Node.js via WebAssembly —
-librosa-compatible analysis plus broadcast-grade mastering, mixing, and editing.
-The same C++ processors run client-side in the browser: 66 named mastering DSP
-processors implemented against published references (ITU-R BS.1770-4 true-peak
-limiting, Linkwitz-Riley crossovers, Vicanek matched-Z biquads, ADAA-antialiased
-saturation), with analysis defaults matching librosa — Apache-2.0, no Python,
-no model weights.
+**Turn audio into data and back — entirely in the browser.** Analyze songs
+(BPM, key, chords, loudness), master and mix to broadcast loudness, and render
+MIDI through built-in instruments, all client-side via WebAssembly — the same
+C++ engine that runs natively, with zero dependencies and no Python or model
+weights. 66 named mastering DSP processors implemented against published
+references (ITU-R BS.1770-4 true-peak limiting, Linkwitz-Riley crossovers,
+Vicanek matched-Z biquads, ADAA-antialiased saturation); analysis defaults match
+librosa where the two overlap.
 
 > **Audio input:** This package expects already-decoded `Float32Array` mono
 > samples (it does not bundle a file decoder). Use the Web Audio API in the
@@ -124,7 +125,8 @@ import { init, analyzeImpulseResponse, detectAcoustic } from '@libraz/libsonare'
 
 await init();
 
-const blind = detectAcoustic(samples, sampleRate, 6, 24, 30.0, 10.0);
+// Blind estimation from ordinary audio; tuning options (nOctaveBands, …) are optional.
+const blind = detectAcoustic(samples, sampleRate);
 const room = analyzeImpulseResponse(irSamples, sampleRate);
 console.log(blind.rt60, room.c50);
 ```
@@ -245,16 +247,15 @@ import { init, masteringChain, masteringChainStereo } from '@libraz/libsonare';
 
 await init();
 
+// Config is a tree of processor sections; set only what you want to change.
 const mastered = masteringChain(samples, sampleRate, {
-  eq: { tiltDb: 1.0 },
   dynamics: { compressor: { thresholdDb: -24, ratio: 1.5 } },
-  saturation: { tape: { driveDb: 1.0, saturation: 0.2 } },
-  loudness: { targetLufs: -14, ceilingDb: -1, truePeakOversample: 4 },
+  loudness: { targetLufs: -14, ceilingDb: -1 },
 });
 
 const stereo = masteringChainStereo(left, right, sampleRate, {
-  stereo: { imager: { width: 1.1 }, monoMaker: { amount: 0.2 } },
-  loudness: { targetLufs: -14, ceilingDb: -1, truePeakOversample: 4 },
+  stereo: { imager: { width: 1.1 } },
+  loudness: { targetLufs: -14, ceilingDb: -1 },
 });
 ```
 
@@ -495,11 +496,42 @@ Capabilities:
   `renderOffline`, `bounceOffline`, `freezeOffline`.
 - **Clip page providers**: `createClipPageProvider` + `supplyClipPage` for
   streaming large clip audio in pages; pair with the OPFS helpers
-  (`createOpfsClipPageProvider`).
+  (`createOpfsClipPageProvider`) and the bounded-memory `ClipPageStreamer`
+  (see below) so a long multitrack arrangement never holds its full PCM in
+  WASM memory.
 - **Telemetry**: `drainTelemetry` / `drainMeterTelemetry`. Inspect runtime
   capabilities (ABI compatibility, SharedArrayBuffer/Atomics) via
   `engineCapabilities()`.
 
+#### Bounded-memory clip streaming
+
+`ClipPageStreamer` keeps OPFS-paged clips fed within a sliding window around the
+playback position, evicting pages that fall outside it. Resident memory per clip
+is bounded to `retainBehindPages + readAheadPages + 1` pages regardless of clip
+length. `attachOpfsClipStream` wires the provider, primes the leading page, and
+registers it in one call; `setClips` schedules the returned `provider`, and
+`pump()` (called on your control-thread tick) services page misses.
+
+```typescript
+import { ClipPageStreamer, attachOpfsClipStream, RealtimeEngine } from '@libraz/libsonare';
+
+const engine = new RealtimeEngine(48000, 128);
+const streamer = new ClipPageStreamer(engine, { readAheadPages: 2, retainBehindPages: 1 });
+
+const { provider } = await attachOpfsClipStream(streamer, engine, {
+  path: 'clips/vocal.f32',
+  clipId: 1,
+  numChannels: 2,
+  numSamples: 26_460_000, // ~10 min at 44.1 kHz, never fully resident
+  pageFrames: 65_536,
+});
+engine.setClips([{ id: 1, pageProvider: provider, startPpq: 0 }]);
+engine.play();
+
+// On each animation frame / control tick:
+await streamer.pump(); // fetch upcoming pages, evict old ones
+```
+
 ### Real-time voice changer
 
 `RealtimeVoiceChanger` runs a block-by-block voice transformation chain (retune,
@@ -520,7 +552,7 @@ try {
 }
 
 // Whole-buffer convenience wrapper (constructs/prepares/disposes internally).
-const processed = voiceChangeRealtime(samples, { preset: 'deep-narrator', sampleRate: 48000 });
+const processed = voiceChangeRealtime(samples, 48000, 'deep-narrator');
 ```
 
 For a simple offline pitch + formant shift without the full chain, use
@@ -627,8 +659,8 @@ function readMeters() {
 
 For browser DAW-style playback, `SonareEngine` keeps a main-thread
 `RealtimeEngine` mirror for offline renders and synchronizes the live worklet
-engine through control messages. The default runtime target is the embind engine;
-the `sonare-rt` runtime remains a transport-focused fallback.
+engine through control messages. There is a single runtime: the full-featured
+embind engine runs both the main-thread mirror and the AudioWorklet.
 
 ```typescript
 import { init } from '@libraz/libsonare';
@@ -665,8 +697,7 @@ Studio integration notes:
   `sync*`, `captureRequest`, and `transportRequest` message used above to that
   allowlist; otherwise the host may silently drop the new control messages.
 - If a host vendors built worklet bundles, regenerate and reimport
-  `worklet.js`, `worklet.d.ts`, `sonare.js`, `sonare.wasm`,
-  `sonare-rt.js`, `sonare-rt-module.js`, and `sonare-rt.wasm` together.
+  `worklet.js`, `worklet.d.ts`, `sonare.js`, and `sonare.wasm` together.
 
 ### Progress callback
 
@@ -757,7 +788,7 @@ try {
 - **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; streaming mastering chain, equalizer, and retune
-- **Instruments**: built-in synth, patch-driven NativeSynth, SoundFont (SF2) player — bound to `Project` bounces or the `RealtimeEngine`
+- **Instruments**: built-in synth, patch-driven NativeSynth (12 synthesis engines, incl. physically-modeled piano/strings/winds — being tuned over time), 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`