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

visqol/__init__.py

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

visqol/__main__.py

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

visqol/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

@@ -10,15 +10,16 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Sequence
 from concurrent.futures import ProcessPoolExecutor, as_completed
-from typing import Callable, List, Optional, Sequence, Tuple, Union
+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__)
 
@@ -53,7 +54,7 @@ class VisqolApi:
     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,
@@ -79,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"
 
@@ -94,9 +91,7 @@ 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}"
-            )
+            raise FileNotFoundError(f"SVR model file not found: {model_path}")
 
         # Store kwargs for batch mode (subprocess recreation)
         self._create_kwargs = {
@@ -160,21 +155,15 @@ 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)
@@ -182,28 +171,61 @@ class VisqolApi:
 
     def measure_batch(
         self,
-        file_pairs: Sequence[Tuple[str, str]],
+        file_pairs: Sequence[tuple[str, str]],
         *,
-        progress_callback: Optional[ProgressCallback] = None,
-    ) -> List[Union[SimilarityResult, Exception]]:
+        max_workers: int | None = None,
+        parallel: bool = True,
+        progress_callback: ProgressCallback | None = None,
+    ) -> list[SimilarityResult | Exception]:
         """
-        Evaluate multiple file pairs sequentially.
+        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*.
+            (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]] = []
+
+        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:
@@ -212,13 +234,68 @@ class VisqolApi:
             except Exception as exc:
                 results.append(exc)
                 logger.warning(
-                    "Pair %d/%d failed: %s", idx + 1, total, exc,
+                    "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
     # ------------------------------------------------------------------
@@ -226,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:
@@ -64,7 +61,7 @@ class AudioSignal:
         return f"AudioSignal({self.duration:.3f}s @ {self.sample_rate} Hz)"
 
 
-def load_audio(path: str) -> Tuple[NDArray[np.float64], int]:
+def load_audio(path: str) -> tuple[NDArray[np.float64], int]:
     """
     Load a WAV file and return ``(data, sample_rate)``.
 
@@ -82,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
@@ -116,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(