libspeech 0.1.1__tar.gz → 0.3.0__tar.gz

libspeech-0.3.0/.github/workflows/cmake.yml

@@ -0,0 +1,143 @@
+name: cmake stuff
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build-and-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    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"
+
+    # speech::models (BUILD_MODELS=ON, the default) needs httpp on the
+    # CMAKE_PREFIX_PATH via find_package(httpp) -- see the "Model
+    # downloading" comment block in the top-level CMakeLists.txt. This has
+    # to happen before the configure step below, since CMake shells out to
+    # `python -c "import httpp; ..."` at configure time to locate it.
+    - name: Install httpp
+      run: pip install httpp
+
+    - name: Build Project
+      uses: threeal/cmake-action@v2.1.0
+      with:
+        build-dir: build
+        options: |
+          CMAKE_BUILD_TYPE=Release
+          BUILD_MODELS=ON
+          BUILD_TESTS=ON
+          BUILD_PYTHON=OFF
+
+    - name: Build
+      run: cmake --build build --config Release
+
+    - name: Run tests
+      run: ctest --test-dir build --output-on-failure --build-config Release
+
+  build-docs:
+    needs: build-and-test
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    - name: Install Doxygen + graphviz
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y doxygen graphviz
+
+    - name: Configure CMake
+      run: |
+        cmake -B build \
+          -DBUILD_MODELS=OFF \
+          -DBUILD_TESTS=OFF \
+          -DBUILD_DOCS=ON
+
+    - name: Build documentation
+      run: cmake --build build --target speech_docs
+
+    - name: Upload documentation artifact
+      uses: actions/upload-artifact@v7
+      with:
+        name: cmake-documentation
+        path: build/docs/out/html
+        retention-days: 5
+
+  build-coverage:
+    needs: build-and-test
+    runs-on: ubuntu-latest
+
+    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).
+    # coverage: drives speech_coverage_python. The rest of the Python side
+    # (nanobind, pytest, ...) is installed by CMakeLists.txt itself when
+    # BUILD_PYTHON=ON.
+    - name: Install python dependencies
+      run: pip install httpp coverage
+
+    - name: Install lcov
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y lcov
+
+    # Same shape as ctoon's coverage job: every component (speech::dsp,
+    # speech::models C++ tests + the Python package's tests) is covered
+    # individually, then merged into coverage/total/ + a dashboard at
+    # coverage/index.html. BUILD_COVERAGE is an explicit opt-in (see the
+    # comment in tests/CMakeLists.txt for why it isn't implied by lcov
+    # merely being installed).
+    - name: Configure CMake with coverage
+      run: |
+        cmake -B build \
+          -DBUILD_MODELS=ON \
+          -DBUILD_TESTS=ON \
+          -DBUILD_PYTHON=ON \
+          -DBUILD_COVERAGE=ON
+
+    - name: Generate coverage report
+      run: cmake --build build --target speech_coverage
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        files: build/coverage/total/coverage.lcov
+        flags: unittests
+        name: codecov-libspeech
+        fail_ci_if_error: false
+        verbose: true
+
+    - name: Upload coverage artifact
+      uses: actions/upload-artifact@v7
+      with:
+        name: cmake-coverage-report
+        path: build/coverage/
+        retention-days: 5

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

@@ -86,7 +86,20 @@ jobs:
         # ships wheels from cp39-abi3 up on PyPI, not cp38 -- building a
         # cp38 wheel here would require httpp built from source instead.
         CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-*"
-        CIBW_ENVIRONMENT_CP312: "SKBUILD_WHEEL_PY_API=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
+        # forward-compatible cp312-abi3 wheel instead of a version-locked
+        # cp312-cp312 one -- see the [tool.cibuildwheel.overrides] entry
+        # in pyproject.toml for *why* it has to live there instead of
+        # here) do NOT work as a "CIBW_<OPTION>_<IDENTIFIER>" env var like
+        # CIBW_ENVIRONMENT_CP312: cibuildwheel only recognizes that
+        # suffix pattern for CIBW_ENVIRONMENT_{LINUX,MACOS,WINDOWS} (i.e.
+        # by platform), not by Python-version identifier -- an env var
+        # like that is silently a no-op, not an error, which is exactly
+        # how this went unnoticed (confirmed: the wheel actually
+        # published to PyPI for 0.1.0 came out tagged cp312-cp312, not
+        # cp312-abi3, meaning SKBUILD_WHEEL_PY_API was never really set
+        # during that build despite this line being here).
         # Disable building PyPy wheels on all platforms. Also skip
         # musllinux (Alpine/musl has no official ONNX Runtime build --
         # only glibc-linked releases exist, which fail to link against

{libspeech-0.1.1 → libspeech-0.3.0}/.gitmodules

@@ -3,8 +3,3 @@
 	url = https://github.com/mackron/miniaudio.git
 	shallow = true
 
-[submodule "src/third_party/dr_libs"]
-	path = src/third_party/dr_libs
-	url = https://github.com/mackron/dr_libs.git
-	shallow = true
-

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

@@ -3,6 +3,8 @@ 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_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")
 set(CMAKE_C_STANDARD_REQUIRED ON)
@@ -108,8 +110,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()
     return()
 endif()
 
@@ -117,6 +126,26 @@ include(ONNXRuntime)
 
 add_subdirectory(src/third_party/miniaudio)
 
+# miniaudio.h uses the C23 double-bracket attribute syntax for its
+# fallthrough marker (MA_FALLTHROUGH -> [[fallthrough]], see miniaudio.h)
+# even in the gnu99 translation unit miniaudio.c compiles as. GCC accepts
+# this quietly under gnu99, but (Apple) Clang's -Wc23-extensions flags it
+# -- three warnings, no errors, harmless either way.
+#
+# This is vendored, upstream code pulled in via a git submodule -- editing
+# miniaudio.h directly isn't an option (the fix would silently vanish on
+# the next `git submodule update`), and a project-wide -Wno-c23-extensions
+# would also mute the same warning if it ever showed up in code we
+# actually own. So silence only this one diagnostic, and only on the one
+# target it's known to come from (confirmed: only miniaudio.c itself hits
+# it, not the extra node .c files below, which don't compile the
+# MA_FALLTHROUGH-containing implementation). Safe to drop once upstream
+# miniaudio switches to __attribute__((fallthrough)) or the project moves
+# to a C standard where the warning no longer applies.
+if(CMAKE_C_COMPILER_ID MATCHES "Clang")
+    target_compile_options(miniaudio PRIVATE -Wno-c23-extensions)
+endif()
+
 # ---------------------------------------------------------------------------
 # Model downloading (speech::utils::downloadFile) used to link the SYSTEM
 # libcurl (find_package(CURL REQUIRED) + apt-installed libcurl4-openssl-dev)
@@ -185,16 +214,18 @@ endif()
 
 # ---------------------------------------------------------------------------
 # speech::io -- audio file I/O (the Audio class: load/save/play/resample/
-# to_mono), backed by miniaudio + dr_libs. Mirrors speech::dsp/speech::models:
-# its own static library, its own namespace (speech::io in the C++ code,
-# matching this CMake alias).
+# to_mono), backed by miniaudio alone (its ma_decoder/ma_encoder embed their
+# own renamed copy of dr_wav/dr_mp3/dr_flac internally -- see the comment at
+# the top of src/audio.cpp -- so the separate dr_libs submodule this used to
+# also need is gone). Mirrors speech::dsp/speech::models: its own static
+# library, its own namespace (speech::io in the C++ code, matching this
+# CMake alias).
 # ---------------------------------------------------------------------------
 add_library(speech_io STATIC src/audio.cpp)
 add_library(speech::io ALIAS speech_io)
 
 target_include_directories(speech_io
         PUBLIC ${PROJECT_SOURCE_DIR}/include
-        PRIVATE src/third_party/dr_libs
         PRIVATE src/third_party/aixlog/include
 )
 target_link_libraries(speech_io
@@ -461,7 +492,7 @@ if(DEFINED PYTHON_PROJECT_NAME)
                 LIBRARY DESTINATION ${PYTHON_PROJECT_NAME}
                 RUNTIME DESTINATION ${PYTHON_PROJECT_NAME})
 
-        # The pure-Python files (__init__.py, __main__.py, core.py) need
+        # 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
@@ -571,6 +602,13 @@ if(BUILD_TESTS AND DEFINED PYTHON_PROJECT_NAME AND NOT DEFINED SKBUILD)
     add_subdirectory(tests/python)
 endif()
 
+# Merge every coverage component configured above into speech_coverage_total
+# + the dashboard (no-op unless -DBUILD_COVERAGE=ON). The BUILD_MODELS=OFF
+# early return above calls this too, since it never reaches this point.
+if(BUILD_TESTS)
+    speech_coverage_finalize()
+endif()
+
 if(DEFINED SKBUILD)
     RETURN()
 endif()

{libspeech-0.1.1 → libspeech-0.3.0}/CONTRIBUTING.md

@@ -12,16 +12,15 @@ git clone https://github.com/MohammadRaziei/libspeech.git
 cd libspeech
 
 # Small, lightweight submodules:
-git submodule update --init src/third_party/miniaudio src/third_party/dr_libs src/third_party/indicators
+git submodule update --init src/third_party/miniaudio
 
-# Mbed TLS (pinned to v3.6.2, kept shallow -- see .gitmodules) has its own
-# nested submodule ("framework") that also needs initializing:
-git submodule update --init src/third_party/mbedtls
-git submodule update --init --depth 1 src/third_party/mbedtls/framework
+# speech::models (BUILD_MODELS=ON, the default) needs httpp on
+# CMAKE_PREFIX_PATH for model downloads (HTTPS client + progress bar):
+pip install httpp
 ```
 
-A few entries under `src/third_party/` (AudioFlux subset, aixlog, httplib)
-are **not** submodules -- those are copied directly into the repo, alongside
+A few entries under `src/third_party/` (AudioFlux subset, aixlog) are
+**not** submodules -- those are copied directly into the repo, alongside
 the actual submodules. See `src/third_party/README.md` for why and which
 ones.
 
@@ -103,9 +102,12 @@ what's already vendored under `src/third_party/`:
    what/why/before-after -- in `audioflux_issues.md` (or a new file
    following that structure for a different vendored project), so it can
    become an upstream PR later.
-3. Security-critical code (crypto, TLS) is the exception: keep those as
-   full git submodules (see Mbed TLS above), not cherry-picked/vendored,
-   so security patches stay easy to pull in.
+3. Security/network-critical code is a different story: `httpp`
+   (HTTPS client + progress bar for model downloads) is a genuine,
+   separately-`pip install`able runtime dependency, not something to vendor
+   or patch in-tree -- see the `find_package(httpp)` comment block in
+   `CMakeLists.txt` for why (this replaced an earlier vendored
+   cpp-httplib + Mbed TLS setup for exactly this reason).
 
 ## Style notes
 
@@ -136,6 +138,46 @@ python version.py minor +            # bump the minor version
 python version.py tag create patch   # bump patch, commit, and tag a release
 ```
 
+## Docs and coverage
+
+`-DBUILD_DOCS=ON` gives you `speech_docs` (Doxygen, warnings-free -- keep it
+that way when you touch a public header). `-DBUILD_COVERAGE=ON` (needs
+`lcov`; add `-DBUILD_PYTHON=ON` and `pip install coverage` for the Python
+side) gives you `speech_coverage`, which runs every component's tests
+instrumented, merges them, and writes a dashboard to
+`build/coverage/index.html`. It mirrors ctoon's setup -- see the "Docs &
+coverage" table in `README.md`. A new C++ module with its own test target
+gets a coverage target by calling `speech_enable_coverage(<lib>)` and
+`speech_add_cpp_coverage_target(...)` next to its tests (see
+`tests/models/CMakeLists.txt` for a three-line example).
+
+Two lcov 2.0 quirks worth knowing before you debug them yourself: its
+`--list` output is wrong (use `--summary`, as the targets do), and an
+`--extract`/`--exclude` pattern that matches nothing is a hard error unless
+you pass `--ignore-errors unused`.
+
+## Packaging / CI changes
+
+If you touch `CMakeLists.txt`'s install rules, `pyproject.toml`, or
+`.github/workflows/wheels.yml`, actually build a wheel locally and inspect
+its *contents* before opening a PR -- don't just read the config and
+assume it's right:
+
+```bash
+python -m build --wheel -o /tmp/wheelcheck
+python -c "import zipfile; z = zipfile.ZipFile('/tmp/wheelcheck/<name>.whl'); [print(i.filename, i.file_size) for i in z.infolist()]"
+```
+
+This project has twice shipped a packaging bug invisible from reading the
+config alone -- a duplicated ~20MB ONNX Runtime binary (symlinks get
+dereferenced both by `install(FILES ...)` and by the wheel-zip step), and a
+wheel silently missing its intended `abi3` tag (`CIBW_ENVIRONMENT_CP312`
+looked like a real cibuildwheel option by analogy with
+`CIBW_ENVIRONMENT_LINUX`, but isn't -- cibuildwheel only recognizes
+platform suffixes there, not Python-version ones, and silently no-ops
+instead of erroring). Both only showed up by actually opening the built
+artifact.
+
 ## Current project status
 
 See [`checklist.md`](checklist.md) for the up-to-date, detailed state of

{libspeech-0.1.1 → libspeech-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: libspeech
-Version: 0.1.1
+Version: 0.3.0
 Summary: Best library for speech
 Author-Email: Mohammad Raziei <mohammadraziei1375@gmail.com>
 Classifier: Development Status :: 4 - Beta
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 [![Python Versions](https://img.shields.io/pypi/pyversions/libspeech)](https://pypi.org/project/libspeech/)
 [![C++ Standard](https://img.shields.io/badge/C++-17-blue)](https://en.cppreference.com/w/cpp/17)
 
-[![Build Status](https://github.com/mohammadraziei/libspeech/actions/workflows/build.yml/badge.svg)](https://github.com/mohammadraziei/libspeech/actions)
+[![Build Status](https://github.com/mohammadraziei/libspeech/actions/workflows/cmake.yml/badge.svg)](https://github.com/mohammadraziei/libspeech/actions)
 [![Code Quality](https://sonarcloud.io/api/project_badges/measure?project=MohammadRaziei_libspeech&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=MohammadRaziei_libspeech)
 [![CodeFactor](https://www.codefactor.io/repository/github/mohammadraziei/libspeech/badge/master)](https://www.codefactor.io/repository/github/mohammadraziei/libspeech/overview/master)
 [![snyk.io](https://snyk.io/advisor/python/libspeech/badge.svg)](https://snyk.io/advisor/python/libspeech)
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 - 🔊 **Speech models** (`speech::models`): a `Denoiser` interface (Facebook/SpeechBrain backends) and Silero VAD
 - 🖥️ **Cross-platform**: Windows, Linux, macOS
 - 🐍 **Python bindings** (nanobind) mirroring the C++ API 1:1
-- 📦 **Zero system dependencies**: no `apt install libcurl-dev` / OpenSSL needed -- HTTPS model downloads go through a vendored [cpp-httplib](https://github.com/yhirose/cpp-httplib) + [Mbed TLS](https://github.com/Mbed-TLS/mbedtls) built from source
+- 📦 **Zero system dependencies**: no `apt install libcurl-dev` / OpenSSL needed -- HTTPS model downloads go through [`httpp`](https://github.com/mohammadraziei/httpp) (`pip install httpp`), a separately-installed package with its own prebuilt HTTP(S) client and progress bar
 
 ## 📦 Installation
 
@@ -72,11 +72,12 @@ pip install libspeech
 ```bash
 git clone https://github.com/MohammadRaziei/libspeech.git
 cd libspeech
-git submodule update --init src/third_party/miniaudio src/third_party/dr_libs src/third_party/indicators
+git submodule update --init src/third_party/miniaudio
 
-# Mbed TLS is pinned to v3.6.2 and kept as a shallow submodule (see .gitmodules):
-git submodule update --init src/third_party/mbedtls
-git submodule update --init --depth 1 src/third_party/mbedtls/framework
+# speech::models (BUILD_MODELS=ON, the default) needs httpp on
+# CMAKE_PREFIX_PATH for model downloads (HTTPS client + progress bar) --
+# no more Mbed TLS/libcurl to build, just:
+pip install httpp
 
 mkdir build && cd build
 cmake ..                      # downloads ONNX Runtime automatically on first configure
@@ -159,6 +160,34 @@ speech_test                       # everything
 Run everything with `cmake --build build --target speech_test`, or just
 `ctest` for the same suites without the extra build-tool chatter.
 
+### Docs & coverage
+
+```bash
+cmake .. -DBUILD_DOCS=ON && cmake --build . --target speech_docs   # Doxygen HTML -> build/docs/out/html
+```
+
+Coverage follows the same layout as [ctoon](https://github.com/mohammadraziei/ctoon):
+one target per component, a merged total, and a dashboard tying the reports
+together.
+
+```bash
+cmake .. -DBUILD_PYTHON=ON -DBUILD_COVERAGE=ON   # + `pip install coverage`, lcov/genhtml on PATH
+cmake --build . --target speech_coverage         # everything below, then the merge + dashboard
+```
+
+| Target | Covers | Output (under `build/coverage/`) |
+|---|---|---|
+| `speech_coverage_cpp_dsp` | `speech::dsp` (utest.h suite) | `cpp_dsp/` |
+| `speech_coverage_cpp_models` | `speech::models` + download utils | `cpp_models/` |
+| `speech_coverage_python` | the Python package's `.py` files (coverage.py) | `python/` |
+| `speech_coverage_total` | lcov merge of all of the above | `total/` |
+
+Open `build/coverage/index.html` for the dashboard. Each component (and the
+total) also leaves a plain `coverage.lcov` next to its HTML, which is what CI
+uploads to Codecov. `BUILD_COVERAGE` is off by default: it instruments
+`speech_dsp`/`speech_models` with `--coverage`, which you don't want in a
+normal build. Without `BUILD_PYTHON` you just get the C++ components.
+
 ## 🔧 Architecture
 
 libspeech is split into three independent C++ libraries (each with its own
@@ -168,7 +197,7 @@ library:
 | Namespace | CMake target | Python module | Depends on |
 |---|---|---|---|
 | `speech::dsp` | `speech_dsp` | `speech_dsp_py` | nothing but a vendored subset of [AudioFlux](https://github.com/libAudioFlux/audioflux)'s C sources |
-| `speech::io` | `speech_io` | `speech_io_py` | `speech::dsp` (for resampling), miniaudio, dr_libs |
+| `speech::io` | `speech_io` | `speech_io_py` | `speech::dsp` (for resampling), miniaudio |
 | `speech::models` | `speech_models` | `speech_models_py` | ONNX Runtime, httplib+Mbed TLS (for downloading model weights) |
 
 See [`checklist.md`](checklist.md) for the detailed, up-to-date state of

{libspeech-0.1.1 → libspeech-0.3.0}/README.md

@@ -17,7 +17,7 @@
 [![Python Versions](https://img.shields.io/pypi/pyversions/libspeech)](https://pypi.org/project/libspeech/)
 [![C++ Standard](https://img.shields.io/badge/C++-17-blue)](https://en.cppreference.com/w/cpp/17)
 
-[![Build Status](https://github.com/mohammadraziei/libspeech/actions/workflows/build.yml/badge.svg)](https://github.com/mohammadraziei/libspeech/actions)
+[![Build Status](https://github.com/mohammadraziei/libspeech/actions/workflows/cmake.yml/badge.svg)](https://github.com/mohammadraziei/libspeech/actions)
 [![Code Quality](https://sonarcloud.io/api/project_badges/measure?project=MohammadRaziei_libspeech&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=MohammadRaziei_libspeech)
 [![CodeFactor](https://www.codefactor.io/repository/github/mohammadraziei/libspeech/badge/master)](https://www.codefactor.io/repository/github/mohammadraziei/libspeech/overview/master)
 [![snyk.io](https://snyk.io/advisor/python/libspeech/badge.svg)](https://snyk.io/advisor/python/libspeech)
@@ -33,7 +33,7 @@
 - 🔊 **Speech models** (`speech::models`): a `Denoiser` interface (Facebook/SpeechBrain backends) and Silero VAD
 - 🖥️ **Cross-platform**: Windows, Linux, macOS
 - 🐍 **Python bindings** (nanobind) mirroring the C++ API 1:1
-- 📦 **Zero system dependencies**: no `apt install libcurl-dev` / OpenSSL needed -- HTTPS model downloads go through a vendored [cpp-httplib](https://github.com/yhirose/cpp-httplib) + [Mbed TLS](https://github.com/Mbed-TLS/mbedtls) built from source
+- 📦 **Zero system dependencies**: no `apt install libcurl-dev` / OpenSSL needed -- HTTPS model downloads go through [`httpp`](https://github.com/mohammadraziei/httpp) (`pip install httpp`), a separately-installed package with its own prebuilt HTTP(S) client and progress bar
 
 ## 📦 Installation
 
@@ -46,11 +46,12 @@ pip install libspeech
 ```bash
 git clone https://github.com/MohammadRaziei/libspeech.git
 cd libspeech
-git submodule update --init src/third_party/miniaudio src/third_party/dr_libs src/third_party/indicators
+git submodule update --init src/third_party/miniaudio
 
-# Mbed TLS is pinned to v3.6.2 and kept as a shallow submodule (see .gitmodules):
-git submodule update --init src/third_party/mbedtls
-git submodule update --init --depth 1 src/third_party/mbedtls/framework
+# speech::models (BUILD_MODELS=ON, the default) needs httpp on
+# CMAKE_PREFIX_PATH for model downloads (HTTPS client + progress bar) --
+# no more Mbed TLS/libcurl to build, just:
+pip install httpp
 
 mkdir build && cd build
 cmake ..                      # downloads ONNX Runtime automatically on first configure
@@ -133,6 +134,34 @@ speech_test                       # everything
 Run everything with `cmake --build build --target speech_test`, or just
 `ctest` for the same suites without the extra build-tool chatter.
 
+### Docs & coverage
+
+```bash
+cmake .. -DBUILD_DOCS=ON && cmake --build . --target speech_docs   # Doxygen HTML -> build/docs/out/html
+```
+
+Coverage follows the same layout as [ctoon](https://github.com/mohammadraziei/ctoon):
+one target per component, a merged total, and a dashboard tying the reports
+together.
+
+```bash
+cmake .. -DBUILD_PYTHON=ON -DBUILD_COVERAGE=ON   # + `pip install coverage`, lcov/genhtml on PATH
+cmake --build . --target speech_coverage         # everything below, then the merge + dashboard
+```
+
+| Target | Covers | Output (under `build/coverage/`) |
+|---|---|---|
+| `speech_coverage_cpp_dsp` | `speech::dsp` (utest.h suite) | `cpp_dsp/` |
+| `speech_coverage_cpp_models` | `speech::models` + download utils | `cpp_models/` |
+| `speech_coverage_python` | the Python package's `.py` files (coverage.py) | `python/` |
+| `speech_coverage_total` | lcov merge of all of the above | `total/` |
+
+Open `build/coverage/index.html` for the dashboard. Each component (and the
+total) also leaves a plain `coverage.lcov` next to its HTML, which is what CI
+uploads to Codecov. `BUILD_COVERAGE` is off by default: it instruments
+`speech_dsp`/`speech_models` with `--coverage`, which you don't want in a
+normal build. Without `BUILD_PYTHON` you just get the C++ components.
+
 ## 🔧 Architecture
 
 libspeech is split into three independent C++ libraries (each with its own
@@ -142,7 +171,7 @@ library:
 | Namespace | CMake target | Python module | Depends on |
 |---|---|---|---|
 | `speech::dsp` | `speech_dsp` | `speech_dsp_py` | nothing but a vendored subset of [AudioFlux](https://github.com/libAudioFlux/audioflux)'s C sources |
-| `speech::io` | `speech_io` | `speech_io_py` | `speech::dsp` (for resampling), miniaudio, dr_libs |
+| `speech::io` | `speech_io` | `speech_io_py` | `speech::dsp` (for resampling), miniaudio |
 | `speech::models` | `speech_models` | `speech_models_py` | ONNX Runtime, httplib+Mbed TLS (for downloading model weights) |
 
 See [`checklist.md`](checklist.md) for the detailed, up-to-date state of