@libraz/libsonare 1.7.2 → 1.8.0

package/NOTICE

@@ -0,0 +1,178 @@
+libsonare
+Copyright 2024 libsonare contributors
+
+This product includes software developed by third parties. Below is the
+attribution for each third-party component whose code reaches a distributed
+binary, and for the project from which algorithms were ported.
+
+================================================================================
+librosa
+================================================================================
+
+  Copyright (c) 2013--2023, librosa development team
+
+  Licensed under the ISC License.
+
+  libsonare ports audio analysis algorithms from librosa, a Python library for
+  music and audio analysis.
+
+  https://github.com/librosa/librosa
+
+================================================================================
+KissFFT
+================================================================================
+
+  Copyright (c) 2003-2010, Mark Borgerding. All rights reserved.
+
+  Licensed under the BSD 3-Clause License (SPDX: BSD-3-Clause).
+
+  https://github.com/mborgerding/kissfft
+
+  Vendored in: third_party/kissfft/
+
+================================================================================
+r8brain-free-src
+================================================================================
+
+  Copyright (c) 2013-2025 Aleksey Vaneev
+
+  Licensed under the MIT License.
+
+  https://github.com/avaneev/r8brain-free-src
+
+  Vendored in: third_party/r8brain/
+
+  r8brain-free-src bundles FFT implementations by other authors under
+  third_party/r8brain/fft/. The MIT notice above covers Aleksey Vaneev's work
+  only; each bundled implementation keeps its own copyright and terms:
+
+    Ooura FFT (fft4g.h) — the implementation r8brain's own resampler uses,
+    since neither R8B_PFFFT nor R8B_IPP is defined. PFFFT below is compiled
+    separately by this project when SONARE_USE_PFFFT is on.
+
+      Copyright (C) 1996-2001 Takuya OOURA
+
+      Used with permission granted by the author's license.
+
+      http://www.kurims.kyoto-u.ac.jp/~ooura/fft.html
+
+    PFFFT and PFFFT DOUBLE (pffft*.c, pffft*.h, simd/pf_*.h)
+
+      Copyright (c) 2013 Julien Pommier
+      Copyright (c) 2020 Hayati Ayguen
+      Copyright (c) 2020 Dario Mambro
+
+      Derived from FFTPACK v4, authored by Dr Paul Swarztrauber of NCAR, and
+      distributed under the FFTPACK v5 license (SPDX: BSD-3-Clause):
+
+        Copyright (c) 2004 the University Corporation for Atmospheric
+        Research ("UCAR"). All rights reserved. Developed by NCAR's
+        Computational and Information Systems Laboratory, UCAR,
+        www.cisl.ucar.edu.
+
+      https://bitbucket.org/jpommier/pffft
+      https://github.com/marton78/pffft
+
+    AVX-to-NEON translation layer (simd/pf_neon_double_from_avx.h)
+
+      Copyright (C) 2020 Huawei Technologies Co., Ltd. All rights reserved.
+
+      Licensed under the Apache License, Version 2.0 (SPDX: Apache-2.0).
+
+      https://github.com/kunpengcompute/AvxToNeon
+
+================================================================================
+dr_libs (dr_wav)
+================================================================================
+
+  Copyright 2023 David Reid
+
+  Available as a choice of Public Domain (Unlicense) or MIT No Attribution
+  (MIT-0).
+
+  https://github.com/mackron/dr_libs
+
+  Vendored in: third_party/dr_libs/
+
+================================================================================
+minimp3
+================================================================================
+
+  To the extent possible under law, the author(s) have dedicated all copyright
+  and related and neighboring rights to this software to the public domain
+  worldwide.
+
+  Licensed under CC0 1.0 Universal (Public Domain Dedication).
+
+  https://github.com/lieff/minimp3
+
+  Vendored in: third_party/minimp3/
+
+================================================================================
+Eigen
+================================================================================
+
+  Copyright (c) Benoit Jacob, Gael Guennebaud and the other Eigen contributors
+
+  Licensed under the Mozilla Public License 2.0 (SPDX: MPL-2.0). Some files in
+  the upstream distribution carry BSD or LGPL terms instead; libsonare compiles
+  with EIGEN_MPL2_ONLY, which upstream defines as a guarantee that no LGPL file
+  is included and makes including one a compilation error.
+
+  Eigen is header-only and is not vendored: the build uses a system Eigen 3.3 or
+  newer where one is installed and otherwise fetches 3.4.1 at configure time.
+  Either way its code is compiled into the distributed binaries, which is why it
+  is listed here. Source for the version a binary was built against is available
+  from the URL below.
+
+  https://gitlab.com/libeigen/eigen
+
+================================================================================
+SADIE II HRTF Database
+================================================================================
+
+  Copyright 2018, University of York.
+
+  Licensed under the Apache License, Version 2.0 (SPDX: Apache-2.0).
+
+  libsonare embeds a derived subset of the SADIE II database's subject D1
+  (KU100) head-related impulse responses as the playback renderer's default
+  HRTF set. The original measurements were reduced to a 5-degree-azimuth by
+  15-degree-elevation grid, converted to 128-tap minimum-phase filters with a
+  separately extracted interaural time delay per direction, and quantized to
+  int16 in libsonare's own SHRF container format.
+
+  Citation: Armstrong, C., Thresh, L., Murphy, D., Kearney, G. (2018). "A
+  Perceptual Evaluation of Individual and Non-Individual HRTFs: A Case Study
+  of the SADIE II Database." Applied Sciences, 8(11), 2029.
+
+  https://www.york.ac.uk/sadie-project/database.html
+
+  Embedded as: src/playback/default.shrf
+
+  The stereo.binaural insert embeds a further reduction of that set's
+  elevation-0 row: left/right mirror-averaged 64-tap minimum-phase filters and
+  ITDs (src/mastering/stereo/binaural_ring.inc).
+
+================================================================================
+Japanese vowel formant data (Yazawa and Kondo)
+================================================================================
+
+  Licensed under CC-BY-4.0. Yazawa, K. and Kondo, M. (2019), Japanese vowel
+  length data, Zenodo record 15227304 (https://zenodo.org/records/15227304).
+  The male-speaker mean formants of /a e i o u/ set the vowel ratios of the
+  effects.filter.vowel table (src/effects/filter/vowel_filter.cpp).
+
+================================================================================
+soundings renderer (GS classic insertion-effect graph)
+================================================================================
+
+  Copyright (c) 2026 libraz
+
+  Licensed under the MIT License.
+
+  The classic GS insertion-effect realisation (src/midi/synth/gs_classic/)
+  ports the node-graph renderer of the soundings measurement project to C++,
+  and src/midi/synth/gs_classic_models.inc is generated from that project's
+  model files by tools/gs/classic_models.py. The measurements themselves are
+  dedicated to the public domain (CC0).

package/README.md

@@ -8,22 +8,9 @@
 [![Docs](https://img.shields.io/badge/docs-libsonare.libraz.net-2563eb)](https://libsonare.libraz.net)
 [![PyPI](https://img.shields.io/pypi/v/libsonare?label=PyPI)](https://pypi.org/project/libsonare/)
 
-**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. 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.
+**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 model weights. 91 named mastering DSP processors implemented against published references; analysis defaults match librosa where the two overlap.
 
-## Try it in the browser
-
-Everything runs client-side — no server, nothing uploaded.
-
-- 🎧 **[Live demos](https://libsonare.libraz.net/demos)** — analyze a song (BPM / key / chords), master to a target loudness, mix, and render MIDI through the built-in instruments, all in the page.
-- 🎛️ **[sonare studio](https://sonare-studio.libraz.net)** — a full browser DAW (multi-track sequencing, piano roll, mixer, mastering, WAV / MP3 / MIDI / MusicXML export) built entirely on this WASM engine. It shows how far one Apache-2.0 engine reaches, from analysis to a playable, exportable arrangement.
-- 📖 **[Documentation & getting started](https://libsonare.libraz.net/docs/getting-started)**
+**Guides and the full API reference: [libsonare.libraz.net](https://libsonare.libraz.net)**. Try it without installing anything: the [live demos](https://libsonare.libraz.net/demos), or [sonare studio](https://sonare-studio.libraz.net), a browser DAW whose audio runs on this engine.
 
 ## Installation
 
@@ -31,31 +18,11 @@ 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.91 MiB raw / 368 KiB gzip; the full
-entry is 3.88 MiB raw / 1.31 MiB gzip. The analysis entry deliberately has no
-`masterAudio`, `mixStereo`, `Project`, `Mixer`, or `RealtimeEngine` export.
+For BPM / key / chord detection, feature extraction and metering without the mastering, mixing or realtime-engine APIs, import the smaller analysis entry: `import { detectBpm, init } from '@libraz/libsonare/analysis'`.
 
 ## 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:** 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)
-> and has no host filesystem access. Drive long-running calls from a Web Worker
-> to keep the UI responsive.
+`init()` loads the WASM module once. Start from `Audio.fromMemoryWithBrowserFallback(bytes)`, which decodes WAV / MP3 in WASM and uses the browser's `decodeAudioData` for other formats. The build is single-threaded, so drive long calls from a Web Worker.
 
 ```typescript
 import { Audio, init } from '@libraz/libsonare';
@@ -68,8 +35,7 @@ const { bpm, key } = audio.analyze();
 console.log(`BPM: ${bpm}  Key: ${key.name}`);
 ```
 
-Render a MIDI arrangement through a built-in instrument with the headless
-`Project`. The embind handle is not garbage-collected — call `delete()` when done.
+Render a MIDI arrangement through a built-in instrument with the headless `Project`. The embind handle is not garbage-collected — call `delete()` when done.
 
 ```typescript
 import { init, Project } from '@libraz/libsonare';
@@ -89,173 +55,31 @@ try {
 }
 ```
 
-### Using already-decoded audio
-
-Use `Float32Array` directly when another API already decoded the audio:
-
-```typescript
-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
-`locateFile` resolver to `init()`:
-
-```typescript
-import wasmUrl from '@libraz/libsonare/wasm?url'; // Vite; adapt per bundler
-
-await init({ locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : path) });
-```
-
-From a CDN, `import { init } from 'https://esm.sh/@libraz/libsonare'` resolves the
-`.wasm` automatically. See the
-[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.
-
-### Cue bus on a second AudioWorklet output
-
-Per-track PFL/AFL monitoring normally folds the cue into the program output.
-Pass `cueOutput` and the node gains a second output carrying the cue alone, so
-it can be routed to headphones or a separate device while the program mix stays
-untouched.
-
-```typescript
-import { SonareEngine } from '@libraz/libsonare/worklet';
-
-const engine = await SonareEngine.create(audioContext, { cueOutput: true });
-engine.setTrackMonitorMode(trackId, 'pfl');
-
-engine.node.connect(audioContext.destination, 0); // program
-engine.node.connect(cueDestination, 1); // cue
-```
-
-Without `cueOutput` the node keeps a single output and the folded mix, sample
-for sample. Off the worklet, the same split is available on the zero-copy path
-as `prepareMonitorChannels` / `getMonitorChannelBuffer` /
-`processPreparedWithMonitor`, and as `processWithMonitor` for a copy-in call.
-
-### Mastering preview inside the worklet
-
-`StreamingMasteringChain` is exported from `@libraz/libsonare/worklet`, so a live
-preview can run in the render realm instead of round-tripping audio to the main
-thread. Build and `prepare()` it from a message handler — `prepare()` allocates
-and must not run inside `process()`. An enabled `loudness` stage needs the
-offline-measured `loudnessStaticGainDb`, since whole-signal integrated LUFS
-cannot be measured block by block. The chain is a host-side stage: it is outside
-the engine's own delay compensation, so aligning it against other engine outputs
-is the caller's job.
-
 ## 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** — 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)
-- **Realtime & streaming** — `RealtimeEngine` (transport / MIDI / render, bounded-memory clip streaming), `StreamingMasteringChain` / `StreamingEqualizer` / `StreamingRetune`, `RealtimeVoiceChanger`, and the AudioWorklet bridge. → [Realtime & streaming](https://libsonare.libraz.net/docs/realtime-streaming)
-- **Instruments & synthesis** — built-in oscillator synth, patch-driven NativeSynth (15 synthesis engines, incl. physically-modeled piano / strings / winds — being tuned over time), and a GS-compatible SoundFont (SF2) player. → [API](https://libsonare.libraz.net/docs/wasm)
-- **Headless DAW** — `Project` arrangement model: audio / MIDI tracks and clips, undo/redo, clip warp, SMF / MIDI 2.0 Clip File I/O, deterministic JSON, offline `bounce`. → [API](https://libsonare.libraz.net/docs/wasm)
-- **Conversions** — Hz / mel / MIDI / note, frames / time, resample.
-
-Native failures throw a `SonareError` carrying a numeric `code` (an `ErrorCode`
-value) and its `codeName`; narrow with the `isSonareError` type guard.
+- **Analysis** — BPM, key, chords, downbeats, sections, melody, tuning, pitch, timbre, spectral features and metering. → [Analysis](https://libsonare.libraz.net/docs/wasm)
+- **Stem decomposition and transcription** — `decomposeStems` splits a mix into stems, and `transcribe` turns audio into MIDI events. → [Analysis](https://libsonare.libraz.net/docs/js-api-analysis)
+- **Mastering** — 91 named DSP processors, the configurable `masteringChain`, 30 named presets via `masterAudio`, and reference-matching. → [Mastering processors](https://libsonare.libraz.net/docs/mastering-processors)
+- **Restoration** — five repair-only presets, `vinyl`, `tapeHiss`, `fieldRecording`, `voiceMemo` and `shellac78`. → [Mastering processors](https://libsonare.libraz.net/docs/mastering-processors)
+- **Mixing** — offline `mixStereo`, the block-based `Mixer` with scene presets, and `suggestMixScene`, which suggests a mixer scene with a written explanation without applying it; `sampleRate` is **required** and must be an integer within `[8000, 384000]`. → [Mixing](https://libsonare.libraz.net/docs/mixing), [Mixing assistant](https://libsonare.libraz.net/docs/mixing-assistant)
+- **Editing DSP** — time-stretch, pitch-shift, HPSS, phase vocoder, normalize, trim, remix. → [Editing DSP](https://libsonare.libraz.net/docs/editing-dsp)
+- **Note editing and takes** — edit the notes of monophonic takes (`extractNotes`) and polyphonic material (`analyzePolyphonic`), align a take to a reference with `alignTakeToReference`, and build tuning targets from a MIDI melody with `noteTargetsFromSmf`. → [Project editing](https://libsonare.libraz.net/docs/project-editing-midi), [Recording and takes](https://libsonare.libraz.net/docs/recording-and-takes)
+- **Room acoustics** — blind RT60, impulse-response metrics, RIR synthesis, room estimation and morphing. → [Room acoustics](https://libsonare.libraz.net/docs/acoustic-analysis)
+- **Realtime and streaming** — `RealtimeEngine` with MIDI 1.0 / 2.0 input, bus-to-bus routing with sends, sidechain keys (`setBusSidechain`), `StreamingMasteringChain`, `RealtimeVoiceChanger` and the AudioWorklet bridge. → [Realtime engine](https://libsonare.libraz.net/docs/realtime-engine), [Streaming](https://libsonare.libraz.net/docs/wasm-streaming)
+- **Instruments and synthesis** — built-in synth, the patch-driven NativeSynth, and a GS-compatible SoundFont (SF2) player that receives GS SysEx and offers two GS insertion-effect realisations (`gsEfxRealization`). The acoustic piano is calibrated; the other physical-model voices are still being tuned and will change in 1.8.x patch releases. → [GM and GS](https://libsonare.libraz.net/docs/gm-gs), [Native synth](https://libsonare.libraz.net/docs/native-synth)
+- **Headless DAW** — `Project` with audio and MIDI tracks, undo/redo, SMF and MIDI 2.0 Clip File I/O, and offline `bounce`; `transcribeToClip` writes a transcription into a clip. → [Project editing](https://libsonare.libraz.net/docs/project-editing)
+- **Playback** — `PlaybackRenderer` renders PCM up to 7.1 to speakers or HRTF binaural headphones. → [Playback](https://libsonare.libraz.net/docs/playback)
+
+## Advanced
+
+- Offline Worker for long audio (`OfflineWorkerClient`) → [Web Worker usage](https://libsonare.libraz.net/docs/wasm-advanced)
+- Loading the `.wasm` file with `locateFile` → [JavaScript API](https://libsonare.libraz.net/docs/js-api)
+- Realtime voice changer preset schemas → [Realtime voice changer](https://libsonare.libraz.net/docs/realtime-voice-changer)
+- Bounded-memory OPFS clip streaming, the cue bus and mastering preview in the worklet → [Realtime and streaming](https://libsonare.libraz.net/docs/realtime-streaming)
 
 ## Documentation
 
-Full API reference, guides, and browser-local demos live at
-**[libsonare.libraz.net](https://libsonare.libraz.net)**
-([getting started](https://libsonare.libraz.net/docs/getting-started) ·
-[browser / WASM API](https://libsonare.libraz.net/docs/wasm) ·
-[demos](https://libsonare.libraz.net/demos)).
+[Getting started](https://libsonare.libraz.net/docs/getting-started) · [Browser / WASM API](https://libsonare.libraz.net/docs/wasm) · [Examples](https://libsonare.libraz.net/docs/examples) · [Binding parity](https://libsonare.libraz.net/docs/binding-parity) · [Demos](https://libsonare.libraz.net/demos).
 
 ## Also available
 
@@ -263,8 +87,7 @@ Full API reference, guides, and browser-local demos live at
 pip install libsonare  # Python bindings with CLI
 ```
 
-The native Node.js N-API binding (reads files from disk) lives at
-[`bindings/node`](https://github.com/libraz/libsonare/tree/main/bindings/node).
+The native Node.js N-API binding (reads files from disk) lives at [`bindings/node`](https://github.com/libraz/libsonare/tree/main/bindings/node).
 
 ## License
 

package/dist/_chain_config.d.ts

@@ -0,0 +1,14 @@
+import type { MasteringChainConfig } from './public_types';
+/**
+ * Flattens a nested {@link MasteringChainConfig} into the dot-notation
+ * `{ "module.processor.param": value }` map the core consumes. Internal helper
+ * shared by the mastering-chain / master-audio entry points. The core owns
+ * legacy leaf-name aliases, so this remains a structural flattening step.
+ *
+ * A key the caller already wrote in dot notation carries through untouched, so
+ * both spellings a {@link MasteringChainConfig} accepts reach the core as the
+ * same parameter — matching what the Python binding documents. An unknown key
+ * in either spelling is rejected by the core, not here.
+ */
+export declare function flattenChainConfig(config: MasteringChainConfig): Record<string, number | boolean>;
+//# sourceMappingURL=_chain_config.d.ts.map

package/dist/_chain_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_chain_config.d.ts","sourceRoot":"","sources":["../src/_chain_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAI3D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAiBjG"}

package/dist/_effects_common.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Input conversion the effect families share.
+ */
+import type { VoicedFlags } from './public_types';
+export declare function toVoicedFloat32(voiced: VoicedFlags): Float32Array;
+//# sourceMappingURL=_effects_common.d.ts.map

package/dist/_effects_common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_effects_common.d.ts","sourceRoot":"","sources":["../src/_effects_common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMlD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAMjE"}

package/dist/_feature_validation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Input checks the spectrogram and inverse-transform entries share.
+ */
+import type { ValidateOptions } from './validation';
+export type GuardedOptions = ValidateOptions;
+export declare function validatePositiveIntegers(fnName: string, values: Record<string, number>): void;
+export declare function validateMelFrequencyRange(fnName: string, fmin: number, fmax: number, sampleRate: number): void;
+//# sourceMappingURL=_feature_validation.d.ts.map

package/dist/_feature_validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_feature_validation.d.ts","sourceRoot":"","sources":["../src/_feature_validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAI7F;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,IAAI,CAaN"}

package/dist/_fft_options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The facade's single FFT-size/hop domain.
+ *
+ * This module is deliberately internal: sibling facade modules import it, but
+ * nothing re-exports it, so it stays out of the package entry point and out of
+ * the C-ABI parity surface (which is defined by the index's re-export closure).
+ */
+/**
+ * Resolves and validates the `nFft` / `hopLength` pair every STFT-backed entry
+ * point takes.
+ *
+ * The core FFT is mixed-radix, so any even size transforms exactly; only the
+ * real one-sided spectrum's `n_fft / 2 + 1` bin layout needs the evenness. A
+ * power-of-two restriction rejects sizes the C ABI and the native CLI accept,
+ * which is what a second copy of this rule used to do: `hpss({ nFft: 1536 })`
+ * worked while `hpssWithResidual({ nFft: 1536 })` threw, with the message
+ * asserting a constraint this project had explicitly written down as untrue.
+ * One implementation, so the two cannot disagree again.
+ */
+export declare function resolveFftOptions(fnName: string, nFft: unknown, hopLength: unknown): {
+    nFft: number;
+    hopLength: number;
+};
+//# sourceMappingURL=_fft_options.d.ts.map

package/dist/_fft_options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_fft_options.d.ts","sourceRoot":"","sources":["../src/_fft_options.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,OAAO,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAQrC"}

package/dist/align_take.d.ts

@@ -0,0 +1,50 @@
+import type { AlignTakeToReferenceRequest, AlignTakeToReferenceResult } from './project_types';
+/**
+ * Aligns one take to a reference timeline and returns the warp anchors that place
+ * the take under it.
+ *
+ * A chromagram is measured for each signal and the two are aligned, then the
+ * alignment is reduced to anchors {@link Project.setWarpMap} accepts: at least
+ * two finite, strictly increasing pairs. The reduction is needed rather than
+ * decorative — an alignment path advances one axis at a time, so the raw
+ * correspondence repeats a coordinate wherever one signal carries more frames
+ * than the other, and those pairs are refused as a warp map.
+ *
+ * **The anchors are oriented for the take's own clip.** `warpSample` is a
+ * position on the REFERENCE timeline and `sourceSample` the corresponding
+ * position in the TAKE, which is the direction a clip whose source is that take
+ * needs. This is why the entry point exists rather than the core alignment
+ * primitive being exposed directly: that one names its arguments the other way
+ * round, so passing the reference as its reference yields the inverse map and
+ * nothing reports it.
+ *
+ * Both signals are read at `sampleRate`; resample first if they differ, since
+ * the alignment does no I/O and no rate conversion.
+ *
+ * {@link AlignTakeToReferenceResult.alignment} is descriptive only — it says how
+ * far the path strayed from a constant rate, so a caller can tell a take the
+ * reference genuinely fits from one it does not, and supplies its own threshold.
+ *
+ * @param request - The two signals, their shared sample rate, and the chroma
+ *   resolution
+ * @returns The anchors and how well the alignment was conditioned
+ * @throws {RangeError} on an empty buffer, a non-finite sample, or a `sampleRate`
+ *   outside `[8000, 384000]`
+ * @throws {SonareError} `InvalidParameter` on a non-positive `hopLength` or
+ *   `binsPerOctave`, on a `binsPerOctave` that is not a multiple of 12, on a
+ *   signal too short to measure two chroma frames, or when the two signals produce
+ *   no pair of distinct anchors — which is what an unalignable pair looks like,
+ *   and is reported rather than answered with a map you cannot use
+ *
+ * @example
+ * ```typescript
+ * const { anchors } = alignTakeToReference({ reference: guide, take, sampleRate });
+ * const project = new Project();
+ * const trackId = project.addTrack({ kind: 'audio' });
+ * const clipId = project.addClip({ trackId, lengthPpq: 64, audio: take, audioSampleRate: sampleRate }); // 16 bars at 4/4, in quarter notes (PPQ)
+ * project.setWarpMap({ id: 1, anchors });
+ * project.setClipWarpRef(clipId, 1);
+ * ```
+ */
+export declare function alignTakeToReference(request: AlignTakeToReferenceRequest): AlignTakeToReferenceResult;
+//# sourceMappingURL=align_take.d.ts.map

package/dist/align_take.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align_take.d.ts","sourceRoot":"","sources":["../src/align_take.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAU5B"}