@libraz/libsonare 1.0.3 → 1.1.0

package/README.md

@@ -2,11 +2,19 @@
 
 [![CI](https://img.shields.io/github/actions/workflow/status/libraz/libsonare/ci.yml?branch=main&label=CI)](https://github.com/libraz/libsonare/actions)
 [![npm](https://img.shields.io/npm/v/@libraz/libsonare)](https://www.npmjs.com/package/@libraz/libsonare)
-[![PyPI](https://img.shields.io/pypi/v/libsonare)](https://pypi.org/project/libsonare/)
+[![npm downloads](https://img.shields.io/npm/dm/@libraz/libsonare)](https://www.npmjs.com/package/@libraz/libsonare)
+[![types](https://img.shields.io/npm/types/@libraz/libsonare)](https://www.npmjs.com/package/@libraz/libsonare)
 [![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/)
 
 Fast, dependency-free audio analysis library for browser and Node.js via WebAssembly.
 
+> **Audio input:** This package expects already-decoded `Float32Array` mono
+> samples (it does not bundle a file decoder). Use the Web Audio API in the
+> browser or `node:wasi` / a JS audio decoder in Node to obtain samples.
+> 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.
+
 ## Installation
 
 ```bash
@@ -32,6 +40,24 @@ console.log(`BPM: ${audio.detectBpm()}`);
 console.log(`Key: ${audio.detectKey().name}`);
 ```
 
+### Decoding files in the browser
+
+```typescript
+import { init, analyze } from '@libraz/libsonare';
+
+await init();
+
+const arrayBuffer = await fetch('song.m4a').then((r) => r.arrayBuffer());
+const audioCtx = new AudioContext();
+const decoded = await audioCtx.decodeAudioData(arrayBuffer);
+// Mono downmix for libsonare:
+const samples = decoded.getChannelData(0);
+const result = analyze(samples, decoded.sampleRate);
+```
+
+Web Audio's `decodeAudioData` handles whatever codecs the browser ships with
+(WAV/MP3/M4A/AAC/Opus/FLAC on most modern browsers).
+
 ### Browser (CDN)
 
 ```html
@@ -70,10 +96,143 @@ const stats = analyzer.stats();
 console.log(`BPM: ${stats.estimate.bpm}, Key: ${stats.estimate.key}`);
 ```
 
+### Mastering (WASM)
+
+The npm package ships mastering DSP in the default WebAssembly build. Pass
+decoded `Float32Array` samples directly:
+
+```typescript
+import { init, masteringChain, masteringChainStereo } from '@libraz/libsonare';
+
+await init();
+
+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 },
+});
+
+const stereo = masteringChainStereo(left, right, sampleRate, {
+  stereo: { imager: { width: 1.1 }, monoMaker: { amount: 0.2 } },
+  loudness: { targetLufs: -14, ceilingDb: -1, truePeakOversample: 4 },
+});
+```
+
+Named mastering processors use the same names and behavior as the native,
+Python, C, and CLI APIs:
+
+```typescript
+import {
+  masteringPairAnalyze,
+  masteringPairProcess,
+  masteringPairProcessorNames,
+  masteringProcess,
+  masteringProcessStereo,
+  masteringProcessorNames,
+  masteringStereoAnalyze,
+} from '@libraz/libsonare';
+
+const names = masteringProcessorNames(); // e.g. "dynamics.compressor"
+const compressed = masteringProcess('dynamics.compressor', samples, sampleRate, {
+  thresholdDb: -24,
+  ratio: 1.5,
+});
+
+const widened = masteringProcessStereo('stereo.imager', left, right, sampleRate, {
+  width: 1.1,
+});
+
+const pairNames = masteringPairProcessorNames(); // e.g. "match.abCrossfade"
+const crossfaded = masteringPairProcess('match.abCrossfade', source, reference, sampleRate, {
+  mix: 0.25,
+});
+
+const loudnessJson = masteringPairAnalyze(
+  'match.referenceLoudness',
+  source,
+  reference,
+  sampleRate,
+);
+const monoCompatJson = masteringStereoAnalyze(
+  'stereo.monoCompatCheck',
+  left,
+  right,
+  sampleRate,
+);
+```
+
+### Mastering presets
+
+```typescript
+import { init, masterAudio, masteringPresetNames } from '@libraz/libsonare';
+
+await init();
+
+masteringPresetNames(); // ['pop', 'edm', 'acoustic', 'hipHop', 'aiMusic', 'speech']
+
+const result = masterAudio(samples, sampleRate, 'aiMusic', {
+  // optional flat overrides applied on top of the preset (dot notation)
+  'loudness.targetLufs': -13,
+});
+console.log(result.outputLufs, result.appliedGainDb);
+```
+
+### Progress callback
+
+`masteringChainWithProgress` (and its stereo variant) is `masteringChain` with
+an extra `(progress, stage) => void` callback invoked after each enabled stage:
+
+```typescript
+import { init, masteringChainWithProgress } from '@libraz/libsonare';
+
+await init();
+
+masteringChainWithProgress(
+  samples,
+  sampleRate,
+  { dynamics: { compressor: { thresholdDb: -24 } } },
+  (progress, stage) => console.log(`${stage}: ${(progress * 100).toFixed(0)}%`),
+);
+```
+
+### Streaming mastering chain
+
+`StreamingMasteringChain` processes blocks while maintaining per-stage state
+across calls. It only supports modules whose state depends solely on the
+sample rate — it cannot include `repair.denoise` or `loudness` (those require
+offline / look-ahead analysis) and throws at construction if they are enabled.
+
+```typescript
+import { init, StreamingMasteringChain } from '@libraz/libsonare';
+
+await init();
+
+const chain = new StreamingMasteringChain({
+  eq: { tiltDb: 0.5 },
+  dynamics: { compressor: { thresholdDb: -20 } },
+});
+chain.prepare(48000, 512, 2);
+
+// Mono block
+const monoBlock = new Float32Array(512);
+const processedMono = chain.processMono(monoBlock);
+
+// Stereo block (separate L/R Float32Arrays)
+const left = new Float32Array(512);
+const right = new Float32Array(512);
+const { left: outL, right: outR } = chain.processStereo(left, right);
+
+chain.reset();
+chain.delete(); // release WASM memory
+```
+
 ## Features
 
 - **Detection**: BPM, key, beats, onsets, chords, sections
 - **Effects**: HPSS, time stretch, pitch shift, normalize, trim
+- **Mastering**: EQ, compressor, tape/exciter, air band, stereo imaging,
+  true-peak limiting, loudness optimization
 - **Features**: STFT, mel spectrogram, MFCC, chroma, CQT/VQT, spectral features
 - **Pitch**: YIN, pYIN algorithms
 - **Streaming**: Real-time analysis with progressive estimates