libspeech 0.3.0__tar.gz → 0.4.0__tar.gz

{libspeech-0.3.0 → libspeech-0.4.0}/.github/workflows/cmake.yml

@@ -58,6 +58,20 @@ jobs:
     steps:
     - name: Checkout repository
       uses: actions/checkout@v6
+      with:
+        submodules: true
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.11"
+        cache: "pip"
+
+    # httpp: needed at CMake-configure time (see build-and-test above). The rest are the docs
+    # tools: Sphinx (Python reference), doxygen-awesome-css (C++ theme), markdown-it-py (pages).
+    # The Python reference imports the package built in the build tree, so this is a full build.
+    - name: Install python dependencies
+      run: pip install httpp sphinx doxygen-awesome-css markdown-it-py
 
     - name: Install Doxygen + graphviz
       run: |
@@ -67,7 +81,9 @@ jobs:
     - name: Configure CMake
       run: |
         cmake -B build \
-          -DBUILD_MODELS=OFF \
+          -DCMAKE_BUILD_TYPE=Release \
+          -DBUILD_MODELS=ON \
+          -DBUILD_PYTHON=ON \
           -DBUILD_TESTS=OFF \
           -DBUILD_DOCS=ON
 
@@ -78,7 +94,7 @@ jobs:
       uses: actions/upload-artifact@v7
       with:
         name: cmake-documentation
-        path: build/docs/out/html
+        path: build/docs/out
         retention-days: 5
 
   build-coverage:
@@ -126,6 +142,12 @@ jobs:
     - name: Generate coverage report
       run: cmake --build build --target speech_coverage
 
+    # Heavy end-to-end Denoiser test (downloads the ONNX model, ~1 GB RAM). It carries the
+    # `models` pytest marker, so the normal pytest runs (wheels.yml / cibuildwheel, the coverage
+    # run above) skip it; this is the one place it runs (pytest -m models).
+    - name: Run model tests (pytest -m models)
+      run: cmake --build build --target speech_test_python_models_e2e
+
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v5
       with:

{libspeech-0.3.0 → libspeech-0.4.0}/.github/workflows/wheels.yml

@@ -57,7 +57,7 @@ jobs:
         submodules: true
 
     - name: Build wheels
-      uses: pypa/cibuildwheel@v3.4.1
+      uses: pypa/cibuildwheel@v4.2.0
       env:
         # ONNX Runtime's own v1.21.0 release notes state outright: "All
         # macOS packages now require macOS version >= 13.3." Without this,
@@ -85,6 +85,8 @@ jobs:
         # cp38 is excluded: httpp (a build-time dependency, see above) only
         # ships wheels from cp39-abi3 up on PyPI, not cp38 -- building a
         # cp38 wheel here would require httpp built from source instead.
+        # (cibuildwheel 4.2 builds CPython 3.15 by default; this explicit list keeps the
+        # matrix at 3.9-3.12 -- the cp312 wheel is abi3, so it also serves 3.13 and newer.)
         CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-*"
         # Per-Python-version env var overrides (SKBUILD_WHEEL_PY_API=cp312
         # for the cp312 build only, so scikit-build-core tags it as a

libspeech-0.4.0/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to libspeech. The version lives in `include/libspeech/version.h`.
+This file starts at 0.3.1; older history is in `git log`.
+
+## Unreleased
+
+## 0.4.0 (2026-10-17)
+
+Needs **httpp 0.7.x** (`httpp>=0.7,<0.8`, in `pyproject.toml`): the download lock and the SHA-256 functions used
+here are not in 0.6.x, and httpp's API is still changing, so the range is deliberately narrow.
+
+### Breaking
+- **C++ API renamed to snake_case, STL style** (types, enumerators, functions, methods,
+  constants). A few names changed beyond case because a type cannot share a method's name:
+  `STFT::stft` → `stft::compute`, `Resample::resample` → `resample::process`,
+  `Spectrogram` → `complex_spectrogram`, `DctII` → `dct_ii_plan`,
+  `Denoiser::Create` → `denoiser::create`. Full old → new table: `docs/api-renames.md`.
+  Python class names (`libspeech.STFT`, ...) are unchanged.
+- **`window_type`** (`enum class`, `include/libspeech/dsp/window_type.h`) replaces AudioFlux's
+  `WindowType`/`Window_*` in the public headers; no AudioFlux header is public any more.
+- **`denoiser` is single-inheritance** (pimpl backends `facebook_denoiser`, `speechbrain_denoiser`);
+  `process()`/`close()` are non-virtual in the base.
+- **Default log level is now `warning`** (it used to print everything). Use
+  `libspeech.set_log_level("debug")`, `speech::utils::set_log_level` or `LIBSPEECH_LOG`.
+- **`istft` with an invalid `method` raises** (only 0/1, or `"weighted"`/`"plain"` in Python).
+- **`nanobind>=2.0.0`** is required to build the Python bindings.
+
+### Changed
+- **License is now Apache-2.0** (was declared as MIT in the README/pyproject, while the `LICENSE` file actually held
+  pybind11's BSD-3 text). `LICENSE` is the standard Apache-2.0 text, `NOTICE` names the third-party code and says
+  that the downloaded models keep their own licenses. Copies of libspeech already distributed under MIT stay MIT.
+
+### Added
+- **Verified model downloads.** A model now always comes with two small files next to it, and all three
+  are downloaded: `<model>.onnx.sha256` (one line, `<sha256>  <file name>`, as `sha256sum` writes it) and
+  `<model>.onnx.readme` (what the model is, who made it, license, provenance). The checksum file is fetched
+  **first** and must be exactly that one line (an HTML error page is rejected); then the readme (so a missing
+  one fails before the big download); then the model, which httpp checks against the checksum and deletes if it
+  does not match. The checksum and readme are installed next to the model only after it arrived and matched,
+  so a failed or interrupted download no longer leaves a broken file behind that later calls would trust
+  (`download_file` skipped any existing file). A cached model is hashed on every load and downloaded again if
+  it does not match; a model cached by an older version just gets its two files. A bare model name (the
+  `models` release) must have all three; an explicit URL may lack the sidecar files and is then used unverified
+  with a warning (a malformed checksum file is still an error).
+- **Several processes, one download.** The lock is httpp's: `httpp::download` always takes `<file>.lock/`,
+  whose `alive` file the downloading process keeps rewriting. Another process (or thread) that wants the same
+  model waits and then finds the finished file instead of downloading it again; a lock that stops being
+  updated belongs to a dead process and is taken over. A download that was killed is resumed from its `.part`
+  file and verified against the checksum. The checksum and readme are fetched under per-download temporary
+  names (`*.<tag>.new`), so a failed refresh (`ignore_cache`) leaves the old cache as it was. A cache hit
+  never takes the lock.
+- **`ignore_cache`**: `Denoiser(..., ignore_cache=True)`, `SileroVad(..., ignore_cache=True)`,
+  `libspeech.fetch_model(..., ignore_cache=True)`; C++ `denoiser::create(..., ignore_cache)`, the model
+  constructors and `fetch_options::ignore_cache`. Downloads everything again; if that fails the old cache is untouched.
+- **Readme API**: `Denoiser.readme()`, `SileroVad.readme()`, `libspeech.model_readme(name)`; C++
+  `denoiser::readme()`, `base_model::readme()`, `speech::models::model_readme(name)`. Also `model_path`
+  and `sha256` on loaded models, `libspeech.fetch_model(name)` (returns the verified path without loading
+  the model) and C++ `speech::models::fetch_model` / `fetch_options` / `parse_checksum`.
+- **SHA-256**: `libspeech.sha256(bytes)`, `libspeech.sha256_file(path)`, C++ `speech::utils::sha256_hex` /
+  `sha256_file` (chunked, any file size). The hashing itself is httpp's (`httpp::sha256_hex`), which also
+  verifies the downloads; no SHA-256 code is vendored.
+- **`data/models.csv`**: every model in the `models` release (name, file, backend, sample rate, size, sha256,
+  license, `commercial_use`, source, notes). A test checks it against the release's `.sha256` files.
+- Python `libspeech.stft(...)` / `libspeech.istft(...)` (librosa style, NumPy in/out), and
+  `STFT.stft_complex`, `STFT.istft`, `FFT.fft`/`FFT.ifft` returning `complex64`.
+- C++ `istft` (inverse real FFT, one-sided or full input, AudioFlux-compatible normalisation),
+  `fft::forward_into/inverse_into/dct_into/idct_into`, `span<T>`/`frame_view<T>` and complex
+  views (`as_complex`, `split_complex_span`, `complex_spectrogram::frames()`).
+- Real-FFT fast path for real input up to 2^17 points.
+- `Denoiser`: `close()`, `closed`, context manager, `sample_rate`, `num_threads`
+  (default 1, 0 = automatic), NumPy overload, GIL released while running, `Denoiser("facebook")`
+  with the default model, `denoiser(x)`.
+- Logger with a public API (`set_log_level`, `get_log_level`, `LIBSPEECH_LOG`), output
+  `time [level] (tag) message`; it no longer takes over `std::clog`.
+- Type stubs: `py.typed` and one `.pyi` per compiled module, generated with
+  `python -m nanobind.stubgen` in `src/bindings/python/CMakeLists.txt` and installed with the
+  wheel.
+- **`resample_quality`** (`best` default, `high`, `medium`, `fast`; Python
+  `Resample(src, dst, "medium")`) trades passband width and alias rejection for speed. Python,
+  44.1 → 16 kHz, one core, min of 60 runs, 10 s / 60 s of audio, in ms: best 2.5 / 15.4,
+  high 1.9 / 11.9, medium 1.35 / 8.2, fast 0.77 / 4.7, against librosa 2.3 / 13.5, soxr MQ
+  2.0 / 11.7, soxr LQ 1.8 / 10.5. Quality, measured with pure tones: aliases rejected by
+  > 150 dB (best), 135 (high), 124 (medium), 107 (fast) at 12 kHz; passband loss at 7 kHz
+  0.00 / 0.00 / 0.07 / 2.3 dB. soxr keeps a flatter passband close to 8 kHz (-0.02 dB at
+  7.4 kHz against -1.1 dB for `best` and -2.0 dB for `medium`), so the levels are not an
+  equal-quality comparison with soxr.
+- **Denoiser backends `gtcrn` and `dpdfnet`** (`gtcrn_denoiser`, `dpdfnet_denoiser`;
+  `Denoiser("gtcrn")`, `Denoiser("dpdfnet", model="dpdfnet4")`). Small streaming models that work
+  on the STFT one frame at a time and carry their state, so any input length works. GTCRN (0.5 MB,
+  16 kHz) and DPDFNet (`dpdfnet_baseline`, `dpdfnet2` (default), `dpdfnet4`, `dpdfnet8` at 16 kHz,
+  `dpdfnet2_48khz_hr` at 48 kHz; pass `sample_rate=48000` for that one) are Ceva's / the GTCRN
+  authors' public ONNX exports, hosted in the `models` release (each with a `.readme` and `.sha256`)
+  and downloaded on first use. Checked against sherpa-onnx 1.13.8 on its
+  9.8 s sample clip: max |difference| 1.5e-7 (float precision) for GTCRN and the four 16 kHz
+  DPDFNet models, 1.4e-5 for the 48 kHz one. Two deliberate differences: the output always has the
+  input's length (sherpa-onnx drops the last `len % hop` samples), and DPDFNet's 4-hop latency is
+  compensated by flushing the model with silence, so its last 40 ms are real output instead of
+  zeros. Single thread, 9.8 s of audio (not compared to anything else): GTCRN 0.8 s,
+  `dpdfnet_baseline` 1.4 s, `dpdfnet2` 2.9 s, `dpdfnet4` 4.0 s, `dpdfnet8` 6.3 s. DPDFNet's
+  optional attenuation limit is not exposed.
+- `libspeech.available_providers()` and `libspeech.is_cuda_available()` (C++:
+  `speech::models::available_providers/is_cuda_available`): the ONNX Runtime providers of the loaded
+  build, and whether CUDA can really be created. Models still run on the CPU; selecting a provider
+  for a session is not implemented yet.
+- Test marker `models` (real-model tests, run by `cmake.yml` only: `pytest -m models`).
+- `benchmarks/profile/`: profiling README and C++ timing scripts for DCT/FFT (2026-10-05).
+- DSP loops link `OpenMP_CXX`; the README documents the SIMD backends and the architecture-agnostic
+  vectorization logic (2026-10-02).
+
+### Changed
+- **httpp 0.7.x is required** (see above); libspeech no longer has its own download lock or SHA-256 code.
+- Resample output is numerically more accurate than before (up to ~6e-3 different from the
+  old kernel). The default (`best`) is still ~8–18% slower than librosa/soxr on one core; use
+  `resample_quality` to trade accuracy for speed.
+- **Documentation site rebuilt like ctoon's**: `-DBUILD_DOCS=ON` + `--target speech_docs` builds the
+  C++ reference (Doxygen, with doxygen-awesome-css), the Python reference (Sphinx, from the package
+  staged in the build tree), a route index (`docs/supported_langs.json`) and Markdown pages
+  (changelog, C++ API renames, contributing) into `<build>/docs/out/`; `speech_docs_cpp` and
+  `speech_docs_python` build one part. Needs `pip install sphinx doxygen-awesome-css markdown-it-py`.
+- The Python bindings' CMake code moved from the top-level `CMakeLists.txt` to
+  `src/bindings/python/CMakeLists.txt`; `cmake/generate_stubs.cmake` is gone.
+- Wheels: cibuildwheel 3.4.1 → 4.2.0 with explicit CPython version constraints; delvewheel repair is
+  disabled on Windows (it caused a missing `speech.dll`); the test dependencies exclude Intel macOS and
+  Python 3.15+ (numba → llvmlite wheel availability).
+- The Python bindings bake the runtime library file names (ONNX Runtime, httpp) into `_about` at build time
+  instead of guessing them at import time (which failed because `dlopen` ignores the RPATH).
+- Benchmarks import NumPy in isolation, so the timings are fair.
+
+### Fixed
+- **Windows: `SPEECH_LOG(ERROR)` messages were never printed.** `<windows.h>` defines `ERROR` as 0,
+  so the macro mapped it to the trace level. The severity is now pasted into a name
+  (`SPEECH_LOG_LEVEL_ERROR`) instead of being macro-expanded. Regression test on every platform
+  (`log.error_severity_is_not_hijacked_by_a_windows_style_error_macro`).
+- **Windows wheel build: stub generation failed** with `No module named 'libspeech._about'`.
+  Multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) append `Release/` to a plain
+  `LIBRARY_OUTPUT_DIRECTORY`, so the staged package was missing its modules; the staging directory is
+  now a generator expression, which switches that suffix off.
+- `audio_callback` initialised a local `output` from itself (it shadowed the `output` parameter),
+  which is undefined behaviour (MSVC C4700).
+- `Denoiser.create(...)` failed with "Unable to convert function return value".
+- Destroying a `Denoiser` aborted the process (`free(): invalid pointer`, multiple-inheritance
+  pointer offset).
+- **Facebook denoiser silently dropped everything after ~32 s of input** (the exported graph
+  works on a fixed window); longer input is now processed in overlapping, cross-faded windows
+  and the output has the input's length.
+- **The Facebook models (`facebook-denoiser-dns48.onnx`, `-dns64.onnx`, `-master64.onnx`) take 4 to 7 s per call whatever the input length.** The graph
+  was traced with a 512000-sample example, so its `valid_length` was baked in as the constant
+  512085 and every input was zero-padded to ~32 s. A re-published model computes `valid_length`
+  from the input length inside the graph (same weights; 38 nodes replace the constant), measured
+  on one core, dns64: 0.1 s → 0.03 s, 1 s → 0.23 s, 5 s → 1.0 s, 32 s → ~7 s (dns48 1 s → 0.14 s,
+  master64 1 s → 0.17 s). All three had the same baked constant and are patched the same way. Output equals the old
+  model for 32 s inputs and differs by ~1e-3 (peak, at the tail) for 1 to 5 s inputs; not
+  compared against the PyTorch reference or on real speech. Existing installs keep the old file
+  in `~/.libspeech/` until it is deleted.
+- `tests/python/test_logging.py` no longer relies on AudioFlux rejecting `FFT(99)` to produce an
+  error line (it failed on Windows CI).
+- The real-FFT STFT path takes its analysis window from `window_calFFTWindow()`, the same function the
+  vendored AudioFlux uses, instead of reading it out of the opaque `stftObj_`; regression test for every
+  supported window type (`tests/dsp/test_fast_paths.cpp`).
+- Python binding memory leak of `Denoiser` (the C++ object is held through a `shared_ptr` now); `close()`
+  frees the model's memory explicitly.
+
+### Known issues
+- Not run on Windows/macOS/ARM, or with several cores, while this version was written (Linux, x86-64 only);
+  the new download code has never been compiled with MSVC. Check CI.
+- GPU is not used: models run on the CPU (`available_providers()` / `is_cuda_available()` only report).
+- The Facebook denoiser models are licensed CC-BY-NC-4.0 (non-commercial); `data/models.csv` says so
+  (`commercial_use=no`), and so does the model's `.readme`.
+- A process killed during a download leaves its `*.new` files in the cache directory (harmless, not reused).
+  If two processes take over the same dead lock at the same moment they can write the same `.part` file;
+  the checksum catches the damage and the download fails instead of installing it.
+- `STFT` outside n_fft 16..8192 uses the AudioFlux fallback, which is mutex-locked; `FFT` is not
+  thread-safe.
+
+## 0.3.1 (2026-10-01; the version was bumped, no git tag)
+
+### Added
+- Python benchmark suite (`benchmarks/`) comparing libspeech with librosa, audioflux, scipy and soundfile for
+  time, memory and install size, with a standalone HTML report (`report/`); the CMake targets skip Python when
+  there is no interpreter.
+- `benchmarks/README.md` documents the measured results and the optimized paths: flat spectrogram, block-wise
+  MFCC with sparse mel filters, AVX2+FMA resampling dispatch, memory-efficient `load`/`to_numpy`.
+
+### Changed
+- README: table of contents, dependency text now names `httpp` (not httplib + Mbed TLS), the STFT/OpenMP
+  benchmark explanation separates single-core from multi-core results; the benchmarking section was removed
+  from the README (the raw data is kept locally).
+
+## 0.3.0 (2026-09-29)
+
+### Added
+- Build options for documentation and coverage (`-DBUILD_DOCS=ON`, `-DBUILD_COVERAGE=ON`); coverage of all
+  components is merged into one `speech_coverage_total` report; CI builds with `BUILD_PYTHON=ON` so the tests
+  are installed and reported.
+
+### Removed
+- The `dr_libs` submodule: `miniaudio` already embeds `dr_wav`, `dr_mp3` and `dr_flac`.
+- The command-line tool, and the unused Python files `libspeech/core.py` and `libspeech/__main__.py`
+  (0 % coverage, leftovers of an earlier split).
+
+## 0.2.0 (2026-09-27)
+
+### Fixed
+- The CPython 3.12 wheel got the wrong ABI tag: the `CIBW_ENVIRONMENT_CP312` variable did nothing
+  (cibuildwheel ignores Python-version suffixes) and was removed; `tool.cibuildwheel.overrides` now forces
+  `cp312-abi3`.
+- Clang's `-Wc23-extensions` warning caused by the vendored miniaudio is silenced.
+
+## 0.1.1 (2026-09-26)
+
+### Fixed
+- Linux wheels ship and load ONNX Runtime under its SONAME (`libonnxruntime.so.1`) instead of the
+  fully-versioned file name; CMake's `install()` followed the symlinks and shipped duplicate ~20 MB copies.
+
+## 0.1.0 (2026-09-26)
+
+First tagged release. Everything from 2026-08-27 up to the first release:
+
+### Added
+- `speech::dsp` as a standalone static library (`speech_dsp`), a direct DCT-II implementation, and an STFT
+  of its own; AudioFlux is no longer a submodule (a subset of its C sources lives in `src/third_party/`,
+  moved there from `src/vendor/`); `fftObj_idct()`'s input mutation is documented; `resampleObj_setSamplate`
+  handles identity resamples.
+- `BUILD_MODELS` (replaces `SPEECH_DSP_ONLY`) to build the DSP layer alone, and a unit-test build option.
+- Python bindings for the speech models (`bind_models`), Python tests, version handling
+  (`include/libspeech/version.h`), `CONTRIBUTING.md`, a standalone benchmarking project for STFT.
+- Model downloads use `httpp` (HTTP client with a progress bar), replacing httplib, Mbed TLS and indicators.
+- CI: a matrix build for CMake and an orchestrator for the wheels and the release.
+
+### Fixed
+- Windows/MSVC: compilation (`NOMINMAX`, `M_PI`, `setenv`), AudioFlux and ONNX Runtime compatibility,
+  public API symbols exported from the DLL, static library members forced into `speech.dll`, ONNX Runtime and
+  httpp DLLs copied beside executables, `speech.dll` installed in the wheel, DLL load failures diagnosed.
+- macOS: arm64 suffix for ONNX Runtime, universal2 ONNX Runtime and dylib names, deployment target 13.3,
+  wheel repair.
+- Wheels: `$ORIGIN` RPATH and the ONNX Runtime SONAME shipped; musllinux and win32 wheels are skipped (ONNX
+  Runtime is glibc-only); the runtime library file names are baked into `_about`; httpp is required
+  unconditionally and loaded from pip instead of being bundled; the `pefile` dependency was replaced by an
+  inline PE import-table parser and then removed; Python bindings consolidated with explicit install rules for
+  the nested package.
+
+## Before 0.1.0 (2025-03-14 to 2025-03-31)
+
+The first prototype, in the order of the commits:
+- Audio I/O with miniaudio and dr_libs, a `speech` namespace for `Audio`, a fixed `play()`, Python audio
+  bindings, `seconds`, a format function and `operator=`.
+- ONNX Runtime support with a base model class, model download with a progress bar (indicators, then a
+  generated progress-bar source), and Silero VAD (fixed on 2025-03-17).
+- AudioFlux (first as a submodule, then static) and `resample`; glog replaced by AixLog.
+- A GitHub workflow, a different way to install onnxruntime for CPython, a simple HTML test, README and the
+  libspeech logo (many iterations).

{libspeech-0.3.0 → libspeech-0.4.0}/CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.19)
 option(BUILD_PYTHON "export python module" off)
 option(BUILD_TESTS "build unit tests (speech::dsp only, no ONNXRuntime/httpp needed)" on)
 option(BUILD_MODELS "build speech::models + the speech library (needs ONNXRuntime download + the httpp package); off configures speech::dsp + tests only" on)
-option(BUILD_DOCS "build the speech_docs Doxygen target (docs/)" off)
+option(BUILD_DOCS "build the speech_docs targets: Doxygen C++ docs, Sphinx Python docs, index and pages (docs/)" off)
 option(BUILD_COVERAGE "instrument speech_dsp with --coverage and enable the speech_coverage_cpp_dsp target (needs lcov/genhtml); OFF by default so a normal build isn't broken just because lcov happens to be installed" off)
 
 set(CMAKE_C_STANDARD 99 CACHE STRING "C version selection")
@@ -98,6 +98,11 @@ target_include_directories(speech_dsp
         PRIVATE src/third_party/audioflux/src   # private AudioFlux headers (fft_algorithm.h, stft_algorithm.h, ...)
 )
 target_link_libraries(speech_dsp PUBLIC audioflux)
+# The STFT/MFCC frame loops carry `#pragma omp`; cmake/AudioFlux.cmake only links the
+# C flavour of OpenMP (for AudioFlux's own C code), so the C++ flavour is linked here.
+if(LIBSPEECH_ENABLE_OPENMP AND OpenMP_CXX_FOUND)
+    target_link_libraries(speech_dsp PUBLIC OpenMP::OpenMP_CXX)
+endif()
 
 # See include/libspeech/export.h -- this makes SPEECH_API expand to
 # __declspec(dllexport) for FFT/STFT/MFCC/Resample when compiled here (as
@@ -110,15 +115,15 @@ if(BUILD_TESTS)
     add_subdirectory(tests)
 endif()
 
-if(BUILD_DOCS)
-    add_subdirectory(docs)
-endif()
-
 if(NOT BUILD_MODELS)
     message(STATUS "BUILD_MODELS=off: configuring speech::dsp + tests only, skipping ONNXRuntime/models/audio I/O.")
     if(BUILD_TESTS)
         speech_coverage_finalize()
     endif()
+    # C++ docs only: the Python docs need the bindings, which this configuration skips
+    if(BUILD_DOCS)
+        add_subdirectory(docs)
+    endif()
     return()
 endif()
 
@@ -338,7 +343,7 @@ elseif(BUILD_PYTHON)
         # to support a much older pip.
         execute_process(
                 COMMAND "${Python3_EXECUTABLE}" -m pip install --break-system-packages
-                nanobind ninja pytest-xdist pip-tools # build requirements
+                nanobind ninja numpy pytest-xdist pip-tools # build + test requirements
                 OUTPUT_QUIET COMMAND_ERROR_IS_FATAL ANY
                 WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
         )
@@ -369,230 +374,12 @@ endif()
 
 
 if(DEFINED PYTHON_PROJECT_NAME)
-    find_package(Python 3.8
-            REQUIRED COMPONENTS Interpreter Development.Module
-            OPTIONAL_COMPONENTS Development.SABIModule)
-    find_package(nanobind CONFIG REQUIRED)
-
-    set(NB_MODULE _about)
-    nanobind_add_module(${NB_MODULE} STABLE_ABI NB_STATIC ${PROJECT_SOURCE_DIR}/src/bindings/python/about.cpp)
-    libspeech_set_origin_rpath(${NB_MODULE})
-
-    # __init__.py's cdll.LoadLibrary() calls need the *exact* on-disk
-    # filename of each preloaded runtime library (speech itself, httpp,
-    # ONNXRuntime) -- these vary by platform (libspeech.so / speech.dll /
-    # libspeech.dylib, etc.) and, for ONNXRuntime, by version too. RPATH
-    # (see libspeech_set_origin_rpath above) can't help with any of this:
-    # it only lets the OS loader resolve a DT_NEEDED entry when one
-    # already-loaded .so pulls in another at normal link time. ctypes'
-    # cdll.LoadLibrary() is a direct, explicit dlopen()/LoadLibrary() call
-    # from Python itself, entirely bypassing that mechanism -- it needs the
-    # literal filename handed to it, RPATH or not.
-    #
-    # Rather than have __init__.py guess that filename per-platform (with
-    # if/else branches or fragile globs), compute it once, here, where
-    # CMake already knows it precisely, and bake it into _about (already a
-    # tiny, dependency-free nanobind module that __init__.py imports first,
-    # for __version__) as extra module attributes -- alongside __version__,
-    # the same way this file already bakes VERSION_INFO in below.
-    # $<TARGET_FILE_NAME:...> is a generator expression, resolved once CMake
-    # knows the real output name of each target.
-    # On Linux, ship (and load) the library under its SONAME
-    # (libonnxruntime.so.1) rather than the fully-versioned filename
-    # (libonnxruntime.so.1.21.0): both names used to be installed as full
-    # ~20MB copies (the SONAME file is a symlink on the upstream release
-    # tarball, but CMake's install(FILES ...)/file(COPY ...) dereference
-    # symlinks, and it turns out the wheel-building step also flattens an
-    # install-time symlink back into a second real copy when zipping -- so
-    # there is no way to keep both names *and* avoid shipping the bytes
-    # twice). Since the SONAME is the one name every consumer .so's
-    # DT_NEEDED entry actually requires at runtime, standardize the
-    # explicit ctypes preload in __init__.py on that same name too and
-    # stop installing the fully-versioned name altogether -- one file,
-    # one name, used both places. Windows/macOS have no such SONAME split
-    # (see cmake/ONNXRuntime.cmake) so they keep using ONNXRUNTIME_LIB_FILE.
-    if(ONNXRUNTIME_SONAME_FILE)
-        get_filename_component(_ONNXRUNTIME_LIB_FILENAME "${ONNXRUNTIME_SONAME_FILE}" NAME)
-    else()
-        get_filename_component(_ONNXRUNTIME_LIB_FILENAME "${ONNXRUNTIME_LIB_FILE}" NAME)
-    endif()
-    target_compile_definitions(${NB_MODULE} PRIVATE
-            VERSION_INFO=${PROJECT_VERSION}
-            NB_MODULE_NAME=${NB_MODULE}
-            LIB_PATH=$<TARGET_FILE_NAME:speech>
-            HTTPP_LIB_PATH=$<TARGET_FILE_NAME:httpp::httpp_core>
-            ONNXRUNTIME_LIB_PATH=${_ONNXRUNTIME_LIB_FILENAME})
-
-    # CONFIGURE_DEPENDS: best-effort auto-detection of new bind_*.cpp files
-    # without a manual reconfigure. This is NOT guaranteed by CMake to work
-    # on every generator/environment (e.g. observed unreliable with the Unix
-    # Makefiles generator in some setups) -- if a newly added binding module
-    # doesn't show up after `cmake --build`, run `cmake ..` (or delete and
-    # recreate the build directory) once to force a fresh configure.
-    file(GLOB PYTHON_BIND_MODULES_PATH CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/src/bindings/python/bind_*.cpp)
-    set(PYTHON_BIND_MODULES "${NB_MODULE}")
-    foreach(NB_MODULE_SOURCE IN LISTS PYTHON_BIND_MODULES_PATH)
-        get_filename_component(NB_MODULE ${NB_MODULE_SOURCE} NAME_WE)
-        string(REGEX REPLACE "bind_(.*)" "speech_\\1_py" NB_MODULE ${NB_MODULE})
-        list(APPEND PYTHON_BIND_MODULES ${NB_MODULE})
-
-        message(STATUS "Found module: ${NB_MODULE}")
-
-        # We are now ready to compile the actual extension module
-        nanobind_add_module(
-                # Name of the extension
-                ${NB_MODULE}
-
-                # Target the stable ABI for Python 3.12+, which reduces
-                # the number of binary wheels that must be built. This
-                # does nothing on older Python versions
-                STABLE_ABI
-
-                # Build libnanobind statically and merge it into the
-                # extension (which itself remains a shared library)
-                #
-                # If your project builds multiple extensions, you can
-                # replace this flag by NB_SHARED to conserve space by
-                # reusing a shared libnanobind across libraries
-                NB_STATIC
-
-                # Source code goes here -- one file per module (ctoon's
-                # convention: src/bindings/python/bind_X.cpp -> speech_X_py),
-                # unlike _about above which is a single nanobind_add_module
-                # call named directly rather than discovered by this glob.
-                ${NB_MODULE_SOURCE}
-        )
+    add_subdirectory(${PROJECT_SOURCE_DIR}/src/bindings/python)
+endif()
 
-        target_include_directories(${NB_MODULE} PRIVATE include src)
-        target_compile_definitions(${NB_MODULE} PRIVATE NB_MODULE_NAME=${NB_MODULE})
-        target_link_libraries(${NB_MODULE} PRIVATE speech::speech)
-        libspeech_set_origin_rpath(${NB_MODULE})
-    endforeach()
-
-    if(DEFINED SKBUILD)
-        # `speech` (line ~221: add_library(speech SHARED ...)) is a real
-        # SHARED library, not a MODULE (unlike ${PYTHON_BIND_MODULES}, the
-        # nanobind extension .pyd/.so files, which install fine under
-        # LIBRARY alone on every platform). CMake's install(TARGETS) docs
-        # spell out the platform split this causes: "For DLL platforms
-        # (Windows) the DLL part of a shared library is treated as a
-        # RUNTIME target, while the corresponding import library is
-        # treated as an ARCHIVE target. On non-DLL platforms shared
-        # libraries are treated as LIBRARY targets." LIBRARY DESTINATION
-        # alone is therefore complete on Linux/macOS but, on Windows,
-        # speech.dll itself belongs to a target kind (RUNTIME) this rule
-        # never mentions -- so it silently isn't installed at all: no
-        # error, no warning, just a wheel with every OTHER file in place
-        # and speech.dll simply missing, which is indistinguishable at
-        # runtime from "installed but failed to load one of its
-        # dependencies" (identical ctypes error either way) until you
-        # actually go looking for the file.
-        install (TARGETS ${PYTHON_BIND_MODULES} speech
-                CONFIGURATIONS Release
-                LIBRARY DESTINATION ${PYTHON_PROJECT_NAME}
-                RUNTIME DESTINATION ${PYTHON_PROJECT_NAME})
-
-        # The pure-Python files (currently just __init__.py) need
-        # their own explicit install rule -- scikit-build-core's automatic
-        # Python-package discovery only looks for an immediate src/<name>
-        # layout, so now that the package lives nested under
-        # src/bindings/python/${PROJECT_NAME} (ctoon's own convention,
-        # matched here on request), it no longer finds it on its own: the
-        # compiled extensions above still land in the wheel fine (that
-        # goes through install(TARGETS), unrelated to this discovery), but
-        # without this, the wheel would ship no __init__.py at all --
-        # `import libspeech` would "succeed" only as an empty implicit
-        # namespace package, silently missing everything real. Same
-        # pattern ctoon itself uses for exactly this reason (see its
-        # src/bindings/python/CMakeLists.txt).
-        install(DIRECTORY ${PROJECT_SOURCE_DIR}/src/bindings/python/${PROJECT_NAME}/
-                DESTINATION ${SKBUILD_PROJECT_NAME}
-                FILES_MATCHING PATTERN "*.py")
-
-        # ONNXRuntime ships as a shared library that the compiled extension
-        # modules dlopen symbols from at import time (see __init__.py's
-        # cdll.LoadLibrary() calls), so it has to be copied into the wheel
-        # next to those extensions rather than relied upon via RPATH:
-        # RPATH would only point back at wherever it got downloaded to on
-        # the *build* machine, which has no reason to exist on whatever
-        # machine later installs this wheel.
-        #
-        # httpp is NOT bundled here -- __init__.py loads it from the
-        # separately pip-installed httpp package instead (see __init__.py).
-        #
-        # ONNXRUNTIME_SONAME_FILE (see cmake/ONNXRuntime.cmake) is the name
-        # every compiled .so's DT_NEEDED entry actually requires at
-        # runtime (libonnxruntime.so.1 on Linux), not the fully-versioned
-        # ONNXRUNTIME_LIB_FILE one -- without a file by that exact name,
-        # `auditwheel repair` fails to find/bundle it at all.
-        #
-        # On disk (in the upstream release tarball) that name is a
-        # symlink to ONNXRUNTIME_LIB_FILE, which is why it used to look
-        # free to ship both: but CMake's install(FILES ...) dereferences
-        # symlinks, AND the wheel-building step separately flattens an
-        # install-time symlink back into a real copy when zipping -- so
-        # shipping *both* names always costs a full second ~20MB copy no
-        # matter which way the symlink is recreated. Since the SONAME is
-        # the only name anything actually needs to dlopen/link against at
-        # runtime (see the ONNXRUNTIME_LIB_PATH comment above), install
-        # the real bytes under that name ONLY and drop the fully-versioned
-        # name from the wheel entirely -- one ~20MB file instead of two.
-        # ONNXRUNTIME_PROVIDERS_SHARED_FILE (Windows only) is the companion
-        # onnxruntime_providers_shared.dll upstream ships alongside
-        # onnxruntime.dll -- see cmake/ONNXRuntime.cmake for why.
-        if(ONNXRUNTIME_SONAME_FILE)
-            get_filename_component(_ONNXRUNTIME_SONAME_FILENAME "${ONNXRUNTIME_SONAME_FILE}" NAME)
-            # RENAME so only one copy of the (large) file is ever written
-            # -- under the SONAME, not the fully-versioned name.
-            install(FILES "${ONNXRUNTIME_LIB_FILE}"
-                    DESTINATION ${SKBUILD_PROJECT_NAME}
-                    RENAME "${_ONNXRUNTIME_SONAME_FILENAME}")
-        else()
-            install(FILES "${ONNXRUNTIME_LIB_FILE}"
-                    DESTINATION ${SKBUILD_PROJECT_NAME})
-        endif()
-        if(ONNXRUNTIME_PROVIDERS_SHARED_FILE)
-            install(FILES "${ONNXRUNTIME_PROVIDERS_SHARED_FILE}"
-                    DESTINATION ${SKBUILD_PROJECT_NAME})
-        endif()
-    else()
-        file(COPY ${PROJECT_SOURCE_DIR}/src/bindings/python/${PROJECT_NAME} DESTINATION ${PYTHON_PROJECT_NAME})
-        if(ONNXRUNTIME_SONAME_FILE)
-            # Same fix as the scikit-build install(FILES ...) branch above:
-            # ship the real bytes under the SONAME only (one ~20MB file,
-            # not the fully-versioned name too), since that's the only
-            # name anything actually dlopens/links against at runtime.
-            get_filename_component(_ONNXRUNTIME_SONAME_FILENAME "${ONNXRUNTIME_SONAME_FILE}" NAME)
-            file(COPY_FILE "${ONNXRUNTIME_LIB_FILE}"
-                 "${PYTHON_PROJECT_NAME}/${PROJECT_NAME}/${_ONNXRUNTIME_SONAME_FILENAME}")
-        else()
-            file(COPY ${ONNXRUNTIME_LIB_FILE} DESTINATION ${PYTHON_PROJECT_NAME}/${PROJECT_NAME})
-        endif()
-        if(ONNXRUNTIME_PROVIDERS_SHARED_FILE)
-            file(COPY ${ONNXRUNTIME_PROVIDERS_SHARED_FILE} DESTINATION ${PYTHON_PROJECT_NAME}/${PROJECT_NAME})
-        endif()
-
-        foreach(_core IN LISTS PYTHON_BIND_MODULES)
-            set_target_properties(${_core} PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${PYTHON_PROJECT_NAME}/${PROJECT_NAME})
-        endforeach()
-
-        # speech itself must land inside the package directory too --
-        # __init__.py's `cdll.LoadLibrary(_here / LIB_PATH)` looks for it
-        # right next to _audio.abi3.so/_about.abi3.so, not in the
-        # top-level build directory (where it would otherwise default to).
-        # Both output-directory properties are needed for the same DLL-
-        # platform-split reason as the SKBUILD install(TARGETS) rule above:
-        # LIBRARY_OUTPUT_DIRECTORY alone places the .dll correctly on
-        # Linux/macOS but is silently ignored for it on Windows, where a
-        # SHARED library's DLL is governed by RUNTIME_OUTPUT_DIRECTORY
-        # instead (LIBRARY_OUTPUT_DIRECTORY only affects its .lib import
-        # library there) -- so on Windows the .dll would otherwise default
-        # to landing directly under ${PYTHON_PROJECT_NAME} instead of
-        # ${PYTHON_PROJECT_NAME}/${PROJECT_NAME}, right alongside it.
-        set_target_properties(speech PROPERTIES
-                LIBRARY_OUTPUT_DIRECTORY ${PYTHON_PROJECT_NAME}/${PROJECT_NAME}
-                RUNTIME_OUTPUT_DIRECTORY ${PYTHON_PROJECT_NAME}/${PROJECT_NAME})
-    endif()
+# After the Python bindings: the Sphinx docs import the package staged in the build tree
+if(BUILD_DOCS)
+    add_subdirectory(docs)
 endif()
 
 # Python tests need the bindings fully configured above (the _audio target,