@libraz/libsonare 1.5.5 → 1.6.0

package/README.md

@@ -12,7 +12,7 @@
 (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. 76 named mastering DSP processors implemented against published
+weights. 88 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.
@@ -31,17 +31,26 @@ Everything runs client-side — no server, nothing uploaded.
 npm install @libraz/libsonare
 ```
 
+For BPM/key/chord detection, feature extraction, and metering without the
+mastering, mixing, or realtime-engine APIs, import the smaller analysis entry:
+
+```typescript
+import { detectBpm, init } from '@libraz/libsonare/analysis';
+```
+
+With emsdk 5.0.2, the analysis binary is 0.86 MiB raw / 347 KiB gzip; the full
+entry is 3.76 MiB raw / 1.26 MiB gzip. The analysis entry deliberately has no
+`masterAudio`, `mixStereo`, `Project`, `Mixer`, or `RealtimeEngine` export.
+
 ## Quick Start
 
 `init()` loads the WASM module once; every API is available afterwards. Top-level
 one-shot functions accept a request object (recommended) or positional arguments.
 
-> **Audio input:** analysis works on decoded `Float32Array` mono samples.
-> `Audio.fromMemory` decodes WAV from an in-memory buffer, but the WebAssembly
-> build bundles no decoder for compressed formats — use the Web Audio API
-> (`decodeAudioData`) for MP3 / M4A / AAC / Opus / FLAC, or the native N-API
-> package [`@libraz/libsonare-native`](https://github.com/libraz/libsonare/tree/main/bindings/node)
-> to read files from disk.
+> **Audio input:** start with `Audio.fromMemoryWithBrowserFallback(bytes)`. It
+> decodes WAV/MP3 in WASM, then uses the browser's `decodeAudioData` for other
+> browser-supported formats. Pass a decoded mono `Float32Array` only when one is
+> already available.
 
 > **Platform constraints:** the WebAssembly build is single-threaded (analysis
 > runs to completion on the calling thread — there is no non-blocking variant)
@@ -49,17 +58,14 @@ one-shot functions accept a request object (recommended) or positional arguments
 > to keep the UI responsive.
 
 ```typescript
-import { init, analyze, masterAudio } from '@libraz/libsonare';
+import { Audio, init } from '@libraz/libsonare';
 
 await init();
 
-// Analyze decoded Float32Array mono samples
-const { bpm, key } = analyze({ samples, sampleRate });
+const bytes = new Uint8Array(await file.arrayBuffer());
+const audio = await Audio.fromMemoryWithBrowserFallback(bytes);
+const { bpm, key } = audio.analyze();
 console.log(`BPM: ${bpm}  Key: ${key.name}`);
-
-// Master toward a target loudness with a named preset
-const mastered = masterAudio({ samples, sampleRate, preset: 'streaming' });
-console.log(mastered.outputLufs, mastered.appliedGainDb);
 ```
 
 Render a MIDI arrangement through a built-in instrument with the headless
@@ -83,16 +89,52 @@ try {
 }
 ```
 
-### Decoding audio in the browser
+### Using already-decoded audio
 
-The WASM build takes decoded samples, so decode with the Web Audio API first:
+Use `Float32Array` directly when another API already decoded the audio:
 
 ```typescript
-const buf = await fetch('song.m4a').then((r) => r.arrayBuffer());
-const decoded = await new AudioContext().decodeAudioData(buf);
-const { bpm, key } = analyze({ samples: decoded.getChannelData(0), sampleRate: decoded.sampleRate });
+const audio = Audio.fromBuffer(decoded.getChannelData(0), decoded.sampleRate);
+const { bpm, key } = audio.analyze();
+```
+
+### Offline Worker for longer audio
+
+For audio longer than roughly 30 seconds, use `OfflineWorkerClient` to keep
+analysis or preset mastering off the UI thread. The published `./worker`
+subpath is resolved automatically. It intentionally exposes only one-shot
+value APIs (`analyze`, BPM/key/chord detection, and `masterAudio`): native
+handles such as `Project`, `Mixer`, and realtime engines stay in their owning
+JavaScript realm.
+
+```typescript
+import { OfflineWorkerClient } from '@libraz/libsonare';
+
+const offline = new OfflineWorkerClient();
+const task = offline.analyze(
+  { samples, sampleRate },
+  {
+    onProgress: ({ progress, stage }) => updateProgress(progress, stage),
+    // copy: true, // retain `samples`; the default transfers and detaches it
+  },
+);
+
+cancelButton.onclick = () => task.cancel();
+try {
+  const result = await task;
+  console.log(result.bpm, result.key.name);
+} finally {
+  offline.dispose();
+}
 ```
 
+By default the input `Float32Array` is transferred, so its buffer is detached
+on the calling thread. Pass `{ copy: true }` when it must remain usable. Prompt
+cancellation of a running synchronous WASM call uses `SharedArrayBuffer`; serve
+the page with cross-origin isolation (COOP/COEP) when a cancel button must take
+effect immediately. `workerUrl` lets a host point the client at a separately
+hosted copy of `@libraz/libsonare/worker`.
+
 ### Loading the `.wasm` file
 
 Bundlers that don't auto-resolve the `.wasm` asset need its URL. Pass a
@@ -109,13 +151,60 @@ From a CDN, `import { init } from 'https://esm.sh/@libraz/libsonare'` resolves t
 [getting-started guide](https://libsonare.libraz.net/docs/getting-started) for
 per-bundler setup and the AudioWorklet bridge.
 
+### Realtime voice changer preset schemas
+
+The published package includes the JSON Schema documents for third-party voice
+changer presets. Resolve them through the package exports rather than copying a
+schema from the repository:
+
+```text
+@libraz/libsonare/schemas/realtime-voice-changer-preset.schema.json
+@libraz/libsonare/schemas/realtime-voice-changer-preset-pack.schema.json
+```
+
+Validate data against the schema before saving it, then pass the JSON text to
+`validateRealtimeVoiceChangerPresetJson()` before applying it. The runtime check
+is authoritative and also rejects malformed JSON such as duplicate keys.
+
+### Bounded-memory OPFS clip streaming
+
+For long raw float32 clips stored in OPFS, `attachOpfsClipStream` supplies only
+the current playback window to WASM. It primes the first page, then fetches page
+misses on the main thread and evicts pages outside the configured read-ahead /
+retain-behind window. The AudioWorklet path uses the same helper: the worklet
+posts a bounded batch of misses, and it outputs silence until a page arrives.
+
+```typescript
+import { attachOpfsClipStream } from '@libraz/libsonare';
+import { SonareEngine } from '@libraz/libsonare/worklet';
+
+const engine = await SonareEngine.create(audioContext);
+const stream = await attachOpfsClipStream(engine, {
+  path: 'takes/lead.f32',
+  clipId: 42,
+  numChannels: 2,
+  numSamples: 48_000 * 600,
+  pageFrames: 16_384,
+});
+
+// `clipId` must equal the explicit id supplied here.
+engine.addClip(trackId, stream.provider, 0, { id: 42 });
+
+// Close the returned binding after removing the clip (or when the host closes).
+stream.binding.close();
+```
+
+The bounded-memory guarantee applies only to an OPFS/page-provider source.
+Passing a `Float32Array[]` to `addClip` keeps that full array in the JavaScript
+heap, so it is appropriate for short clips but does not make long clips bounded.
+
 ## Capabilities
 
 Every area below has runnable examples and the full API in the
 [documentation](https://libsonare.libraz.net/docs/wasm).
 
 - **Analysis** — BPM, key (+ candidates), chords, downbeats, sections, melody, tuning; pitch (YIN / pYIN), timbre, and the full spectral feature set (STFT, mel, MFCC, chroma, CQT/VQT, spectral contrast); metering (true-peak, LUFS, correlation, vectorscope, waveform peaks). → [API](https://libsonare.libraz.net/docs/wasm)
-- **Mastering** — 76 named DSP processors, the configurable `masteringChain`, 25 named presets via `masterAudio`, and reference-matching. → [Mastering processors](https://libsonare.libraz.net/docs/mastering-processors)
+- **Mastering** — 88 named DSP processors, the configurable `masteringChain`, 25 named presets via `masterAudio`, and reference-matching. → [Mastering processors](https://libsonare.libraz.net/docs/mastering-processors)
 - **Mixing** — offline `mixStereo` and the block-based `Mixer` with scene presets. → [Mixing](https://libsonare.libraz.net/docs/mixing)
 - **Editing DSP** — time-stretch, pitch-shift, HPSS (+ residual), phase vocoder, normalize, trim, remix. → [Editing DSP](https://libsonare.libraz.net/docs/editing-dsp)
 - **Room acoustics** — blind RT60 / EDT, impulse-response clarity metrics, RIR synthesis, room estimation and morphing. → [Room acoustics](https://libsonare.libraz.net/docs/acoustic-analysis)