audio_samples_qoe Documentation

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

  • 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.

  • 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 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

from audio_samples_qoe import visqol

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

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")

from audio_samples_qoe import Scoreq

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

Installation

pip install audio-samples-qoe

Contents

User Guide

API Reference

Indices and tables