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

visqol_python-3.3.6/CHANGELOG.md

@@ -0,0 +1,55 @@
+# 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.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.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/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to ViSQOL (Python)
+
+Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
+
+## Getting Started
+
+1. **Fork** the repository on GitHub
+2. **Clone** your fork locally:
+   ```bash
+   git clone https://github.com/<your-username>/visqol-python.git
+   cd visqol-python
+   ```
+3. **Create a branch** for your changes:
+   ```bash
+   git checkout -b feature/my-improvement
+   ```
+
+## Development Setup
+
+```bash
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # macOS/Linux
+# venv\Scripts\activate   # Windows
+
+# Install in development mode with test dependencies
+pip install -e ".[test]"
+```
+
+## Running Tests
+
+```bash
+# Quick smoke tests (no external data needed)
+pytest tests/test_quick.py -v
+
+# Full conformance tests (requires testdata directory)
+pytest tests/test_conformance.py -v --testdata /path/to/visqol/testdata
+```
+
+## Code Style
+
+- **Type hints**: All public functions and methods must include type annotations.
+- **Docstrings**: Use Google-style docstrings for all public APIs.
+- **Imports**: Use `from __future__ import annotations` at the top of every module.
+- Keep line length ≤ 99 characters where practical.
+
+## Making Changes
+
+1. Write clean, well-documented code with type hints.
+2. Add or update tests for any new functionality.
+3. Ensure all existing tests still pass.
+4. Update `CHANGELOG.md` under an `[Unreleased]` section.
+
+## Pull Request Process
+
+1. Update the `CHANGELOG.md` with details of your changes.
+2. Ensure all tests pass locally.
+3. Submit a pull request with a clear description of the changes.
+4. Link any relevant issues.
+
+## Reporting Bugs
+
+Please open an [issue](https://github.com/talker93/visqol-python/issues) with:
+
+- A clear, descriptive title
+- Steps to reproduce the problem
+- Expected vs. actual behavior
+- Python version and OS
+- Relevant audio file details (sample rate, duration, format)
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). The single source of truth for the version number is `visqol/__init__.py`.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).

{visqol_python-3.3.5 → visqol_python-3.3.6}/MANIFEST.in

@@ -1,4 +1,5 @@
 include README.md
 include LICENSE
-include requirements.txt
+include CHANGELOG.md
+include CONTRIBUTING.md
 recursive-include visqol/model *.txt

{visqol_python-3.3.5/visqol_python.egg-info → visqol_python-3.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.3.5
+Version: 3.3.6
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -30,6 +30,10 @@ Requires-Dist: soundfile>=0.10
 Requires-Dist: libsvm-official>=3.25
 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"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -103,6 +107,33 @@ result = api.measure_from_arrays(ref, deg, sample_rate=sr)
 print(f"MOS-LQO: {result.moslqo:.4f}")
 ```
 
+### Batch Evaluation
+
+```python
+from visqol import VisqolApi
+
+api = VisqolApi()
+api.create(mode="audio")
+
+file_pairs = [
+    ("ref1.wav", "deg1.wav"),
+    ("ref2.wav", "deg2.wav"),
+    ("ref3.wav", "deg3.wav"),
+]
+
+# Optional progress callback
+results = api.measure_batch(
+    file_pairs,
+    progress_callback=lambda done, total: print(f"{done}/{total}"),
+)
+
+for pair, result in zip(file_pairs, results):
+    if isinstance(result, Exception):
+        print(f"{pair}: FAILED — {result}")
+    else:
+        print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+```
+
 ### Command Line
 
 ```bash

{visqol_python-3.3.5 → visqol_python-3.3.6}/README.md

@@ -69,6 +69,33 @@ result = api.measure_from_arrays(ref, deg, sample_rate=sr)
 print(f"MOS-LQO: {result.moslqo:.4f}")
 ```
 
+### Batch Evaluation
+
+```python
+from visqol import VisqolApi
+
+api = VisqolApi()
+api.create(mode="audio")
+
+file_pairs = [
+    ("ref1.wav", "deg1.wav"),
+    ("ref2.wav", "deg2.wav"),
+    ("ref3.wav", "deg3.wav"),
+]
+
+# Optional progress callback
+results = api.measure_batch(
+    file_pairs,
+    progress_callback=lambda done, total: print(f"{done}/{total}"),
+)
+
+for pair, result in zip(file_pairs, results):
+    if isinstance(result, Exception):
+        print(f"{pair}: FAILED — {result}")
+    else:
+        print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+```
+
 ### Command Line
 
 ```bash

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

@@ -38,6 +38,11 @@ dependencies = [
 
 [project.optional-dependencies]
 test = ["pytest>=7.0"]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4",
+    "mypy>=1.8",
+]
 
 [project.urls]
 Homepage = "https://github.com/talker93/visqol-python"
@@ -61,7 +66,31 @@ visqol = ["model/*.txt", "py.typed"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.ruff]
+target-version = "py39"
+line-length = 95
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific rules
+]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.ruff.lint.isort]
+known-first-party = ["visqol"]
+
 [tool.mypy]
 strict = true
 warn_return_any = true
 warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = ["svmutil.*", "libsvm.*", "soundfile.*"]
+ignore_missing_imports = true

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

@@ -7,7 +7,13 @@ These tests verify basic API functionality without requiring external testdata.
 import numpy as np
 import pytest
 
-from visqol import VisqolApi, SimilarityResult, AudioSignal
+from visqol import (
+    AudioSignal,
+    PatchSimilarityResult,
+    ProgressCallback,
+    SimilarityResult,
+    VisqolApi,
+)
 
 
 # ── API creation ──
@@ -147,6 +153,91 @@ class TestResultFields:
         assert hasattr(result, "patch_sims")
 
 
+# ── __repr__ / __str__ ──
+
+
+class TestReprStr:
+    """Test readable string representations."""
+
+    def test_audio_signal_repr(self):
+        sig = AudioSignal(np.zeros(16000), 16000)
+        r = repr(sig)
+        assert "AudioSignal" in r
+        assert "16000" in r
+        assert "1.000" in r
+
+    def test_audio_signal_str(self):
+        sig = AudioSignal(np.zeros(48000), 48000)
+        s = str(sig)
+        assert "1.000s" in s
+        assert "48000" in s
+
+    def test_similarity_result_str(self):
+        res = SimilarityResult(moslqo=4.5, vnsim=0.95)
+        s = str(res)
+        assert "4.5" in s
+        assert "0.95" in s
+
+    def test_similarity_result_repr(self):
+        res = SimilarityResult(moslqo=4.5, vnsim=0.95)
+        r = repr(res)
+        assert "SimilarityResult" in r
+        assert "moslqo" in r
+
+    def test_patch_similarity_result_str(self):
+        p = PatchSimilarityResult(similarity=0.85)
+        s = str(p)
+        assert "0.85" in s
+
+    def test_patch_similarity_result_repr(self):
+        p = PatchSimilarityResult(similarity=0.85)
+        r = repr(p)
+        assert "PatchSimilarityResult" in r
+
+
+# ── measure_batch ──
+
+
+class TestMeasureBatch:
+    """Test batch evaluation API."""
+
+    def test_batch_before_create_raises(self):
+        api = VisqolApi()
+        with pytest.raises(RuntimeError, match="create"):
+            api.measure_batch([("/a.wav", "/b.wav")])
+
+    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"),
+        ])
+        assert len(results) == 2
+        assert all(isinstance(r, Exception) for r in results)
+
+    def test_batch_progress_callback(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        progress_log: list[tuple[int, int]] = []
+
+        def cb(done: int, total: int) -> None:
+            progress_log.append((done, total))
+
+        results = api.measure_batch(
+            [("/nonexistent/a.wav", "/nonexistent/b.wav")],
+            progress_callback=cb,
+        )
+        assert len(results) == 1
+        assert progress_log == [(1, 1)]
+
+    def test_batch_empty(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        results = api.measure_batch([])
+        assert results == []
+
+
 # ── Package metadata ──
 
 
@@ -166,3 +257,5 @@ class TestVersion:
         assert hasattr(visqol, "VisqolApi")
         assert hasattr(visqol, "SimilarityResult")
         assert hasattr(visqol, "AudioSignal")
+        assert hasattr(visqol, "PatchSimilarityResult")
+        assert hasattr(visqol, "ProgressCallback")

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

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

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

@@ -9,11 +9,13 @@ Usage::
 from __future__ import annotations
 
 import argparse
-import sys
 import logging
+import sys
 
 from visqol.api import VisqolApi
 
+logger = logging.getLogger("visqol")
+
 
 def main() -> None:
     """Entry point for the ``visqol`` CLI."""
@@ -61,7 +63,11 @@ def main() -> None:
 
     # Setup logging
     level = logging.DEBUG if args.verbose else logging.WARNING
-    logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+    )
 
     # Run ViSQOL
     mode: str = "speech" if args.speech_mode else "audio"
@@ -79,30 +85,29 @@ def main() -> None:
 
         result = api.measure(args.reference, args.degraded)
 
-    except FileNotFoundError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
-    except ValueError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
-    except RuntimeError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
+    except (FileNotFoundError, ValueError, RuntimeError) as exc:
+        logger.error("%s", exc)
         sys.exit(1)
+    except Exception as exc:
+        logger.error("Unexpected error: %s", exc)
+        sys.exit(2)
 
     # Output results
     print(f"MOS-LQO:      {result.moslqo:.6f}")
     print(f"VNSIM:        {result.vnsim:.6f}")
+
     if args.verbose:
-        print(f"FVNSIM:       {result.fvnsim}")
-        print(f"FVNSIM10:     {result.fvnsim10}")
-        print(f"FSTDNSIM:     {result.fstdnsim}")
-        print(f"FVDEGENERGY:  {result.fvdegenergy}")
-        print(f"Patches:      {len(result.patch_sims)}")
+        logger.info("FVNSIM:       %s", result.fvnsim)
+        logger.info("FVNSIM10:     %s", result.fvnsim10)
+        logger.info("FSTDNSIM:     %s", result.fstdnsim)
+        logger.info("FVDEGENERGY:  %s", result.fvdegenergy)
+        logger.info("Patches:      %d", len(result.patch_sims))
         for i, p in enumerate(result.patch_sims):
-            print(
-                f"  Patch {i}: sim={p.similarity:.4f} "
-                f"ref=[{p.ref_patch_start_time:.3f}-{p.ref_patch_end_time:.3f}] "
-                f"deg=[{p.deg_patch_start_time:.3f}-{p.deg_patch_end_time:.3f}]"
+            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,
             )
 
 

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol/api.py

@@ -8,8 +8,10 @@ Corresponds to C++ file: visqol_api.cc
 
 from __future__ import annotations
 
+import logging
 import os
-from typing import Optional
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import Callable, List, Optional, Sequence, Tuple, Union
 
 import numpy as np
 from numpy.typing import NDArray
@@ -18,6 +20,8 @@ from visqol.audio_utils import AudioSignal
 from visqol.visqol_manager import VisqolManager
 from visqol.visqol_core import SimilarityResult
 
+logger = logging.getLogger(__name__)
+
 # Valid mode names
 _VALID_MODES = frozenset({"audio", "speech"})
 
@@ -25,6 +29,9 @@ _VALID_MODES = frozenset({"audio", "speech"})
 _DEFAULT_MODEL_DIR: str = os.path.join(os.path.dirname(__file__), "model")
 _DEFAULT_SVR_MODEL: str = os.path.join(_DEFAULT_MODEL_DIR, "libsvm_nu_svr_model.txt")
 
+# Type alias for progress callback: (completed_count, total_count) -> None
+ProgressCallback = Callable[[int, int], None]
+
 
 class VisqolApi:
     """
@@ -41,6 +48,7 @@ class VisqolApi:
     def __init__(self) -> None:
         self._manager: VisqolManager = VisqolManager()
         self._is_created: bool = False
+        self._create_kwargs: dict[str, object] = {}
 
     def create(
         self,
@@ -90,14 +98,17 @@ class VisqolApi:
                 f"SVR model file not found: {model_path}"
             )
 
-        self._manager.init(
-            model_path=model_path or "",
-            use_speech_mode=use_speech_mode,
-            use_unscaled_speech=use_unscaled_speech,
-            search_window=search_window,
-            disable_global_alignment=disable_global_alignment,
-            disable_realignment=disable_realignment,
-        )
+        # Store kwargs for batch mode (subprocess recreation)
+        self._create_kwargs = {
+            "model_path": model_path or "",
+            "use_speech_mode": use_speech_mode,
+            "use_unscaled_speech": use_unscaled_speech,
+            "search_window": search_window,
+            "disable_global_alignment": disable_global_alignment,
+            "disable_realignment": disable_realignment,
+        }
+
+        self._manager.init(**self._create_kwargs)  # type: ignore[arg-type]
         self._is_created = True
 
     def measure(self, ref_path: str, deg_path: str) -> SimilarityResult:
@@ -169,6 +180,45 @@ class VisqolApi:
         deg_signal = AudioSignal(deg_array, sample_rate)
         return self._manager.run_from_signals(ref_signal, deg_signal)
 
+    def measure_batch(
+        self,
+        file_pairs: Sequence[Tuple[str, str]],
+        *,
+        progress_callback: Optional[ProgressCallback] = None,
+    ) -> List[Union[SimilarityResult, Exception]]:
+        """
+        Evaluate multiple file pairs sequentially.
+
+        Args:
+            file_pairs: Sequence of ``(ref_path, deg_path)`` tuples.
+            progress_callback: Optional ``(completed, total) -> None`` callback
+                invoked after each pair is processed.
+
+        Returns:
+            List of :class:`SimilarityResult` (on success) or :class:`Exception`
+            (on failure) for each pair, in the same order as *file_pairs*.
+
+        Raises:
+            RuntimeError: If :meth:`create` has not been called.
+        """
+        self._ensure_created()
+        total = len(file_pairs)
+        results: List[Union[SimilarityResult, Exception]] = []
+
+        for idx, (ref_path, deg_path) in enumerate(file_pairs):
+            try:
+                result = self.measure(ref_path, deg_path)
+                results.append(result)
+            except Exception as exc:
+                results.append(exc)
+                logger.warning(
+                    "Pair %d/%d failed: %s", idx + 1, total, exc,
+                )
+            if progress_callback is not None:
+                progress_callback(idx + 1, total)
+
+        return results
+
     # ------------------------------------------------------------------
     # Private helpers
     # ------------------------------------------------------------------

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol/audio_utils.py

@@ -53,6 +53,16 @@ class AudioSignal:
     def __len__(self) -> int:
         return len(self.data)
 
+    def __repr__(self) -> str:
+        return (
+            f"AudioSignal(samples={self.num_samples}, "
+            f"sample_rate={self.sample_rate}, "
+            f"duration={self.duration:.3f}s)"
+        )
+
+    def __str__(self) -> str:
+        return f"AudioSignal({self.duration:.3f}s @ {self.sample_rate} Hz)"
+
 
 def load_audio(path: str) -> Tuple[NDArray[np.float64], int]:
     """

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol/gammatone.py

@@ -174,21 +174,6 @@ def make_erb_filters(
     return ErbFiltersResult(center_freqs=cf, filter_coeffs=filter_coeffs)
 
 
-def _iir_filter(
-    b: NDArray[np.float64],
-    a: NDArray[np.float64],
-    signal: NDArray[np.float64],
-    zi: NDArray[np.float64],
-) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """
-    Apply IIR filter (Direct Form II transposed).
-
-    Matches C++ ``SignalFilter::Filter``.
-    """
-    y, zf = lfilter(b, a, signal, zi=zi)
-    return y, zf
-
-
 class GammatoneFilterBank:
     """
     Gammatone filterbank that applies 4-stage cascaded IIR filtering.
@@ -226,9 +211,9 @@ class GammatoneFilterBank:
         """
         assert self._conditions is not None, "Call reset_conditions() first"
 
-        output = np.zeros((self.num_bands, len(signal)))
+        nb = self.num_bands
 
-        # Extract coefficient vectors
+        # Extract coefficient vectors (all bands at once)
         A0 = filter_coeffs[0]
         A11 = filter_coeffs[1]
         A12 = filter_coeffs[2]
@@ -240,36 +225,28 @@ class GammatoneFilterBank:
         B2 = filter_coeffs[8]
         gain = filter_coeffs[9]
 
-        for chan in range(self.num_bands):
-            # Stage 1: normalize by gain
-            a1_b = np.array([
-                A0[chan] / gain[chan],
-                A11[chan] / gain[chan],
-                A2[chan] / gain[chan],
-            ])
-            # Stage 2
-            a2_b = np.array([A0[chan], A12[chan], A2[chan]])
-            # Stage 3
-            a3_b = np.array([A0[chan], A13[chan], A2[chan]])
-            # Stage 4
-            a4_b = np.array([A0[chan], A14[chan], A2[chan]])
-
-            # Denominator is the same for all 4 stages
-            denom = np.array([B0[chan], B1[chan], B2[chan]])
-
-            # 4-stage cascade
-            y, zf = lfilter(a1_b, denom, signal, zi=self._conditions[0][chan])
-            self._conditions[0][chan] = zf
-
-            y, zf = lfilter(a2_b, denom, y, zi=self._conditions[1][chan])
-            self._conditions[1][chan] = zf
-
-            y, zf = lfilter(a3_b, denom, y, zi=self._conditions[2][chan])
-            self._conditions[2][chan] = zf
-
-            y, zf = lfilter(a4_b, denom, y, zi=self._conditions[3][chan])
-            self._conditions[3][chan] = zf
-
+        # Pre-build numerator arrays for all 4 stages × all channels
+        # Stage 1: normalize by gain
+        b1 = np.column_stack([A0 / gain, A11 / gain, A2 / gain])  # (nb, 3)
+        # Stage 2-4
+        b2 = np.column_stack([A0, A12, A2])  # (nb, 3)
+        b3 = np.column_stack([A0, A13, A2])  # (nb, 3)
+        b4 = np.column_stack([A0, A14, A2])  # (nb, 3)
+
+        # Denominator is the same for all 4 stages (per channel)
+        denom = np.column_stack([B0, B1, B2])  # (nb, 3)
+
+        # Process all channels with vectorised per-channel lfilter
+        output = np.empty((nb, len(signal)), dtype=np.float64)
+        stages_b = [b1, b2, b3, b4]
+
+        for chan in range(nb):
+            y = signal
+            for stage_idx, sb in enumerate(stages_b):
+                y, zf = lfilter(
+                    sb[chan], denom[chan], y, zi=self._conditions[stage_idx][chan],
+                )
+                self._conditions[stage_idx][chan] = zf
             output[chan] = y
 
         return output
@@ -303,6 +280,11 @@ class Spectrogram:
     def num_frames(self) -> int:
         return self.data.shape[1]
 
+    def __repr__(self) -> str:
+        return (
+            f"Spectrogram(bands={self.num_bands}, frames={self.num_frames})"
+        )
+
 
 def convert_to_db(matrix: NDArray[np.float64]) -> NDArray[np.float64]:
     """
@@ -343,16 +325,16 @@ def prepare_spectrograms_for_comparison(
     ref_db = np.maximum(ref_db, NOISE_FLOOR_ABSOLUTE_DB)
     deg_db = np.maximum(deg_db, NOISE_FLOOR_ABSOLUTE_DB)
 
-    # 3. Per-frame relative noise floor
+    # 3. Per-frame relative noise floor (vectorised)
     min_cols = min(ref_db.shape[1], deg_db.shape[1])
-    for i in range(min_cols):
-        our_max = np.max(ref_db[:, i])
-        other_max = np.max(deg_db[:, i])
-        any_max = max(float(our_max), float(other_max))
-        floor_db = any_max - NOISE_FLOOR_RELATIVE_TO_PEAK_DB
-
-        ref_db[:, i] = np.maximum(ref_db[:, i], floor_db)
-        deg_db[:, i] = np.maximum(deg_db[:, i], floor_db)
+    ref_view = ref_db[:, :min_cols]
+    deg_view = deg_db[:, :min_cols]
+    ref_max = np.max(ref_view, axis=0)  # (min_cols,)
+    deg_max = np.max(deg_view, axis=0)  # (min_cols,)
+    any_max = np.maximum(ref_max, deg_max)
+    floor_db = any_max - NOISE_FLOOR_RELATIVE_TO_PEAK_DB  # (min_cols,)
+    ref_db[:, :min_cols] = np.maximum(ref_view, floor_db[np.newaxis, :])
+    deg_db[:, :min_cols] = np.maximum(deg_view, floor_db[np.newaxis, :])
 
     # 4. Global normalization: subtract global minimum
     lowest = min(float(np.min(ref_db)), float(np.min(deg_db)))

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol/nsim.py

@@ -51,6 +51,19 @@ class PatchSimilarityResult:
     deg_patch_start_time: float = 0.0
     deg_patch_end_time: float = 0.0
 
+    def __str__(self) -> str:
+        return (
+            f"PatchSimilarityResult(sim={self.similarity:.4f}, "
+            f"ref=[{self.ref_patch_start_time:.3f}-{self.ref_patch_end_time:.3f}], "
+            f"deg=[{self.deg_patch_start_time:.3f}-{self.deg_patch_end_time:.3f}])"
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"PatchSimilarityResult(similarity={self.similarity!r}, "
+            f"freq_band_means=<{len(self.freq_band_means)} bands>)"
+        )
+
 
 def _valid_2d_conv_with_boundary(
     kernel: NDArray[np.float64], matrix: NDArray[np.float64]

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol/visqol_core.py

@@ -43,6 +43,16 @@ class SimilarityResult:
     )
     patch_sims: List[PatchSimilarityResult] = field(default_factory=list)
 
+    def __str__(self) -> str:
+        return f"SimilarityResult(moslqo={self.moslqo:.4f}, vnsim={self.vnsim:.4f})"
+
+    def __repr__(self) -> str:
+        return (
+            f"SimilarityResult(moslqo={self.moslqo!r}, vnsim={self.vnsim!r}, "
+            f"fvnsim=<{len(self.fvnsim)} bands>, "
+            f"patch_sims=<{len(self.patch_sims)} patches>)"
+        )
+
 
 # ---------------------------------------------------------------------------
 # Helper functions

{visqol_python-3.3.5 → visqol_python-3.3.6/visqol_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.3.5
+Version: 3.3.6
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -30,6 +30,10 @@ Requires-Dist: soundfile>=0.10
 Requires-Dist: libsvm-official>=3.25
 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"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -103,6 +107,33 @@ result = api.measure_from_arrays(ref, deg, sample_rate=sr)
 print(f"MOS-LQO: {result.moslqo:.4f}")
 ```
 
+### Batch Evaluation
+
+```python
+from visqol import VisqolApi
+
+api = VisqolApi()
+api.create(mode="audio")
+
+file_pairs = [
+    ("ref1.wav", "deg1.wav"),
+    ("ref2.wav", "deg2.wav"),
+    ("ref3.wav", "deg3.wav"),
+]
+
+# Optional progress callback
+results = api.measure_batch(
+    file_pairs,
+    progress_callback=lambda done, total: print(f"{done}/{total}"),
+)
+
+for pair, result in zip(file_pairs, results):
+    if isinstance(result, Exception):
+        print(f"{pair}: FAILED — {result}")
+    else:
+        print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+```
+
 ### Command Line
 
 ```bash

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol_python.egg-info/SOURCES.txt

@@ -1,8 +1,9 @@
+CHANGELOG.md
+CONTRIBUTING.md
 LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-requirements.txt
 tests/test_conformance.py
 tests/test_quick.py
 visqol/__init__.py

{visqol_python-3.3.5 → visqol_python-3.3.6}/visqol_python.egg-info/requires.txt

@@ -3,5 +3,10 @@ scipy>=1.7
 soundfile>=0.10
 libsvm-official>=3.25
 
+[dev]
+pytest>=7.0
+ruff>=0.4
+mypy>=1.8
+
 [test]
 pytest>=7.0

visqol_python-3.3.5/requirements.txt

@@ -1,4 +0,0 @@
-numpy>=1.20
-scipy>=1.7
-soundfile>=0.10
-libsvm-official>=3.25