visqol-python 3.3.6__tar.gz → 3.5.0__tar.gz

visqol_python-3.5.0/CHANGELOG.md

@@ -0,0 +1,163 @@
+# 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.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.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.3.6 → visqol_python-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.3.6
+Version: 3.5.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
@@ -28,12 +29,21 @@ Requires-Dist: numpy>=1.20
 Requires-Dist: scipy>=1.7
 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: all
+Requires-Dist: numba>=0.57; extra == "all"
+Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev
 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"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -43,19 +53,25 @@ 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 + fastmath) and DP patch matching — **9× overall speedup**, RTF 0.064 (surpasses C++ estimates)
+- **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
 
@@ -63,14 +79,34 @@ 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 DP matching (~9× faster):
+
+```bash
+pip install visqol-python[accel]
+```
+
+Install everything (lattice + numba):
+
+```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
@@ -121,12 +157,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}")
@@ -153,7 +192,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 |
@@ -181,21 +223,34 @@ 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:
 
+### Without Numba (pure Python + NumPy/SciPy)
+
 | Mode | Avg RTF | Typical Time |
 |------|---------|-------------|
-| Audio (48 kHz) | **0.71x** | 7 – 12 s per file pair |
+| Audio (48 kHz) | **0.18x** | ~2.2 s per file pair |
 | Speech (16 kHz) | **0.38x** | ~1 s per file pair |
 
+### With Numba (`pip install visqol-python[accel]`)
+
+| Mode | Avg RTF | Typical Time | Speedup |
+|------|---------|-------------|---------|
+| Audio (48 kHz) | **0.064x** | ~0.8 s per file pair | **9×** |
+
 > RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba acceleration, the Python implementation **surpasses C++ estimated performance** (RTF ≈ 0.093).
 
 ## Project Structure
 
@@ -215,18 +270,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
 ```
@@ -247,7 +307,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.3.6 → visqol_python-3.5.0}/README.md

@@ -5,19 +5,25 @@
 [![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 + fastmath) and DP patch matching — **9× overall speedup**, RTF 0.064 (surpasses C++ estimates)
+- **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 +31,34 @@ 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 DP matching (~9× faster):
+
+```bash
+pip install visqol-python[accel]
+```
+
+Install everything (lattice + numba):
+
+```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 +109,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 +144,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 +175,34 @@ 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:
 
+### Without Numba (pure Python + NumPy/SciPy)
+
 | Mode | Avg RTF | Typical Time |
 |------|---------|-------------|
-| Audio (48 kHz) | **0.71x** | 7 – 12 s per file pair |
+| Audio (48 kHz) | **0.18x** | ~2.2 s per file pair |
 | Speech (16 kHz) | **0.38x** | ~1 s per file pair |
 
+### With Numba (`pip install visqol-python[accel]`)
+
+| Mode | Avg RTF | Typical Time | Speedup |
+|------|---------|-------------|---------|
+| Audio (48 kHz) | **0.064x** | ~0.8 s per file pair | **9×** |
+
 > RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba acceleration, the Python implementation **surpasses C++ estimated performance** (RTF ≈ 0.093).
 
 ## Project Structure
 
@@ -177,18 +222,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 +259,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.3.6 → visqol_python-3.5.0}/pyproject.toml

@@ -15,6 +15,7 @@ authors = [
 keywords = [
     "audio-quality", "speech-quality", "MOS", "PESQ", "POLQA",
     "visqol", "objective-metric", "perceptual-quality",
+    "numba", "batch-processing",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -28,6 +29,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Sound/Audio :: Analysis",
     "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
 ]
 dependencies = [
     "numpy>=1.20",
@@ -37,11 +39,19 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+accel = ["numba>=0.57"]
+lattice = ["ai-edge-litert>=2.1.5; python_version >= '3.10'"]
+all = [
+    "numba>=0.57",
+    "ai-edge-litert>=2.1.5; python_version >= '3.10'",
+]
 test = ["pytest>=7.0"]
 dev = [
     "pytest>=7.0",
     "ruff>=0.4",
     "mypy>=1.8",
+    "numba>=0.57",
+    "ai-edge-litert>=2.1.5; python_version >= '3.10'",
 ]
 
 [project.urls]
@@ -61,7 +71,7 @@ version = {attr = "visqol.__version__"}
 exclude = ["tests*"]
 
 [tool.setuptools.package-data]
-visqol = ["model/*.txt", "py.typed"]
+visqol = ["model/*.txt", "model/*.tflite", "py.typed"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -81,7 +91,16 @@ select = [
     "SIM",  # flake8-simplify
     "RUF",  # ruff-specific rules
 ]
-ignore = ["E501"]  # line length handled by formatter
+ignore = [
+    "E501",    # line length handled by formatter
+    "RUF001",  # ambiguous unicode in string (intentional mathematical symbols)
+    "RUF002",  # ambiguous unicode in docstring (intentional: ×, −)
+    "RUF003",  # ambiguous unicode in comment (intentional: ×, →)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/bench_*.py" = ["E402", "E702"]  # bench scripts use sys.path manipulation
+"tests/test_parallel_correctness.py" = ["E402"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["visqol"]
@@ -92,5 +111,19 @@ warn_return_any = true
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = ["svmutil.*", "libsvm.*", "soundfile.*"]
+module = [
+    "svmutil.*",
+    "libsvm.*",
+    "soundfile.*",
+    "numba.*",
+    "ai_edge_litert.*",
+]
 ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["visqol.numba_accel"]
+# numba @njit decorators are untyped; strict mode is not feasible here
+strict = false
+disallow_untyped_defs = false
+disallow_untyped_decorators = false
+warn_unused_ignores = false