visqol-python 3.3.4__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.4 → 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.4/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.4
+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.4 → 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.4 → 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"
@@ -56,7 +61,36 @@ version = {attr = "visqol.__version__"}
 exclude = ["tests*"]
 
 [tool.setuptools.package-data]
-visqol = ["model/*.txt"]
+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.6/tests/test_quick.py

@@ -0,0 +1,261 @@
+"""
+Quick smoke tests for ViSQOL Python.
+
+These tests verify basic API functionality without requiring external testdata.
+"""
+
+import numpy as np
+import pytest
+
+from visqol import (
+    AudioSignal,
+    PatchSimilarityResult,
+    ProgressCallback,
+    SimilarityResult,
+    VisqolApi,
+)
+
+
+# ── API creation ──
+
+
+class TestApiCreation:
+    """Test that VisqolApi can be created in different modes."""
+
+    def test_create_audio_mode(self):
+        api = VisqolApi()
+        api.create(mode="audio")
+
+    def test_create_speech_mode(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+
+    def test_create_default_mode(self):
+        """Default mode (no argument) should work as audio mode."""
+        api = VisqolApi()
+        api.create()
+
+    def test_create_case_insensitive(self):
+        api = VisqolApi()
+        api.create(mode="SPEECH")
+
+    def test_create_invalid_mode_raises(self):
+        api = VisqolApi()
+        with pytest.raises(ValueError, match="Invalid mode"):
+            api.create(mode="invalid")
+
+    def test_create_negative_search_window_raises(self):
+        api = VisqolApi()
+        with pytest.raises(ValueError, match="search_window"):
+            api.create(search_window=-1)
+
+    def test_create_missing_model_raises(self):
+        api = VisqolApi()
+        with pytest.raises(FileNotFoundError):
+            api.create(mode="audio", model_path="/nonexistent/model.txt")
+
+
+# ── Measure guards ──
+
+
+class TestMeasureGuards:
+    """Test that measure() raises helpful errors for bad inputs."""
+
+    def test_measure_before_create_raises(self):
+        api = VisqolApi()
+        with pytest.raises(RuntimeError, match="create"):
+            api.measure("a.wav", "b.wav")
+
+    def test_measure_nonexistent_ref_raises(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        with pytest.raises(FileNotFoundError, match="Reference"):
+            api.measure("/nonexistent/ref.wav", "/nonexistent/deg.wav")
+
+    def test_measure_from_arrays_before_create_raises(self):
+        api = VisqolApi()
+        with pytest.raises(RuntimeError, match="create"):
+            api.measure_from_arrays(np.zeros(100), np.zeros(100), 16000)
+
+    def test_measure_from_arrays_bad_type_raises(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        with pytest.raises(TypeError, match="numpy array"):
+            api.measure_from_arrays([1, 2, 3], np.zeros(100), 16000)  # type: ignore[arg-type]
+
+    def test_measure_from_arrays_empty_raises(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        with pytest.raises(ValueError, match="empty"):
+            api.measure_from_arrays(np.array([]), np.zeros(100), 16000)
+
+    def test_measure_from_arrays_bad_sr_raises(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        with pytest.raises(ValueError, match="sample_rate"):
+            api.measure_from_arrays(np.zeros(100), np.zeros(100), 0)
+
+
+# ── measure_from_arrays ──
+
+
+class TestMeasureFromArrays:
+    """Test measure_from_arrays with synthetic signals."""
+
+    def test_identical_signal_high_score(self):
+        """Identical signals should produce a high MOS score."""
+        api = VisqolApi()
+        api.create(mode="speech")
+        sr = 16000
+        duration = 3.0
+        t = np.linspace(0, duration, int(sr * duration), endpoint=False)
+        signal = 0.5 * np.sin(2 * np.pi * 440 * t)
+        result = api.measure_from_arrays(signal, signal, sample_rate=sr)
+        assert result.moslqo >= 4.0, (
+            f"Identical signal should give MOS >= 4.0, got {result.moslqo:.4f}"
+        )
+
+    def test_degraded_signal_lower_score(self):
+        """Adding noise to a signal should produce a lower MOS score."""
+        api = VisqolApi()
+        api.create(mode="speech")
+        sr = 16000
+        duration = 3.0
+        t = np.linspace(0, duration, int(sr * duration), endpoint=False)
+        ref = 0.5 * np.sin(2 * np.pi * 440 * t)
+        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}"
+        )
+
+
+# ── Result fields ──
+
+
+class TestResultFields:
+    """Test that SimilarityResult has all expected fields."""
+
+    def test_result_has_expected_fields(self):
+        api = VisqolApi()
+        api.create(mode="speech")
+        sr = 16000
+        duration = 3.0
+        t = np.linspace(0, duration, int(sr * duration), endpoint=False)
+        signal = 0.5 * np.sin(2 * np.pi * 440 * t)
+        result = api.measure_from_arrays(signal, signal, sample_rate=sr)
+        assert hasattr(result, "moslqo")
+        assert hasattr(result, "vnsim")
+        assert hasattr(result, "fvnsim")
+        assert hasattr(result, "fstdnsim")
+        assert hasattr(result, "fvdegenergy")
+        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 ──
+
+
+class TestVersion:
+    """Test package version is accessible."""
+
+    def test_version_string(self):
+        import visqol
+        assert hasattr(visqol, "__version__")
+        assert isinstance(visqol.__version__, str)
+        parts = visqol.__version__.split(".")
+        assert len(parts) >= 2, "Version should have at least major.minor"
+
+    def test_public_exports(self):
+        """Package should export key classes."""
+        import visqol
+        assert hasattr(visqol, "VisqolApi")
+        assert hasattr(visqol, "SimilarityResult")
+        assert hasattr(visqol, "AudioSignal")
+        assert hasattr(visqol, "PatchSimilarityResult")
+        assert hasattr(visqol, "ProgressCallback")

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

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

visqol_python-3.3.6/visqol/__main__.py

@@ -0,0 +1,115 @@
+"""
+ViSQOL command-line interface.
+
+Usage::
+
+    python -m visqol --reference ref.wav --degraded deg.wav [--speech_mode]
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from visqol.api import VisqolApi
+
+logger = logging.getLogger("visqol")
+
+
+def main() -> None:
+    """Entry point for the ``visqol`` CLI."""
+    parser = argparse.ArgumentParser(
+        description="ViSQOL - Virtual Speech Quality Objective Listener (Python)",
+    )
+    parser.add_argument(
+        "--reference", "-r", required=True,
+        help="Path to reference audio file (WAV)",
+    )
+    parser.add_argument(
+        "--degraded", "-d", required=True,
+        help="Path to degraded audio file (WAV)",
+    )
+    parser.add_argument(
+        "--speech_mode", action="store_true",
+        help="Use speech mode (16 kHz, exponential mapping)",
+    )
+    parser.add_argument(
+        "--model", default=None,
+        help="Path to SVR model file (Audio mode only)",
+    )
+    parser.add_argument(
+        "--search_window", type=int, default=60,
+        help="Search window radius (default: 60)",
+    )
+    parser.add_argument(
+        "--unscaled_speech", action="store_true",
+        help="Don't scale speech MOS to max 5.0",
+    )
+    parser.add_argument(
+        "--no_alignment", action="store_true",
+        help="Disable global alignment",
+    )
+    parser.add_argument(
+        "--no_realignment", action="store_true",
+        help="Disable fine realignment",
+    )
+    parser.add_argument(
+        "--verbose", "-v", action="store_true",
+        help="Enable verbose output",
+    )
+
+    args = parser.parse_args()
+
+    # Setup logging
+    level = logging.DEBUG if args.verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    # Run ViSQOL
+    mode: str = "speech" if args.speech_mode else "audio"
+
+    try:
+        api = VisqolApi()
+        api.create(
+            mode=mode,
+            model_path=args.model,
+            search_window=args.search_window,
+            use_unscaled_speech=args.unscaled_speech,
+            disable_global_alignment=args.no_alignment,
+            disable_realignment=args.no_realignment,
+        )
+
+        result = api.measure(args.reference, args.degraded)
+
+    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:
+        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):
+            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,
+            )
+
+
+if __name__ == "__main__":
+    main()