visqol-python 3.4.0__tar.gz → 3.6.0__tar.gz

visqol_python-3.6.0/CHANGELOG.md

@@ -0,0 +1,227 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [3.6.0] - 2026-05-27
+
+### Added
+- **Optional pyFFTW backend** (`pip install visqol-python[fftw]`):
+  - Routes `scipy.fft.fft / ifft / rfft / irfft` through FFTW3 via
+    `pyfftw.interfaces.scipy_fft` for the alignment and cross-correlation
+    FFTs. Detected at module load time in `signal_utils` and applied
+    transparently via a thin `_fft_backend()` context manager.
+  - Plan cache enabled with 60 s keep-alive so consecutive measurements
+    on equal-length signals reuse the FFTW plan.
+
+### Improved
+- **Fused NSIM kernel**: `_measure_patch_similarity_numba` merged its 5
+  separate 2-D convolutions (μ_r, μ_d, ref², deg², ref·deg) and the
+  intensity/structure recombination into one `(r, c)` double loop. Each
+  patch element is read from L1 once per visit instead of five times,
+  and the four intermediate `(rows × cols)` matrices are no longer
+  materialised between convs. Bit-exact with the previous split-conv
+  path (ULP-level FP rounding only).
+- **`nsim.measure_patch_similarity`** now dispatches to the fused JIT
+  kernel when Numba is available — the same code path the DP patch
+  matcher uses, so `finely_align_and_recreate_patches` shares the
+  speedup. The pure-NumPy implementation is preserved as a fallback.
+- **`signal_utils._hilbert`** is a drop-in `scipy.signal.hilbert`
+  replacement built on `rfft` for the real-valued input (~2× less
+  forward-transform work than the original full complex `fft`).
+- **`signal_utils.find_best_lag`** now uses `rfft + irfft` for the
+  cross-correlation, again exploiting the real input. Net effect:
+  alignment FFTs see roughly 2× less work overall.
+- Removed dead helper `_conv2d_boundary_valid` from `numba_accel.py`
+  (subsumed by the fused kernel).
+
+### Fixed
+- **`find_best_lag` interpreter hot loop**: the previous implementation
+  ran `xcorr_full[-max_lag:].tolist() + xcorr_full[:max_lag+1].tolist()`
+  and then `builtin argmax(list)` over a ~1.2 M-element Python list,
+  costing ~33 ms per call in pure interpreter overhead. Now uses
+  `np.concatenate + np.argmax` entirely in C.
+
+### Performance
+
+Apple M-series, Python 3.13, audio mode, the `guitar48_stereo` 12.5 s
+conformance case, average of 3 runs with Numba + pyFFTW both installed:
+
+| Stage              | v3.5.0   | v3.6.0   | Speedup |
+|--------------------|----------|----------|---------|
+| DP Patch matching  | 0.397 s  | 0.131 s  | **3.0×** |
+| Global align / FFT | 0.173 s  | 0.091 s  | 1.9×    |
+| Fine align + NSIM  | 0.093 s  | 0.043 s  | 2.2×    |
+| Gammatone          | 0.173 s  | 0.179 s  | ~       |
+| **Total**          | **0.839 s** | **0.447 s** | **1.9×** |
+| **RTF**            | 0.067    | **0.036**   | (C++ est. 0.093) |
+
+### Numerical parity
+
+All v3.5.0 conformance baselines preserved within ULP precision:
+
+| Test                          | Max MOS diff vs v3.5.0 |
+|-------------------------------|------------------------|
+| Audio (10 conformance cases)  | < 5 × 10⁻¹⁴            |
+| Speech polynomial CA01        | 0.0 (bit-exact)        |
+| Speech lattice CA01           | 0.0 (bit-exact)        |
+
+## [3.5.0] - 2026-05-26
+
+### Added
+- **Deep-lattice TFLite speech quality mapper** (`pip install visqol-python[lattice]`):
+  - `TFLiteSpeechQualityMapper` loads the same `.tflite` lattice network used by
+    C++ ViSQOL's default `--use_lattice_model=true` and runs inference through
+    the upstream Google TFLite C++ runtime via `ai-edge-litert`
+  - New `use_lattice_model` parameter on `VisqolApi.create()` (default `None`
+    auto-enables lattice when the runtime is installed)
+  - New `lattice_model_path` parameter to override the bundled model
+  - New CLI flags `--no_lattice_model` and `--lattice_model PATH`
+- New `[lattice]` and `[all]` extras in `pyproject.toml`
+- Bundled `lattice_*.tflite` (2.1 MB) into the wheel as package data
+
+### Fixed
+- **GH issue #1**: Speech-mode MOS scores were systematically 1–2 points higher
+  than C++ ViSQOL's default. Root cause: the Python port only implemented the
+  legacy polynomial mapper (`SpeechSimilarityToQualityMapper`, equivalent to
+  C++ `--use_lattice_model=false`), while the C++ default routes through the
+  TFLite lattice network. Installing `visqol-python[lattice]` now matches C++
+  default scoring (CA01 conformance: diff 0.027 vs 1–2 MOS before).
+- **`signal_utils.normalize()` parity bug**: the previous implementation did
+  min–max scaling to ``[0, 1]`` (shifting the signal positive and adding a DC
+  offset), while C++ ``MiscMath::Normalize`` only divides by the peak. This
+  inflated the RMS values fed to the speech-mode VAD, causing Python to keep
+  every patch as voice-active and adding spurious patches the C++ binary
+  would have discarded. Fixing this brought polynomial speech parity from
+  diff 0.007 → 0.001 and was a prerequisite for lattice parity. Only the
+  speech-mode VAD path used this function; audio mode is unaffected.
+- **`nsim` stddev estimator mismatch**: both ``nsim.measure_patch_similarity``
+  (``np.std(..., ddof=0)``) and the Numba ``_measure_patch_similarity_numba``
+  kernel (``sqrt(ss / cols)``) used the population estimator (divide by N).
+  C++ uses Armadillo's ``stddev(..., 0)`` which is the *unbiased* sample
+  estimator (divide by N-1, despite the misleading ``0`` flag). The
+  per-band ``freq_band_stddevs`` was therefore systematically smaller by
+  ``sqrt((N-1)/N) ≈ 0.974``, which fed into the pooled ``fstdnsim`` and
+  perturbed every lattice prediction.
+- **`numba_accel.fastmath=True` on the Gammatone spectrogram kernel**: the
+  compounded LLVM-level FP reassociation across the 4-stage cascaded IIR ×
+  thousands of samples × hundreds of frames pushed lattice MOS off by
+  another ~0.02 vs strict IEEE-754. ``fastmath`` has been removed from the
+  spectrogram kernel; ``parallel=True`` is kept (each frame's IIR state is
+  independent so the reduction is safe).
+
+### Speech-mode parity numbers (CA01 conformance)
+
+| Mode | Before all fixes | After all fixes | C++ baseline |
+|------|------------------|-----------------|--------------|
+| Polynomial | diff 0.0067 | **diff 0.0011** | 3.3745 |
+| Lattice | diff 0.0856 (≈1–2 MOS on Nils's TCD-VOIP samples) | **diff 0.0023** | 3.3130 |
+
+### Changed
+- Speech mode `create(mode="speech")` now auto-uses lattice when available; when
+  `ai-edge-litert` is missing, it logs a one-time warning and falls back to
+  polynomial (existing scores reproduce exactly).
+- `tests/test_conformance.py` split the single speech case into
+  `test_speech_polynomial_conformance` (existing C++ polynomial baseline 3.3745)
+  and `test_speech_lattice_conformance` (regression baseline captured from this
+  implementation).
+- README: documented the polynomial-vs-lattice distinction, new install matrix,
+  and parity caveats.
+
+## [3.4.0] - 2026-03-23
+
+### Added
+- **Numba JIT acceleration** (`pip install visqol-python[accel]`):
+  - DP patch matching inner loops compiled to machine code via `@njit`
+  - Gammatone IIR filterbank compiled with `parallel=True` + `fastmath=True` — frames processed in parallel across all CPU cores
+  - NSIM similarity kernel JIT-compiled
+  - Automatic `NUMBA_THREADING_LAYER=workqueue` setup for macOS compatibility
+  - Zero-loss parallel accuracy (each frame's IIR state is independent)
+- **Batch evaluation API**: `VisqolApi.measure_batch()` with optional `parallel=True` and `max_workers` for multi-process execution
+- Exported `PatchSimilarityResult` and `ProgressCallback` from top-level package
+
+### Performance
+- **12x Gammatone speedup** via parallel + fastmath (1.53s → 0.13s per signal pair)
+- **8.7x DP patch matching speedup** via Numba JIT (3.5s → 0.40s)
+- **Overall 9x speedup**: RTF 0.58 → 0.064 (surpasses C++ estimate of 0.093)
+- Fine alignment skip optimization: 29x speedup when lag == 0
+
+### Improved
+- `__repr__` / `__str__` for `SimilarityResult`, `AudioSignal`, `PatchSimilarityResult`, `Spectrogram`
+- Logging replaces print statements in CLI verbose output
+- Development tooling: ruff lint/format + mypy strict type checking in CI
+
+### Fixed
+- **CI failures**: resolved all ruff lint (308 errors), ruff format (24 files), and mypy (24 errors) issues
+- Added `per-file-ignores` for benchmark test scripts (E402, E702)
+- Added mypy override for `numba_accel.py` (untyped `@njit` decorators)
+- Fixed `no-any-return` errors across `audio_utils.py`, `gammatone.py`, `visqol_core.py`, `api.py`
+- Added `TYPE_CHECKING` imports for `ImagePatchCreator` / `VadPatchCreator` in `visqol_core.py`
+
+## [3.3.6] - 2026-03-23
+
+### Added
+- **Batch evaluation API**: `VisqolApi.measure_batch()` with `progress_callback` support
+- **Numba optional acceleration**: `visqol/numba_accel.py` with JIT-compiled DP forward pass and NSIM kernel
+- `[accel]` optional dependency group: `pip install visqol-python[accel]`
+
+### Improved
+- `GammatoneFilterBank.apply_filter()` pre-builds coefficient arrays (avoids per-channel allocation)
+- `prepare_spectrograms_for_comparison()` vectorized per-frame noise floor
+- Ruff lint/format configuration added to `pyproject.toml`
+- CI enhanced with lint and type-check jobs
+- Development dependencies: `[project.optional-dependencies] dev`
+
+## [3.3.5] - 2026-03-23
+
+### Added
+- **Type hints** on all public and internal APIs (`from __future__ import annotations`)
+- **`py.typed`** marker (PEP 561) — mypy / pyright can now type-check dependents
+- **CONTRIBUTING.md** with development setup, code style, and PR guidelines
+- Exported `SimilarityResult` and `AudioSignal` from top-level `visqol` package
+- `mypy` configuration in `pyproject.toml`
+
+### Improved
+- **Error handling**: friendly `ValueError` / `FileNotFoundError` / `TypeError` throughout:
+  - `VisqolApi.create()` now validates mode, search_window, and model_path
+  - `VisqolApi.measure()` checks file existence before processing
+  - `VisqolApi.measure_from_arrays()` validates array types, emptiness, and sample rate
+  - `AudioSignal` validates sample rate on construction
+  - `AnalysisWindow` validates sample_rate and overlap range
+  - CLI now catches exceptions and prints user-friendly error messages
+- `AnalysisWindow.apply_hann_window()` uses `ValueError` instead of bare `assert`
+
+## [3.3.4] - 2026-03-23
+
+### Improved
+- Tests rewritten in **pytest** format with `parametrize` and fixtures
+- Added **CI workflow** (GitHub Actions): auto-test on Python 3.9–3.13 for every push/PR
+- Added **smoke tests** (`test_quick.py`) that run without external testdata
+- Version number now managed in a single place (`visqol/__init__.py`)
+- Removed redundant `setup.py` — `pyproject.toml` is the single source of truth
+- Added this CHANGELOG
+- README: added PyPI / CI / License badges
+
+### Fixed
+- `requires-python` updated from `>=3.8` to `>=3.9` (numpy/scipy dropped 3.8 support)
+
+## [3.3.3] - 2026-03-23
+
+### Added
+- Initial PyPI release as `visqol-python`
+- Pure Python port of [Google's ViSQOL v3.3.3](https://github.com/google/visqol)
+- **Audio mode** (48 kHz, SVR quality mapping) — 10/10 conformance tests pass
+- **Speech mode** (16 kHz, exponential polynomial mapping) — 1/1 conformance test passes
+- Python API: `VisqolApi.measure()` and `VisqolApi.measure_from_arrays()`
+- CLI: `python -m visqol` / `visqol` command
+- Bundled SVR model (`libsvm_nu_svr_model.txt`)
+- GitHub Actions workflow for auto-publish to PyPI via Trusted Publisher
+
+[3.6.0]: https://github.com/talker93/visqol-python/compare/v3.5.0...v3.6.0
+[3.5.0]: https://github.com/talker93/visqol-python/compare/v3.4.0...v3.5.0
+[3.4.0]: https://github.com/talker93/visqol-python/compare/v3.3.6...v3.4.0
+[3.3.6]: https://github.com/talker93/visqol-python/compare/v3.3.5...v3.3.6
+[3.3.5]: https://github.com/talker93/visqol-python/compare/v3.3.4...v3.3.5
+[3.3.4]: https://github.com/talker93/visqol-python/compare/v3.3.3...v3.3.4
+[3.3.3]: https://github.com/talker93/visqol-python/releases/tag/v3.3.3

{visqol_python-3.4.0 → visqol_python-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.4.0
+Version: 3.6.0
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/talker93/visqol-python/blob/main/CHAN
 Project-URL: Bug Reports, https://github.com/talker93/visqol-python/issues
 Project-URL: Source, https://github.com/talker93/visqol-python
 Project-URL: Original C++, https://github.com/google/visqol
-Keywords: audio-quality,speech-quality,MOS,PESQ,POLQA,visqol,objective-metric,perceptual-quality
+Keywords: audio-quality,speech-quality,MOS,PESQ,POLQA,visqol,objective-metric,perceptual-quality,numba,batch-processing
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
 Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -30,6 +31,14 @@ Requires-Dist: soundfile>=0.10
 Requires-Dist: libsvm-official>=3.25
 Provides-Extra: accel
 Requires-Dist: numba>=0.57; extra == "accel"
+Provides-Extra: lattice
+Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "lattice"
+Provides-Extra: fftw
+Requires-Dist: pyfftw>=0.13; extra == "fftw"
+Provides-Extra: all
+Requires-Dist: numba>=0.57; extra == "all"
+Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "all"
+Requires-Dist: pyfftw>=0.13; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev
@@ -37,6 +46,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Requires-Dist: numba>=0.57; extra == "dev"
+Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "dev"
+Requires-Dist: pyfftw>=0.13; extra == "dev"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -46,19 +57,26 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/visqol-python)](https://pypi.org/project/visqol-python/)
 [![License](https://img.shields.io/github/license/talker93/visqol-python)](LICENSE)
 
-A pure Python implementation of [Google's ViSQOL](https://github.com/google/visqol) (Virtual Speech Quality Objective Listener) v3.3.3 for objective audio/speech quality assessment.
+A pure Python implementation of [Google's ViSQOL](https://github.com/google/visqol) (Virtual Speech Quality Objective Listener) for objective audio/speech quality assessment.
 
 ViSQOL compares a reference audio signal with a degraded version and outputs a **MOS-LQO** (Mean Opinion Score - Listening Quality Objective) score on a scale of **1.0 – 5.0**.
 
 ## Features
 
 - **Two modes**: Audio mode (music/general audio at 48 kHz) and Speech mode (speech at 16 kHz)
-- **High accuracy**: 11/11 conformance tests pass against the official C++ implementation
+- **High accuracy**: 12/12 conformance tests pass against the official C++ implementation
   - Audio mode: 9/10 tests produce **identical** MOS scores (diff = 0.000000), 1 test diff = 0.000117
-  - Speech mode: diff = 0.006715
-- **Pure Python**: no C/C++ compilation required
-- **Minimal dependencies**: only 4 pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
-- **Faster than real-time**: Audio RTF ≈ 0.71x, Speech RTF ≈ 0.38x
+  - Speech mode (polynomial): diff = 0.001057
+  - Speech mode (lattice TFLite): diff = 0.002341
+- **Two speech quality mappers** matching C++ ViSQOL:
+  - **Lattice (default)** — deep-lattice TFLite network (`--use_lattice_model=true` in C++); requires the optional `[lattice]` extra
+  - **Polynomial (fallback)** — legacy exponential fit (`--use_lattice_model=false` in C++)
+- **Pure Python**: no C/C++ compilation required (the optional `[lattice]` extra adds the Google `ai-edge-litert` TFLite runtime as a binary wheel)
+- **Minimal dependencies**: 4 core pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel) and a fused NSIM + DP patch matching kernel
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment / xcorr FFTs through FFTW3 — **~16× overall speedup**, RTF 0.036 (vs C++ estimate 0.093)
+- **Batch & parallel evaluation**: `measure_batch(parallel=True)` for multi-process execution across CPU cores
+- **Fully typed**: PEP 561 `py.typed`, strict mypy, ruff-enforced code style
 
 ## Installation
 
@@ -66,14 +84,40 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
 pip install visqol-python
 ```
 
+For **C++-default-equivalent speech mode** (deep-lattice TFLite mapper):
+
+```bash
+pip install visqol-python[lattice]   # requires Python ≥ 3.10
+```
+
+For **Numba-accelerated** Gammatone filtering and the fused NSIM + DP kernel:
+
+```bash
+pip install visqol-python[accel]
+```
+
+For **FFTW3-backed alignment FFTs** via pyFFTW:
+
+```bash
+pip install visqol-python[fftw]
+```
+
+Install everything (lattice + numba + fftw):
+
+```bash
+pip install visqol-python[all]
+```
+
 Or install from source:
 
 ```bash
 git clone https://github.com/talker93/visqol-python.git
 cd visqol-python
-pip install -e .
+pip install -e ".[dev]"
 ```
 
+> **Note on speech mode parity**: Without the `[lattice]` extra, speech mode falls back to the polynomial mapping (equivalent to running C++ ViSQOL with `--use_lattice_model=false`). The polynomial can over-predict MOS by 1–2 points on degraded speech vs the C++ default. Install `[lattice]` whenever you need numbers that line up with the C++ default behaviour (see [issue #1](https://github.com/talker93/visqol-python/issues/1)).
+
 ## Quick Start
 
 ### Python API
@@ -124,12 +168,15 @@ file_pairs = [
     ("ref3.wav", "deg3.wav"),
 ]
 
-# Optional progress callback
+# Sequential with progress callback
 results = api.measure_batch(
     file_pairs,
     progress_callback=lambda done, total: print(f"{done}/{total}"),
 )
 
+# Multi-process parallel (uses all CPU cores)
+results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
+
 for pair, result in zip(file_pairs, results):
     if isinstance(result, Exception):
         print(f"{pair}: FAILED — {result}")
@@ -156,7 +203,10 @@ python -m visqol -r reference.wav -d degraded.wav -v
 |------|-------------|
 | `-r`, `--reference` | Path to reference WAV file (required) |
 | `-d`, `--degraded` | Path to degraded WAV file (required) |
-| `--speech_mode` | Use speech mode (16 kHz, polynomial mapping) |
+| `--speech_mode` | Use speech mode (16 kHz) |
+| `--no_lattice_model` | Speech mode: disable lattice TFLite mapper, use polynomial fallback |
+| `--lattice_model` | Custom path to lattice `.tflite` model (speech mode) |
+| `--unscaled_speech` | Don't scale polynomial speech MOS to 5.0 (polynomial only) |
 | `--model` | Custom SVR model file path (audio mode only) |
 | `--search_window` | Search window radius (default: 60) |
 | `--verbose`, `-v` | Show detailed per-patch results |
@@ -184,21 +234,37 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ### Speech Mode
 - Target sample rate: **16 kHz**
-- 32 Gammatone frequency bands (50 Hz – 8 000 Hz)
-- Quality mapping: exponential polynomial fit
+- 21 Gammatone frequency bands (50 Hz – 8 000 Hz)
 - VAD (Voice Activity Detection) based patch selection
+- Quality mapping (choose one):
+  - **Deep-lattice TFLite (default)** — same mapper as C++ ViSQOL's default `--use_lattice_model=true`; requires `pip install visqol-python[lattice]`
+  - **Exponential polynomial (fallback)** — same as C++ `--use_lattice_model=false`; used automatically when the lattice runtime is not installed
+- Toggle from Python: `api.create(mode="speech", use_lattice_model=False)`
+- Toggle from CLI: `--no_lattice_model`
 - Best for: speech, VoIP, telephony
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13:
+Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
 
-| Mode | Avg RTF | Typical Time |
-|------|---------|-------------|
-| Audio (48 kHz) | **0.71x** | 7 – 12 s per file pair |
-| Speech (16 kHz) | **0.38x** | ~1 s per file pair |
+| Configuration | RTF | Typical Time | Speedup vs pure Python |
+|---|---|---|---|
+| Pure Python + NumPy/SciPy | 0.58 | ~7 s | 1.0× |
+| + `[accel]` (Numba JIT) | 0.067 | ~0.84 s | 8.7× |
+| + `[accel] [fftw]` (Numba + FFTW3) | **0.036** | **~0.45 s** | **16×** |
 
 > RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba + pyFFTW the Python implementation runs at **2.6× the C++ estimated speed** (C++ RTF ≈ 0.093).
+
+Stage-level breakdown of the v3.6.0 fully-accelerated path:
+
+| Stage | Time | % |
+|---|---|---|
+| Gammatone filterbank | 0.179 s | 40% |
+| DP Patch matching (fused NSIM kernel) | 0.131 s | 29% |
+| Global alignment (pyFFTW rfft/irfft) | 0.091 s | 20% |
+| Fine alignment + NSIM | 0.043 s | 10% |
+| Other (SPL, postproc, SVR, …) | 0.003 s | < 1% |
 
 ## Project Structure
 
@@ -218,18 +284,23 @@ visqol-python/
 │   ├── alignment.py           # Global alignment via cross-correlation
 │   ├── nsim.py                # NSIM similarity metric
 │   ├── quality_mapper.py      # SVR & exponential quality mapping
+│   ├── numba_accel.py         # Optional Numba JIT kernels (DP, NSIM, Gammatone)
 │   ├── __main__.py            # CLI entry point
+│   ├── py.typed               # PEP 561 type marker
 │   └── model/                 # Bundled SVR model
 │       └── libsvm_nu_svr_model.txt
-├── tests/                     # Tests (pytest)
+├── tests/                     # Tests & benchmarks (pytest)
 │   ├── conftest.py            # Shared fixtures & CLI options
 │   ├── test_quick.py          # Smoke tests (no external data needed)
-│   └── test_conformance.py    # Full conformance tests (needs testdata)
+│   ├── test_conformance.py    # Full conformance tests (needs testdata)
+│   ├── test_parallel_correctness.py  # Numba parallel correctness tests
+│   └── bench_*.py             # Performance benchmarks
 ├── .github/workflows/
-│   ├── ci.yml                 # CI: test on Python 3.9–3.13
+│   ├── ci.yml                 # CI: lint + type-check + matrix test (Python × NumPy)
 │   └── publish.yml            # Auto-publish to PyPI on tag push
 ├── pyproject.toml             # Package metadata & build config
 ├── CHANGELOG.md
+├── CONTRIBUTING.md
 ├── LICENSE
 └── README.md
 ```
@@ -250,7 +321,10 @@ Tested against the [official C++ ViSQOL v3.3.3](https://github.com/google/visqol
 | glock_48aac | Audio | 4.3325 | 4.3325 | 0.000000 |
 | contrabassoon_24aac | Audio | 2.3469 | 2.3468 | 0.000117 |
 | castanets_identity | Audio | 4.7321 | 4.7321 | 0.000000 |
-| speech_CA01 | Speech | 3.3745 | 3.3678 | 0.006715 |
+| speech_CA01 (polynomial) | Speech | 3.3745 | 3.3756 | 0.001057 |
+| speech_CA01 (lattice) | Speech | 3.3130 | 3.3153 | 0.002341 |
+
+Both speech values come from running the C++ ViSQOL binary directly with the corresponding `--use_lattice_model` flag, so they represent ground-truth parity targets.
 
 ## References
 

{visqol_python-3.4.0 → visqol_python-3.6.0}/README.md

@@ -5,19 +5,26 @@
 [![Python](https://img.shields.io/pypi/pyversions/visqol-python)](https://pypi.org/project/visqol-python/)
 [![License](https://img.shields.io/github/license/talker93/visqol-python)](LICENSE)
 
-A pure Python implementation of [Google's ViSQOL](https://github.com/google/visqol) (Virtual Speech Quality Objective Listener) v3.3.3 for objective audio/speech quality assessment.
+A pure Python implementation of [Google's ViSQOL](https://github.com/google/visqol) (Virtual Speech Quality Objective Listener) for objective audio/speech quality assessment.
 
 ViSQOL compares a reference audio signal with a degraded version and outputs a **MOS-LQO** (Mean Opinion Score - Listening Quality Objective) score on a scale of **1.0 – 5.0**.
 
 ## Features
 
 - **Two modes**: Audio mode (music/general audio at 48 kHz) and Speech mode (speech at 16 kHz)
-- **High accuracy**: 11/11 conformance tests pass against the official C++ implementation
+- **High accuracy**: 12/12 conformance tests pass against the official C++ implementation
   - Audio mode: 9/10 tests produce **identical** MOS scores (diff = 0.000000), 1 test diff = 0.000117
-  - Speech mode: diff = 0.006715
-- **Pure Python**: no C/C++ compilation required
-- **Minimal dependencies**: only 4 pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
-- **Faster than real-time**: Audio RTF ≈ 0.71x, Speech RTF ≈ 0.38x
+  - Speech mode (polynomial): diff = 0.001057
+  - Speech mode (lattice TFLite): diff = 0.002341
+- **Two speech quality mappers** matching C++ ViSQOL:
+  - **Lattice (default)** — deep-lattice TFLite network (`--use_lattice_model=true` in C++); requires the optional `[lattice]` extra
+  - **Polynomial (fallback)** — legacy exponential fit (`--use_lattice_model=false` in C++)
+- **Pure Python**: no C/C++ compilation required (the optional `[lattice]` extra adds the Google `ai-edge-litert` TFLite runtime as a binary wheel)
+- **Minimal dependencies**: 4 core pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel) and a fused NSIM + DP patch matching kernel
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment / xcorr FFTs through FFTW3 — **~16× overall speedup**, RTF 0.036 (vs C++ estimate 0.093)
+- **Batch & parallel evaluation**: `measure_batch(parallel=True)` for multi-process execution across CPU cores
+- **Fully typed**: PEP 561 `py.typed`, strict mypy, ruff-enforced code style
 
 ## Installation
 
@@ -25,14 +32,40 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
 pip install visqol-python
 ```
 
+For **C++-default-equivalent speech mode** (deep-lattice TFLite mapper):
+
+```bash
+pip install visqol-python[lattice]   # requires Python ≥ 3.10
+```
+
+For **Numba-accelerated** Gammatone filtering and the fused NSIM + DP kernel:
+
+```bash
+pip install visqol-python[accel]
+```
+
+For **FFTW3-backed alignment FFTs** via pyFFTW:
+
+```bash
+pip install visqol-python[fftw]
+```
+
+Install everything (lattice + numba + fftw):
+
+```bash
+pip install visqol-python[all]
+```
+
 Or install from source:
 
 ```bash
 git clone https://github.com/talker93/visqol-python.git
 cd visqol-python
-pip install -e .
+pip install -e ".[dev]"
 ```
 
+> **Note on speech mode parity**: Without the `[lattice]` extra, speech mode falls back to the polynomial mapping (equivalent to running C++ ViSQOL with `--use_lattice_model=false`). The polynomial can over-predict MOS by 1–2 points on degraded speech vs the C++ default. Install `[lattice]` whenever you need numbers that line up with the C++ default behaviour (see [issue #1](https://github.com/talker93/visqol-python/issues/1)).
+
 ## Quick Start
 
 ### Python API
@@ -83,12 +116,15 @@ file_pairs = [
     ("ref3.wav", "deg3.wav"),
 ]
 
-# Optional progress callback
+# Sequential with progress callback
 results = api.measure_batch(
     file_pairs,
     progress_callback=lambda done, total: print(f"{done}/{total}"),
 )
 
+# Multi-process parallel (uses all CPU cores)
+results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
+
 for pair, result in zip(file_pairs, results):
     if isinstance(result, Exception):
         print(f"{pair}: FAILED — {result}")
@@ -115,7 +151,10 @@ python -m visqol -r reference.wav -d degraded.wav -v
 |------|-------------|
 | `-r`, `--reference` | Path to reference WAV file (required) |
 | `-d`, `--degraded` | Path to degraded WAV file (required) |
-| `--speech_mode` | Use speech mode (16 kHz, polynomial mapping) |
+| `--speech_mode` | Use speech mode (16 kHz) |
+| `--no_lattice_model` | Speech mode: disable lattice TFLite mapper, use polynomial fallback |
+| `--lattice_model` | Custom path to lattice `.tflite` model (speech mode) |
+| `--unscaled_speech` | Don't scale polynomial speech MOS to 5.0 (polynomial only) |
 | `--model` | Custom SVR model file path (audio mode only) |
 | `--search_window` | Search window radius (default: 60) |
 | `--verbose`, `-v` | Show detailed per-patch results |
@@ -143,21 +182,37 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ### Speech Mode
 - Target sample rate: **16 kHz**
-- 32 Gammatone frequency bands (50 Hz – 8 000 Hz)
-- Quality mapping: exponential polynomial fit
+- 21 Gammatone frequency bands (50 Hz – 8 000 Hz)
 - VAD (Voice Activity Detection) based patch selection
+- Quality mapping (choose one):
+  - **Deep-lattice TFLite (default)** — same mapper as C++ ViSQOL's default `--use_lattice_model=true`; requires `pip install visqol-python[lattice]`
+  - **Exponential polynomial (fallback)** — same as C++ `--use_lattice_model=false`; used automatically when the lattice runtime is not installed
+- Toggle from Python: `api.create(mode="speech", use_lattice_model=False)`
+- Toggle from CLI: `--no_lattice_model`
 - Best for: speech, VoIP, telephony
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13:
+Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
 
-| Mode | Avg RTF | Typical Time |
-|------|---------|-------------|
-| Audio (48 kHz) | **0.71x** | 7 – 12 s per file pair |
-| Speech (16 kHz) | **0.38x** | ~1 s per file pair |
+| Configuration | RTF | Typical Time | Speedup vs pure Python |
+|---|---|---|---|
+| Pure Python + NumPy/SciPy | 0.58 | ~7 s | 1.0× |
+| + `[accel]` (Numba JIT) | 0.067 | ~0.84 s | 8.7× |
+| + `[accel] [fftw]` (Numba + FFTW3) | **0.036** | **~0.45 s** | **16×** |
 
 > RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba + pyFFTW the Python implementation runs at **2.6× the C++ estimated speed** (C++ RTF ≈ 0.093).
+
+Stage-level breakdown of the v3.6.0 fully-accelerated path:
+
+| Stage | Time | % |
+|---|---|---|
+| Gammatone filterbank | 0.179 s | 40% |
+| DP Patch matching (fused NSIM kernel) | 0.131 s | 29% |
+| Global alignment (pyFFTW rfft/irfft) | 0.091 s | 20% |
+| Fine alignment + NSIM | 0.043 s | 10% |
+| Other (SPL, postproc, SVR, …) | 0.003 s | < 1% |
 
 ## Project Structure
 
@@ -177,18 +232,23 @@ visqol-python/
 │   ├── alignment.py           # Global alignment via cross-correlation
 │   ├── nsim.py                # NSIM similarity metric
 │   ├── quality_mapper.py      # SVR & exponential quality mapping
+│   ├── numba_accel.py         # Optional Numba JIT kernels (DP, NSIM, Gammatone)
 │   ├── __main__.py            # CLI entry point
+│   ├── py.typed               # PEP 561 type marker
 │   └── model/                 # Bundled SVR model
 │       └── libsvm_nu_svr_model.txt
-├── tests/                     # Tests (pytest)
+├── tests/                     # Tests & benchmarks (pytest)
 │   ├── conftest.py            # Shared fixtures & CLI options
 │   ├── test_quick.py          # Smoke tests (no external data needed)
-│   └── test_conformance.py    # Full conformance tests (needs testdata)
+│   ├── test_conformance.py    # Full conformance tests (needs testdata)
+│   ├── test_parallel_correctness.py  # Numba parallel correctness tests
+│   └── bench_*.py             # Performance benchmarks
 ├── .github/workflows/
-│   ├── ci.yml                 # CI: test on Python 3.9–3.13
+│   ├── ci.yml                 # CI: lint + type-check + matrix test (Python × NumPy)
 │   └── publish.yml            # Auto-publish to PyPI on tag push
 ├── pyproject.toml             # Package metadata & build config
 ├── CHANGELOG.md
+├── CONTRIBUTING.md
 ├── LICENSE
 └── README.md
 ```
@@ -209,7 +269,10 @@ Tested against the [official C++ ViSQOL v3.3.3](https://github.com/google/visqol
 | glock_48aac | Audio | 4.3325 | 4.3325 | 0.000000 |
 | contrabassoon_24aac | Audio | 2.3469 | 2.3468 | 0.000117 |
 | castanets_identity | Audio | 4.7321 | 4.7321 | 0.000000 |
-| speech_CA01 | Speech | 3.3745 | 3.3678 | 0.006715 |
+| speech_CA01 (polynomial) | Speech | 3.3745 | 3.3756 | 0.001057 |
+| speech_CA01 (lattice) | Speech | 3.3130 | 3.3153 | 0.002341 |
+
+Both speech values come from running the C++ ViSQOL binary directly with the corresponding `--use_lattice_model` flag, so they represent ground-truth parity targets.
 
 ## References