@libraz/libsonare 1.2.0 → 1.2.2

package/README.md

@@ -9,7 +9,7 @@
 
 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: 77 named mastering DSP
+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,
@@ -56,6 +56,57 @@ console.log(`Key: ${audio.detectKey().name}`);
 const audioKeyWithOptions = audio.detectKey({ useHpss: true, highPassHz: 80 });
 ```
 
+### Pitch, timbre, and spectral APIs
+
+Pitch tracking keeps unvoiced `f0` frames as `NaN` by default. Pass
+`fillNa: true` when downstream code needs finite values and should treat
+unvoiced frames as `0`. Timbre analysis returns aggregate metrics plus
+`timbreOverTime`.
+
+```typescript
+import {
+  analyzeTimbre,
+  decompose,
+  ebur128LoudnessRange,
+  estimateTuning,
+  hpssWithResidual,
+  init,
+  lufsInterleaved,
+  nnFilter,
+  phaseVocoder,
+  pitchPyin,
+  pitchTuning,
+  pitchYin,
+  polyFeatures,
+  remix,
+  spectralContrast,
+  zeroCrossings,
+} from '@libraz/libsonare';
+
+await init();
+
+const yin = pitchYin(samples, sampleRate, 2048, 512, 65, 2093, 0.3, true);
+const pyin = pitchPyin(samples, sampleRate, 2048, 512, 65, 2093, 0.3, true);
+
+const timbre = analyzeTimbre(samples, sampleRate);
+console.log(timbre.brightness, timbre.timbreOverTime[0]?.brightness);
+
+const contrast = spectralContrast(samples, sampleRate); // Matrix2d result
+const poly = polyFeatures(samples, sampleRate);         // Matrix2d result
+const crossings = zeroCrossings(samples);               // Int32Array
+const tuning = estimateTuning(samples, sampleRate);
+const offset = pitchTuning(yin.f0);
+
+const { w, h } = decompose(spectrogram, nFeatures, nFrames, 8);
+const filtered = nnFilter(spectrogram, nFeatures, nFrames);
+const remixed = remix(samples, Int32Array.from([0, sampleRate, sampleRate, 2 * sampleRate]));
+const stretched = phaseVocoder(samples, 1.5, sampleRate);
+const hpss = hpssWithResidual(samples, sampleRate);
+
+const multi = lufsInterleaved(interleaved, 2, sampleRate);
+const lra = ebur128LoudnessRange(samples, sampleRate);
+```
+
 ### Room acoustics
 
 Use `detectAcoustic` for blind RT60/EDT estimation from ordinary audio.
@@ -392,11 +443,12 @@ chain.delete(); // release WASM memory
 ## Features
 
 - **Detection**: BPM, key, beats, onsets, chords, sections
-- **Effects**: HPSS, time stretch, pitch shift, normalize, trim
+- **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 features
-- **Pitch**: YIN, pYIN algorithms
+- **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
 - **Conversions**: Hz/mel/MIDI/note, frames/time, resample