audio_samples_qoe Documentation
===============================

**audio-samples-qoe** computes two perceptual audio quality metrics from
Python. The scoring core is pure Rust.

- :func:`~audio_samples_qoe.visqol` — **ViSQOL** (Virtual Speech Quality
  Objective Listener), a full-reference DSP metric. Given a clean
  **reference** signal and a **degraded** signal (codec artefacts, bandwidth
  limiting, added noise), it returns a **MOS-LQO** (mean opinion score,
  listening quality objective) in the range **1.0 to 5.0**. Higher is better.
- :class:`~audio_samples_qoe.Scoreq` — **SCOREQ** (Speech Contrastive
  Regression for Quality Assessment), a neural wav2vec2-based metric. In
  no-reference mode it predicts a MOS from a single signal; in reference mode
  it returns an embedding distance between a test and reference signal.

ViSQOL is conformance-tested against Google's C++ reference in both audio and
speech mode. Both metrics release the GIL during computation, so scoring
parallelises across Python threads.

Features
--------

- **Two metrics**: ViSQOL's ``audio`` mode (32 gammatone bands, SVR mapping)
  and ``speech`` mode (21 bands ≤ 8 kHz, voice-activity-gated, exponential
  NSIM fit); SCOREQ's ``nr`` (no-reference MOS) and ``ref`` (embedding
  distance) modes, each for ``natural`` or ``synthetic`` speech.
- **Flexible inputs**: an :class:`audio_samples.AudioSamples` object or a path
  to a WAV/FLAC file, in any combination. Path arguments are decoded with
  ``audio_samples.read()``.
- **Any rate, any channel count**: signals are resampled and mixed to mono
  internally to match each pipeline.
- **Typed**: ships full type stubs and a ``py.typed`` marker.

Quick Example
-------------

.. code-block:: python

   from audio_samples_qoe import visqol

   score = visqol("reference.wav", "degraded.wav")
   print(f"MOS-LQO: {score:.3f}")

.. code-block:: python

   from audio_samples import sine_wave, white_noise
   from audio_samples_qoe import visqol

   ref = sine_wave(440, 5.0, 48_000)
   deg = ref + white_noise(5.0, 48_000, amplitude=0.02, seed=0)

   score = visqol(ref, deg)            # audio mode (default)
   score = visqol(ref, deg, mode="speech")

.. code-block:: python

   from audio_samples_qoe import Scoreq

   model = Scoreq(domain="natural", mode="nr")
   mos = model.predict("degraded.wav")

Installation
------------

.. code-block:: bash

   pip install audio-samples-qoe

Contents
--------

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   guide/installation
   guide/quickstart
   guide/inputs
   guide/modes
   guide/scoreq
   guide/errors

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/index

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`