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

{visqol_python-3.3.6 → visqol_python-3.4.0}/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.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
@@ -49,6 +93,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - Bundled SVR model (`libsvm_nu_svr_model.txt`)
 - GitHub Actions workflow for auto-publish to PyPI via Trusted Publisher
 
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.3.6
+Version: 3.4.0
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -28,12 +28,15 @@ 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: 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"
 Dynamic: license-file
 
 # ViSQOL (Python)

{visqol_python-3.3.6 → visqol_python-3.4.0}/pyproject.toml

@@ -37,11 +37,13 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+accel = ["numba>=0.57"]
 test = ["pytest>=7.0"]
 dev = [
     "pytest>=7.0",
     "ruff>=0.4",
     "mypy>=1.8",
+    "numba>=0.57",
 ]
 
 [project.urls]
@@ -81,7 +83,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 +103,13 @@ warn_return_any = true
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = ["svmutil.*", "libsvm.*", "soundfile.*"]
+module = ["svmutil.*", "libsvm.*", "soundfile.*", "numba.*"]
 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

{visqol_python-3.3.6 → visqol_python-3.4.0}/tests/test_conformance.py

@@ -18,9 +18,9 @@ import pytest
 
 from visqol import VisqolApi
 
-
 # ── Fixtures ──
 
+
 @pytest.fixture(scope="session")
 def testdata_dir(request):
     """Resolve testdata directory from --testdata or auto-detect."""
@@ -63,36 +63,56 @@ def speech_api():
 TOLERANCE = 0.05
 
 AUDIO_CASES = [
-    ("strauss48_stereo.wav", "strauss48_stereo_lp35.wav",
-     1.3888791489130758, "strauss_lp35"),
-    ("steely48_stereo.wav", "steely48_stereo_lp7.wav",
-     2.2501683734385183, "steely_lp7"),
-    ("sopr48_stereo.wav", "sopr48_stereo_256kbps_aac.wav",
-     4.68228969737946, "sopr_256aac"),
-    ("ravel48_stereo.wav", "ravel48_stereo_128kbps_opus.wav",
-     4.465141897255348, "ravel_128opus"),
-    ("moonlight48_stereo.wav", "moonlight48_stereo_128kbps_aac.wav",
-     4.684292801646114, "moonlight_128aac"),
-    ("harpsichord48_stereo.wav", "harpsichord48_stereo_96kbps_mp3.wav",
-     4.22374532766003, "harpsichord_96mp3"),
-    ("guitar48_stereo.wav", "guitar48_stereo_64kbps_aac.wav",
-     4.349722308064298, "guitar_64aac"),
-    ("glock48_stereo.wav", "glock48_stereo_48kbps_aac.wav",
-     4.332452943882108, "glock_48aac"),
-    ("contrabassoon48_stereo.wav", "contrabassoon48_stereo_24kbps_aac.wav",
-     2.346868205375293, "contrabassoon_24aac"),
-    ("castanets48_stereo.wav", "castanets48_stereo.wav",
-     4.732101253042348, "castanets_identity"),
+    ("strauss48_stereo.wav", "strauss48_stereo_lp35.wav", 1.3888791489130758, "strauss_lp35"),
+    ("steely48_stereo.wav", "steely48_stereo_lp7.wav", 2.2501683734385183, "steely_lp7"),
+    ("sopr48_stereo.wav", "sopr48_stereo_256kbps_aac.wav", 4.68228969737946, "sopr_256aac"),
+    (
+        "ravel48_stereo.wav",
+        "ravel48_stereo_128kbps_opus.wav",
+        4.465141897255348,
+        "ravel_128opus",
+    ),
+    (
+        "moonlight48_stereo.wav",
+        "moonlight48_stereo_128kbps_aac.wav",
+        4.684292801646114,
+        "moonlight_128aac",
+    ),
+    (
+        "harpsichord48_stereo.wav",
+        "harpsichord48_stereo_96kbps_mp3.wav",
+        4.22374532766003,
+        "harpsichord_96mp3",
+    ),
+    (
+        "guitar48_stereo.wav",
+        "guitar48_stereo_64kbps_aac.wav",
+        4.349722308064298,
+        "guitar_64aac",
+    ),
+    ("glock48_stereo.wav", "glock48_stereo_48kbps_aac.wav", 4.332452943882108, "glock_48aac"),
+    (
+        "contrabassoon48_stereo.wav",
+        "contrabassoon48_stereo_24kbps_aac.wav",
+        2.346868205375293,
+        "contrabassoon_24aac",
+    ),
+    (
+        "castanets48_stereo.wav",
+        "castanets48_stereo.wav",
+        4.732101253042348,
+        "castanets_identity",
+    ),
 ]
 
 SPEECH_CASES = [
-    ("CA01_01.wav", "transcoded_CA01_01.wav",
-     3.374505555111911, "CA01_transcoded"),
+    ("CA01_01.wav", "transcoded_CA01_01.wav", 3.374505555111911, "CA01_transcoded"),
 ]
 
 
 # ── Audio mode tests ──
 
+
 @pytest.mark.parametrize(
     "ref_name, deg_name, expected_mos, test_id",
     AUDIO_CASES,
@@ -110,6 +130,7 @@ def test_audio_conformance(audio_api, conf_dir, ref_name, deg_name, expected_mos
 
 # ── Speech mode tests ──
 
+
 @pytest.mark.parametrize(
     "ref_name, deg_name, expected_mos, test_id",
     SPEECH_CASES,

visqol_python-3.4.0/tests/test_parallel_correctness.py

@@ -0,0 +1,96 @@
+"""
+Correctness test: verify that the parallel+fastmath Gammatone spectrogram
+produces results consistent with the original serial version.
+
+Approach: run the full ViSQOL pipeline on a known test file and check
+that the MOS score is within expected tolerance.
+"""
+
+import os
+import sys
+import time
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+VISQOL_ROOT = os.path.dirname(ROOT)
+sys.path.insert(0, ROOT)
+
+
+# --- Quick sanity: does the module load without errors? ---
+print("=" * 60)
+print("1) Import & warmup")
+print("=" * 60)
+from visqol import numba_accel
+
+print(f"   _HAS_NUMBA          = {numba_accel._HAS_NUMBA}")
+print(f"   _HAS_NUMBA_PARALLEL = {numba_accel._HAS_NUMBA_PARALLEL}")
+print(f"   NUMBA_THREADING_LAYER = {os.environ.get('NUMBA_THREADING_LAYER', '(not set)')}")
+
+t0 = time.perf_counter()
+numba_accel.warmup()
+t1 = time.perf_counter()
+print(f"   warmup completed in {t1 - t0:.2f}s")
+
+# --- Full pipeline correctness test ---
+print()
+print("=" * 60)
+print("2) Full pipeline MOS score test")
+print("=" * 60)
+
+from visqol.api import VisqolApi
+
+TESTDATA = os.path.join(VISQOL_ROOT, "testdata", "conformance_testdata_subset")
+ref_file = os.path.join(TESTDATA, "guitar48_stereo.wav")
+deg_file = os.path.join(TESTDATA, "guitar48_stereo_64kbps_aac.wav")
+
+if not os.path.exists(ref_file):
+    import glob
+
+    testdata_root = os.path.join(VISQOL_ROOT, "testdata")
+    wavs = sorted(glob.glob(os.path.join(testdata_root, "**", "*.wav"), recursive=True))
+    if len(wavs) >= 2:
+        ref_file = wavs[0]
+        deg_file = wavs[1]
+    else:
+        print("   ERROR: No test WAV files found")
+        sys.exit(1)
+
+print(f"   ref: {os.path.basename(ref_file)}")
+print(f"   deg: {os.path.basename(deg_file)}")
+
+v = VisqolApi()
+v.create(mode="audio")
+
+# Run 1: get score (also triggers JIT compilation if not warmed up)
+t0 = time.perf_counter()
+result1 = v.measure(ref_file, deg_file)
+t1 = time.perf_counter()
+print(f"   Run 1: MOS = {result1.moslqo:.6f}  ({t1 - t0:.3f}s)")
+
+# Run 2: steady-state (JIT cached)
+t0 = time.perf_counter()
+result2 = v.measure(ref_file, deg_file)
+t1 = time.perf_counter()
+print(f"   Run 2: MOS = {result2.moslqo:.6f}  ({t1 - t0:.3f}s)")
+
+# Check reproducibility
+diff = abs(result1.moslqo - result2.moslqo)
+print(f"   Run1 vs Run2 diff: {diff:.2e}")
+assert diff < 1e-10, f"Non-reproducible results: diff={diff}"
+print("   ✅ Results are reproducible across runs")
+
+# Check MOS is in a reasonable range
+print(f"   MOS value: {result1.moslqo:.6f}")
+assert 1.0 <= result1.moslqo <= 5.0, f"MOS out of range: {result1.moslqo}"
+print("   ✅ MOS in valid range [1, 5]")
+
+# Run 3: timing
+t0 = time.perf_counter()
+result3 = v.measure(ref_file, deg_file)
+t1 = time.perf_counter()
+print(f"   Run 3: MOS = {result3.moslqo:.6f}  ({t1 - t0:.3f}s)")
+
+print()
+print("=" * 60)
+print("ALL CORRECTNESS CHECKS PASSED ✅")
+print(f"Steady-state latency: {t1 - t0:.3f}s")
+print("=" * 60)

{visqol_python-3.3.6 → visqol_python-3.4.0}/tests/test_quick.py

@@ -10,12 +10,10 @@ import pytest
 from visqol import (
     AudioSignal,
     PatchSimilarityResult,
-    ProgressCallback,
     SimilarityResult,
     VisqolApi,
 )
 
-
 # ── API creation ──
 
 
@@ -126,9 +124,7 @@ class TestMeasureFromArrays:
         rng = np.random.default_rng(42)
         deg = ref + 0.3 * rng.standard_normal(len(ref))
         result = api.measure_from_arrays(ref, deg, sample_rate=sr)
-        assert 1.0 <= result.moslqo <= 5.0, (
-            f"MOS should be in [1, 5], got {result.moslqo:.4f}"
-        )
+        assert 1.0 <= result.moslqo <= 5.0, f"MOS should be in [1, 5], got {result.moslqo:.4f}"
 
 
 # ── Result fields ──
@@ -209,10 +205,12 @@ class TestMeasureBatch:
     def test_batch_nonexistent_files_returns_exceptions(self):
         api = VisqolApi()
         api.create(mode="speech")
-        results = api.measure_batch([
-            ("/nonexistent/a.wav", "/nonexistent/b.wav"),
-            ("/nonexistent/c.wav", "/nonexistent/d.wav"),
-        ])
+        results = api.measure_batch(
+            [
+                ("/nonexistent/a.wav", "/nonexistent/b.wav"),
+                ("/nonexistent/c.wav", "/nonexistent/d.wav"),
+            ]
+        )
         assert len(results) == 2
         assert all(isinstance(r, Exception) for r in results)
 
@@ -246,6 +244,7 @@ class TestVersion:
 
     def test_version_string(self):
         import visqol
+
         assert hasattr(visqol, "__version__")
         assert isinstance(visqol.__version__, str)
         parts = visqol.__version__.split(".")
@@ -254,6 +253,7 @@ class TestVersion:
     def test_public_exports(self):
         """Package should export key classes."""
         import visqol
+
         assert hasattr(visqol, "VisqolApi")
         assert hasattr(visqol, "SimilarityResult")
         assert hasattr(visqol, "AudioSignal")

{visqol_python-3.3.6 → visqol_python-3.4.0}/visqol/__init__.py

@@ -13,7 +13,7 @@ Usage:
     print(f"MOS-LQO: {result.moslqo}")
 """
 
-__version__: str = "3.3.6"
+__version__: str = "3.4.0"
 
 from visqol.api import ProgressCallback, VisqolApi
 from visqol.audio_utils import AudioSignal
@@ -21,9 +21,9 @@ from visqol.nsim import PatchSimilarityResult
 from visqol.visqol_core import SimilarityResult
 
 __all__: list[str] = [
-    "VisqolApi",
-    "SimilarityResult",
     "AudioSignal",
     "PatchSimilarityResult",
     "ProgressCallback",
+    "SimilarityResult",
+    "VisqolApi",
 ]

{visqol_python-3.3.6 → visqol_python-3.4.0}/visqol/__main__.py

@@ -23,39 +23,52 @@ def main() -> None:
         description="ViSQOL - Virtual Speech Quality Objective Listener (Python)",
     )
     parser.add_argument(
-        "--reference", "-r", required=True,
+        "--reference",
+        "-r",
+        required=True,
         help="Path to reference audio file (WAV)",
     )
     parser.add_argument(
-        "--degraded", "-d", required=True,
+        "--degraded",
+        "-d",
+        required=True,
         help="Path to degraded audio file (WAV)",
     )
     parser.add_argument(
-        "--speech_mode", action="store_true",
+        "--speech_mode",
+        action="store_true",
         help="Use speech mode (16 kHz, exponential mapping)",
     )
     parser.add_argument(
-        "--model", default=None,
+        "--model",
+        default=None,
         help="Path to SVR model file (Audio mode only)",
     )
     parser.add_argument(
-        "--search_window", type=int, default=60,
+        "--search_window",
+        type=int,
+        default=60,
         help="Search window radius (default: 60)",
     )
     parser.add_argument(
-        "--unscaled_speech", action="store_true",
+        "--unscaled_speech",
+        action="store_true",
         help="Don't scale speech MOS to max 5.0",
     )
     parser.add_argument(
-        "--no_alignment", action="store_true",
+        "--no_alignment",
+        action="store_true",
         help="Disable global alignment",
     )
     parser.add_argument(
-        "--no_realignment", action="store_true",
+        "--no_realignment",
+        action="store_true",
         help="Disable fine realignment",
     )
     parser.add_argument(
-        "--verbose", "-v", action="store_true",
+        "--verbose",
+        "-v",
+        action="store_true",
         help="Enable verbose output",
     )
 
@@ -105,9 +118,12 @@ def main() -> None:
         for i, p in enumerate(result.patch_sims):
             logger.info(
                 "  Patch %d: sim=%.4f ref=[%.3f-%.3f] deg=[%.3f-%.3f]",
-                i, p.similarity,
-                p.ref_patch_start_time, p.ref_patch_end_time,
-                p.deg_patch_start_time, p.deg_patch_end_time,
+                i,
+                p.similarity,
+                p.ref_patch_start_time,
+                p.ref_patch_end_time,
+                p.deg_patch_start_time,
+                p.deg_patch_end_time,
             )
 
 

{visqol_python-3.3.6 → visqol_python-3.4.0}/visqol/alignment.py

@@ -6,17 +6,13 @@ Corresponds to C++ file: alignment.cc
 
 from __future__ import annotations
 
-from typing import Tuple
-
 import numpy as np
 
 from visqol.audio_utils import AudioSignal
-from visqol.signal_utils import upper_envelope, find_best_lag
+from visqol.signal_utils import find_best_lag, upper_envelope
 
 
-def globally_align(
-    reference: AudioSignal, degraded: AudioSignal
-) -> Tuple[AudioSignal, float]:
+def globally_align(reference: AudioSignal, degraded: AudioSignal) -> tuple[AudioSignal, float]:
     """
     Globally align degraded signal to reference signal.
 
@@ -43,7 +39,7 @@ def globally_align(
 
     if best_lag < 0:
         # Degraded comes before reference: truncate front of degraded
-        new_data = degraded.data[abs(best_lag):]
+        new_data = degraded.data[abs(best_lag) :]
     else:
         # Reference comes before degraded: prepend zeros to degraded
         new_data = np.concatenate([np.zeros(best_lag), degraded.data])
@@ -55,7 +51,7 @@ def globally_align(
 
 def align_and_truncate(
     reference: AudioSignal, degraded: AudioSignal
-) -> Tuple[AudioSignal, AudioSignal, float]:
+) -> tuple[AudioSignal, AudioSignal, float]:
     """
     Align and truncate signals to the same length.
 
@@ -70,15 +66,15 @@ def align_and_truncate(
     deg_data = aligned_deg.data
 
     if len(ref_data) > len(deg_data):
-        ref_data = ref_data[:len(deg_data)]
+        ref_data = ref_data[: len(deg_data)]
     elif len(ref_data) < len(deg_data):
         # For positive lag, the beginning of ref aligns with zeros
         lag_samples = int(lag_seconds * reference.sample_rate)
         if lag_samples > 0:
             ref_data = ref_data[lag_samples:]
-            deg_data = deg_data[lag_samples:lag_samples + len(ref_data)]
+            deg_data = deg_data[lag_samples : lag_samples + len(ref_data)]
         else:
-            deg_data = deg_data[:len(ref_data)]
+            deg_data = deg_data[: len(ref_data)]
 
     # Ensure same length
     min_len = min(len(ref_data), len(deg_data))

{visqol_python-3.3.6 → visqol_python-3.4.0}/visqol/analysis_window.py

@@ -43,7 +43,7 @@ class AnalysisWindow:
 
         self.window_duration: float = window_duration
         self.overlap: float = overlap
-        self.size: int = int(round(sample_rate * window_duration))
+        self.size: int = round(sample_rate * window_duration)
         self._hann_window: NDArray[np.float64] | None = None
 
     @property
@@ -57,9 +57,7 @@ class AnalysisWindow:
         if self._hann_window is None:
             # Match C++ exactly: 0.5 − 0.5 * cos(2π i / (size − 1))
             n = self.size
-            self._hann_window = 0.5 - 0.5 * np.cos(
-                2.0 * np.pi * np.arange(n) / (n - 1)
-            )
+            self._hann_window = 0.5 - 0.5 * np.cos(2.0 * np.pi * np.arange(n) / (n - 1))
         return self._hann_window
 
     def apply_hann_window(self, frame: NDArray[np.float64]) -> NDArray[np.float64]:
@@ -70,7 +68,6 @@ class AnalysisWindow:
         """
         if len(frame) != self.size:
             raise ValueError(
-                f"Frame length ({len(frame)}) does not match "
-                f"window size ({self.size})."
+                f"Frame length ({len(frame)}) does not match window size ({self.size})."
             )
         return frame * self.hann_window