Functions

audio_samples_qoe.visqol(reference, degraded, *, mode='audio')[source]

Compute the ViSQOL MOS-LQO score between a reference and a degraded signal.

ViSQOL (Virtual Speech Quality Objective Listener) is a full-reference perceptual quality metric: it compares a degraded signal against a clean reference and predicts a mean opinion score.

Each signal may be given as an audio_samples.AudioSamples object or as a path to a WAV or FLAC file (decoded with audio_samples.read()), in any combination. Multi-channel signals are mixed down to mono by channel averaging, and any sample type is accepted.

In "audio" mode both signals are resampled internally to the 48 kHz rate the model is calibrated for, and the score is predicted by a support vector regression over 32 gammatone bands. In "speech" mode the pipeline matches the C++ reference: it runs at the reference signal’s native sample rate (the degraded signal is resampled to match) with 21 gammatone bands capped at 8 kHz, reference patches are gated on voice activity so silence is excluded, and the score comes from an exponential NSIM→MOS fit (identical signals map to 5.0). Upstream recommends 16 kHz input for speech mode.

The GIL is released while the score is computed, so scoring parallelises across Python threads.

Parameters:

  • reference (AudioSamples | str | PathLike[str]) – Clean reference signal — an AudioSamples or a WAV/FLAC file path.

  • degraded (AudioSamples | str | PathLike[str]) – Degraded signal to evaluate — an AudioSamples or a WAV/FLAC file path.

  • mode (Literal['audio', 'speech']) – "audio" (default) for full-band audio, "speech" for speech.

Returns:

The MOS-LQO score, a float in [1.0, 5.0]. Higher is better. Identical signals score ~4.73 in audio mode and 5.0 in speech mode.

Raises:

  • TypeError – If an argument is neither an AudioSamples nor a path.

  • ValueError – If mode is not "audio" or "speech".

  • OSError – If a file path cannot be read or decoded.

  • VisqolError – If the metric pipeline fails — most commonly because a signal is too short to extract a single analysis patch (roughly 0.6 s in audio mode, 0.5 s in speech mode).

Return type:

float

Example

>>> from audio_samples import sine_wave
>>> from audio_samples_qoe import visqol
>>> ref = sine_wave(440, 5.0, 48000)
>>> score = visqol(ref, "degraded.wav")

Type Aliases

audio_samples_qoe.AudioInput

an in-memory audio_samples.AudioSamples or a path to a WAV/FLAC file. Forwarded straight through to the native extension, which decodes paths via audio_samples.read().

Type:

A signal argument to visqol() or Scoreq

alias of AudioSamples | str | PathLike[str]

audio_samples_qoe.VisqolMode

"audio" (full-band, 32 gammatone bands up to Nyquist) or "speech" (21 bands capped at 8 kHz, voice-activity-gated patch selection).

Type:

Scoring mode accepted by visqol()

alias of Literal[‘audio’, ‘speech’]