visqol-python 3.3.5__py3-none-any.whl → 3.4.0__py3-none-any.whl

visqol/__init__.py

@@ -13,10 +13,17 @@ Usage:
     print(f"MOS-LQO: {result.moslqo}")
 """
 
-__version__: str = "3.3.5"
+__version__: str = "3.4.0"
 
-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] = [
+    "AudioSignal",
+    "PatchSimilarityResult",
+    "ProgressCallback",
+    "SimilarityResult",
+    "VisqolApi",
+]

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."""
@@ -21,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",
     )
 
@@ -61,7 +76,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 +98,32 @@ 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/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/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

visqol/api.py

@@ -8,15 +8,20 @@ Corresponds to C++ file: visqol_api.cc
 
 from __future__ import annotations
 
+import logging
 import os
-from typing import Optional
+from collections.abc import Sequence
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import Callable
 
 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
+from visqol.visqol_manager import VisqolManager
+
+logger = logging.getLogger(__name__)
 
 # Valid mode names
 _VALID_MODES = frozenset({"audio", "speech"})
@@ -25,6 +30,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,11 +49,12 @@ class VisqolApi:
     def __init__(self) -> None:
         self._manager: VisqolManager = VisqolManager()
         self._is_created: bool = False
+        self._create_kwargs: dict[str, object] = {}
 
     def create(
         self,
         mode: str = "audio",
-        model_path: Optional[str] = None,
+        model_path: str | None = None,
         search_window: int = 60,
         use_unscaled_speech: bool = False,
         disable_global_alignment: bool = False,
@@ -71,14 +80,10 @@ class VisqolApi:
         """
         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)}."
-            )
+            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}."
-            )
+            raise ValueError(f"search_window must be a positive integer, got {search_window}.")
 
         use_speech_mode = mode_lower == "speech"
 
@@ -86,18 +91,19 @@ class VisqolApi:
             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,
-        )
+            raise FileNotFoundError(f"SVR model file not found: {model_path}")
+
+        # 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:
@@ -149,26 +155,147 @@ class VisqolApi:
         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__}"
-            )
+            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__}"
-            )
+            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}."
-            )
+            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)
 
+    def measure_batch(
+        self,
+        file_pairs: Sequence[tuple[str, str]],
+        *,
+        max_workers: int | None = None,
+        parallel: bool = True,
+        progress_callback: ProgressCallback | None = None,
+    ) -> list[SimilarityResult | Exception]:
+        """
+        Evaluate multiple file pairs, optionally in parallel.
+
+        When *parallel* is ``True`` (the default), evaluation is distributed
+        across multiple **processes** via :class:`ProcessPoolExecutor`.  Each
+        worker recreates its own ``VisqolManager`` from the same configuration
+        so there is **zero** shared state and no GIL contention.
+
+        Args:
+            file_pairs: Sequence of ``(ref_path, deg_path)`` tuples.
+            max_workers: Maximum number of worker processes.  *None* means
+                ``min(len(file_pairs), os.cpu_count())``.  Ignored when
+                *parallel* is ``False``.
+            parallel: If ``False``, fall back to sequential evaluation
+                (useful for debugging or when multiprocessing is unavailable).
+            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)
+
+        if not parallel or total <= 1:
+            return self._measure_batch_sequential(file_pairs, progress_callback)
+
+        return self._measure_batch_parallel(
+            file_pairs,
+            max_workers,
+            progress_callback,
+        )
+
+    # ------------------------------------------------------------------
+    # Batch helpers
+    # ------------------------------------------------------------------
+
+    def _measure_batch_sequential(
+        self,
+        file_pairs: Sequence[tuple[str, str]],
+        progress_callback: ProgressCallback | None = None,
+    ) -> list[SimilarityResult | Exception]:
+        """Evaluate file pairs one by one (original behaviour)."""
+        total = len(file_pairs)
+        results: list[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
+
+    def _measure_batch_parallel(
+        self,
+        file_pairs: Sequence[tuple[str, str]],
+        max_workers: int | None,
+        progress_callback: ProgressCallback | None = None,
+    ) -> list[SimilarityResult | Exception]:
+        """Evaluate file pairs in parallel using ProcessPoolExecutor."""
+        total = len(file_pairs)
+
+        if max_workers is None:
+            cpu_count = os.cpu_count() or 1
+            max_workers = min(total, cpu_count)
+
+        # We pickle the create_kwargs so each worker can build its own manager.
+        create_kwargs = self._create_kwargs
+
+        results: list[SimilarityResult | Exception] = [
+            RuntimeError("not yet evaluated")
+        ] * total
+
+        completed = 0
+
+        with ProcessPoolExecutor(max_workers=max_workers) as pool:
+            # Submit all futures and track their original index.
+            future_to_idx = {}
+            for idx, (ref_path, deg_path) in enumerate(file_pairs):
+                future = pool.submit(
+                    _worker_measure,
+                    create_kwargs,
+                    ref_path,
+                    deg_path,
+                )
+                future_to_idx[future] = idx
+
+            for future in as_completed(future_to_idx):
+                idx = future_to_idx[future]
+                try:
+                    results[idx] = future.result()
+                except Exception as exc:
+                    results[idx] = exc
+                    logger.warning(
+                        "Pair %d/%d failed: %s",
+                        idx + 1,
+                        total,
+                        exc,
+                    )
+                completed += 1
+                if progress_callback is not None:
+                    progress_callback(completed, total)
+
+        return results
+
     # ------------------------------------------------------------------
     # Private helpers
     # ------------------------------------------------------------------
@@ -176,6 +303,44 @@ class VisqolApi:
     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."
-            )
+            raise RuntimeError("VisqolApi must be created (call .create()) before measuring.")
+
+
+# =====================================================================
+# Module-level worker function for multiprocessing (must be picklable)
+# =====================================================================
+
+
+def _worker_measure(
+    create_kwargs: dict[str, object],
+    ref_path: str,
+    deg_path: str,
+) -> SimilarityResult:
+    """
+    Evaluate a single file pair in a worker process.
+
+    Each worker lazily creates its own ``VisqolManager`` on first call
+    (stored in a global to reuse across tasks in the same process).
+    """
+    global _worker_manager
+
+    try:
+        mgr = _worker_manager
+    except NameError:
+        mgr = None
+
+    if mgr is None:
+        mgr = VisqolManager()
+        mgr.init(**create_kwargs)  # type: ignore[arg-type]
+        _worker_manager = mgr
+
+    ref_signal = __import__("visqol.audio_utils", fromlist=["load_as_mono"]).load_as_mono(
+        ref_path
+    )
+    deg_signal = __import__("visqol.audio_utils", fromlist=["load_as_mono"]).load_as_mono(
+        deg_path
+    )
+    return mgr.run_from_signals(ref_signal, deg_signal)
+
+
+_worker_manager: VisqolManager | None = None

visqol/audio_utils.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Tuple
 
 import numpy as np
 from numpy.typing import NDArray
@@ -37,9 +36,7 @@ class AudioSignal:
         self.sample_rate: int = int(sample_rate)
 
         if self.sample_rate <= 0:
-            raise ValueError(
-                f"sample_rate must be positive, got {self.sample_rate}"
-            )
+            raise ValueError(f"sample_rate must be positive, got {self.sample_rate}")
 
     @property
     def duration(self) -> float:
@@ -53,8 +50,18 @@ 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 load_audio(path: str) -> Tuple[NDArray[np.float64], int]:
+    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]:
     """
     Load a WAV file and return ``(data, sample_rate)``.
 
@@ -72,16 +79,14 @@ def load_audio(path: str) -> Tuple[NDArray[np.float64], int]:
     try:
         data, sr = sf.read(path, dtype="float64", always_2d=True)
     except Exception as exc:
-        raise RuntimeError(
-            f"Failed to read audio file '{path}': {exc}"
-        ) from exc
+        raise RuntimeError(f"Failed to read audio file '{path}': {exc}") from exc
     return data, int(sr)
 
 
 def to_mono(data: NDArray[np.float64]) -> NDArray[np.float64]:
     """Convert multi-channel audio to mono by averaging channels."""
     if data.ndim == 2 and data.shape[1] > 1:
-        return np.mean(data, axis=1)
+        return np.asarray(np.mean(data, axis=1), dtype=np.float64)
     elif data.ndim == 2:
         return data[:, 0]
     return data
@@ -106,10 +111,10 @@ def calc_sound_pressure_level(signal: AudioSignal) -> float:
     ``SPL = 20 * log10(rms / reference_point)``
     """
     data = signal.data
-    rms: float = float(np.sqrt(np.mean(data ** 2)))
+    rms: float = float(np.sqrt(np.mean(data**2)))
     if rms == 0:
         return float(-np.inf)
-    return 20.0 * np.log10(rms / SPL_REFERENCE_POINT)
+    return float(20.0 * np.log10(rms / SPL_REFERENCE_POINT))
 
 
 def scale_to_match_sound_pressure_level(