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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.3.4
+Version: 3.3.5
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0

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

@@ -56,7 +56,12 @@ 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.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true

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

@@ -7,7 +7,10 @@ These tests verify basic API functionality without requiring external testdata.
 import numpy as np
 import pytest
 
-from visqol import VisqolApi
+from visqol import VisqolApi, SimilarityResult, AudioSignal
+
+
+# ── API creation ──
 
 
 class TestApiCreation:
@@ -26,6 +29,69 @@ class TestApiCreation:
         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."""
@@ -59,6 +125,9 @@ class TestMeasureFromArrays:
         )
 
 
+# ── Result fields ──
+
+
 class TestResultFields:
     """Test that SimilarityResult has all expected fields."""
 
@@ -78,6 +147,9 @@ class TestResultFields:
         assert hasattr(result, "patch_sims")
 
 
+# ── Package metadata ──
+
+
 class TestVersion:
     """Test package version is accessible."""
 
@@ -87,3 +159,10 @@ class TestVersion:
         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")

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

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

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

@@ -1,10 +1,13 @@
 """
 ViSQOL command-line interface.
 
-Usage:
+Usage::
+
     python -m visqol --reference ref.wav --degraded deg.wav [--speech_mode]
 """
 
+from __future__ import annotations
+
 import argparse
 import sys
 import logging
@@ -12,45 +15,46 @@ import logging
 from visqol.api import VisqolApi
 
 
-def main():
+def main() -> None:
+    """Entry point for the ``visqol`` CLI."""
     parser = argparse.ArgumentParser(
-        description="ViSQOL - Virtual Speech Quality Objective Listener (Python)"
+        description="ViSQOL - Virtual Speech Quality Objective Listener (Python)",
     )
     parser.add_argument(
         "--reference", "-r", required=True,
-        help="Path to reference audio file (WAV)"
+        help="Path to reference audio file (WAV)",
     )
     parser.add_argument(
         "--degraded", "-d", required=True,
-        help="Path to degraded audio file (WAV)"
+        help="Path to degraded audio file (WAV)",
     )
     parser.add_argument(
         "--speech_mode", action="store_true",
-        help="Use speech mode (16kHz, exponential mapping)"
+        help="Use speech mode (16 kHz, exponential mapping)",
     )
     parser.add_argument(
         "--model", default=None,
-        help="Path to SVR model file (Audio mode only)"
+        help="Path to SVR model file (Audio mode only)",
     )
     parser.add_argument(
         "--search_window", type=int, default=60,
-        help="Search window radius (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"
+        help="Don't scale speech MOS to max 5.0",
     )
     parser.add_argument(
         "--no_alignment", action="store_true",
-        help="Disable global alignment"
+        help="Disable global alignment",
     )
     parser.add_argument(
         "--no_realignment", action="store_true",
-        help="Disable fine realignment"
+        help="Disable fine realignment",
     )
     parser.add_argument(
         "--verbose", "-v", action="store_true",
-        help="Enable verbose output"
+        help="Enable verbose output",
     )
 
     args = parser.parse_args()
@@ -60,18 +64,30 @@ def main():
     logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
 
     # Run ViSQOL
-    mode = "speech" if args.speech_mode else "audio"
-    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,
-    )
+    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)
 
-    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)
+        sys.exit(1)
 
     # Output results
     print(f"MOS-LQO:      {result.moslqo:.6f}")
@@ -83,9 +99,11 @@ def main():
         print(f"FVDEGENERGY:  {result.fvdegenergy}")
         print(f"Patches:      {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}]")
+            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}]"
+            )
 
 
 if __name__ == "__main__":

{visqol_python-3.3.4 → visqol_python-3.3.5}/visqol/alignment.py

@@ -4,31 +4,38 @@ Global signal alignment using upper envelope cross-correlation.
 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
 
 
-def globally_align(reference: AudioSignal, degraded: AudioSignal) -> tuple:
+def globally_align(
+    reference: AudioSignal, degraded: AudioSignal
+) -> Tuple[AudioSignal, float]:
     """
     Globally align degraded signal to reference signal.
 
     Uses upper envelope cross-correlation to find the best time-domain lag,
     then shifts the degraded signal accordingly.
 
-    Matches C++ Alignment::GloballyAlign.
+    Matches C++ ``Alignment::GloballyAlign``.
 
     Args:
         reference: Reference audio signal.
         degraded: Degraded audio signal.
 
     Returns:
-        Tuple of (aligned_degraded: AudioSignal, lag_seconds: float).
+        Tuple of ``(aligned_degraded, lag_seconds)``.
     """
     ref_env = upper_envelope(reference.data)
     deg_env = upper_envelope(degraded.data)
 
-    best_lag = find_best_lag(ref_env, deg_env)
+    best_lag: int = find_best_lag(ref_env, deg_env)
 
     # Limit lag to half the reference length
     if best_lag == 0 or abs(best_lag) > len(reference.data) / 2.0:
@@ -42,19 +49,20 @@ def globally_align(reference: AudioSignal, degraded: AudioSignal) -> tuple:
         new_data = np.concatenate([np.zeros(best_lag), degraded.data])
 
     aligned_signal = AudioSignal(new_data, degraded.sample_rate)
-    lag_seconds = best_lag / float(degraded.sample_rate)
+    lag_seconds: float = best_lag / float(degraded.sample_rate)
     return aligned_signal, lag_seconds
 
 
-def align_and_truncate(reference: AudioSignal,
-                       degraded: AudioSignal) -> tuple:
+def align_and_truncate(
+    reference: AudioSignal, degraded: AudioSignal
+) -> Tuple[AudioSignal, AudioSignal, float]:
     """
     Align and truncate signals to the same length.
 
-    Matches C++ Alignment::AlignAndTruncate.
+    Matches C++ ``Alignment::AlignAndTruncate``.
 
     Returns:
-        Tuple of (aligned_ref: AudioSignal, aligned_deg: AudioSignal, lag_seconds: float).
+        Tuple of ``(aligned_ref, aligned_deg, lag_seconds)``.
     """
     aligned_deg, lag_seconds = globally_align(reference, degraded)
 
@@ -77,6 +85,8 @@ def align_and_truncate(reference: AudioSignal,
     ref_data = ref_data[:min_len]
     deg_data = deg_data[:min_len]
 
-    return (AudioSignal(ref_data, reference.sample_rate),
-            AudioSignal(deg_data, degraded.sample_rate),
-            lag_seconds)
+    return (
+        AudioSignal(ref_data, reference.sample_rate),
+        AudioSignal(deg_data, degraded.sample_rate),
+        lag_seconds,
+    )

visqol_python-3.3.5/visqol/analysis_window.py

@@ -0,0 +1,76 @@
+"""
+Analysis window for spectrogram construction.
+
+Corresponds to C++ files: analysis_window.cc/h
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class AnalysisWindow:
+    """
+    Analysis window used for spectrogram frame windowing.
+
+    Attributes:
+        size: Window size in samples.
+        overlap: Overlap ratio (e.g. 0.25 means 25 % of window size as hop).
+        window_duration: Duration of window in seconds.
+    """
+
+    def __init__(
+        self,
+        sample_rate: int,
+        overlap: float = 0.25,
+        window_duration: float = 0.08,
+    ) -> None:
+        """
+        Args:
+            sample_rate: Sample rate of the audio signal.
+            overlap: Overlap as a fraction of window size
+                (used as ``hop = size * overlap``).
+            window_duration: Duration of the analysis window in seconds.
+
+        Raises:
+            ValueError: If *sample_rate* ≤ 0 or *overlap* not in (0, 1).
+        """
+        if sample_rate <= 0:
+            raise ValueError(f"sample_rate must be positive, got {sample_rate}")
+        if not (0.0 < overlap < 1.0):
+            raise ValueError(f"overlap must be in (0, 1), got {overlap}")
+
+        self.window_duration: float = window_duration
+        self.overlap: float = overlap
+        self.size: int = int(round(sample_rate * window_duration))
+        self._hann_window: NDArray[np.float64] | None = None
+
+    @property
+    def hop_size(self) -> int:
+        """Hop size = window_size × overlap."""
+        return int(self.size * self.overlap)
+
+    @property
+    def hann_window(self) -> NDArray[np.float64]:
+        """Pre-computed Hann window."""
+        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)
+            )
+        return self._hann_window
+
+    def apply_hann_window(self, frame: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Apply Hann window to a frame.
+
+        Raises:
+            ValueError: If *frame* length does not match window size.
+        """
+        if len(frame) != self.size:
+            raise ValueError(
+                f"Frame length ({len(frame)}) does not match "
+                f"window size ({self.size})."
+            )
+        return frame * self.hann_window

visqol_python-3.3.5/visqol/api.py

@@ -0,0 +1,181 @@
+"""
+ViSQOL public API.
+
+Provides a simple interface for comparing audio quality.
+
+Corresponds to C++ file: visqol_api.cc
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import numpy as np
+from numpy.typing import NDArray
+
+from visqol.audio_utils import AudioSignal
+from visqol.visqol_manager import VisqolManager
+from visqol.visqol_core import SimilarityResult
+
+# Valid mode names
+_VALID_MODES = frozenset({"audio", "speech"})
+
+# Default SVR model path (bundled inside the package)
+_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")
+
+
+class VisqolApi:
+    """
+    Public API for ViSQOL audio quality assessment.
+
+    Usage::
+
+        api = VisqolApi()
+        api.create(mode="audio")
+        result = api.measure("reference.wav", "degraded.wav")
+        print(f"MOS-LQO: {result.moslqo}")
+    """
+
+    def __init__(self) -> None:
+        self._manager: VisqolManager = VisqolManager()
+        self._is_created: bool = False
+
+    def create(
+        self,
+        mode: str = "audio",
+        model_path: Optional[str] = None,
+        search_window: int = 60,
+        use_unscaled_speech: bool = False,
+        disable_global_alignment: bool = False,
+        disable_realignment: bool = False,
+    ) -> None:
+        """
+        Initialize ViSQOL with the specified configuration.
+
+        Args:
+            mode: ``"audio"`` for music/general audio (48 kHz, SVR model) or
+                ``"speech"`` for speech signals (16 kHz, exponential fit).
+            model_path: Path to SVR model file (Audio mode only).
+                If *None*, uses the bundled default model.
+            search_window: Search window radius (default 60).
+            use_unscaled_speech: If *True*, don't scale speech MOS to 5.0.
+            disable_global_alignment: Skip global alignment step.
+            disable_realignment: Skip fine realignment step.
+
+        Raises:
+            ValueError: If *mode* is not ``"audio"`` or ``"speech"``.
+            ValueError: If *search_window* is not positive.
+            FileNotFoundError: If *model_path* is given but does not exist.
+        """
+        mode_lower = mode.lower()
+        if mode_lower not in _VALID_MODES:
+            raise ValueError(
+                f"Invalid mode {mode!r}. Must be one of {sorted(_VALID_MODES)}."
+            )
+
+        if search_window <= 0:
+            raise ValueError(
+                f"search_window must be a positive integer, got {search_window}."
+            )
+
+        use_speech_mode = mode_lower == "speech"
+
+        if not use_speech_mode and model_path is None:
+            model_path = _DEFAULT_SVR_MODEL
+
+        if model_path is not None and not os.path.isfile(model_path):
+            raise FileNotFoundError(
+                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,
+        )
+        self._is_created = True
+
+    def measure(self, ref_path: str, deg_path: str) -> SimilarityResult:
+        """
+        Compare two audio files and return quality assessment.
+
+        Args:
+            ref_path: Path to reference audio file (WAV).
+            deg_path: Path to degraded audio file (WAV).
+
+        Returns:
+            :class:`SimilarityResult` containing MOS-LQO score and detailed results.
+
+        Raises:
+            RuntimeError: If :meth:`create` has not been called.
+            FileNotFoundError: If either audio file does not exist.
+        """
+        self._ensure_created()
+
+        if not os.path.isfile(ref_path):
+            raise FileNotFoundError(f"Reference audio file not found: {ref_path}")
+        if not os.path.isfile(deg_path):
+            raise FileNotFoundError(f"Degraded audio file not found: {deg_path}")
+
+        return self._manager.run(ref_path, deg_path)
+
+    def measure_from_arrays(
+        self,
+        ref_array: NDArray[np.floating],
+        deg_array: NDArray[np.floating],
+        sample_rate: int,
+    ) -> SimilarityResult:
+        """
+        Compare two audio signals from numpy arrays.
+
+        Args:
+            ref_array: Reference audio signal (1-D numpy array).
+            deg_array: Degraded audio signal (1-D numpy array).
+            sample_rate: Sample rate of both signals in Hz.
+
+        Returns:
+            :class:`SimilarityResult` containing MOS-LQO score and detailed results.
+
+        Raises:
+            RuntimeError: If :meth:`create` has not been called.
+            ValueError: If arrays are empty or *sample_rate* is not positive.
+            TypeError: If arrays are not numpy arrays.
+        """
+        self._ensure_created()
+
+        if not isinstance(ref_array, np.ndarray):
+            raise TypeError(
+                f"ref_array must be a numpy array, got {type(ref_array).__name__}"
+            )
+        if not isinstance(deg_array, np.ndarray):
+            raise TypeError(
+                f"deg_array must be a numpy array, got {type(deg_array).__name__}"
+            )
+        if ref_array.size == 0:
+            raise ValueError("ref_array must not be empty.")
+        if deg_array.size == 0:
+            raise ValueError("deg_array must not be empty.")
+        if sample_rate <= 0:
+            raise ValueError(
+                f"sample_rate must be a positive integer, got {sample_rate}."
+            )
+
+        ref_signal = AudioSignal(ref_array, sample_rate)
+        deg_signal = AudioSignal(deg_array, sample_rate)
+        return self._manager.run_from_signals(ref_signal, deg_signal)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_created(self) -> None:
+        """Raise if :meth:`create` has not been called."""
+        if not self._is_created:
+            raise RuntimeError(
+                "VisqolApi must be created (call .create()) before measuring."
+            )