Classes

class audio_samples_qoe.Scoreq(domain, mode='nr')[source]

Bases: object

A loaded SCOREQ model — a neural, wav2vec2-based speech quality metric.

SCOREQ (Speech Contrastive Regression for Quality Assessment) is a neural alternative to visqol(). It runs a trained model via ONNX Runtime rather than a pure DSP pipeline, in one of two operating modes:

  • mode="nr" (no-reference): predict() returns a predicted MOS from the test signal alone.

  • mode="ref" (reference-based): predict_ref() returns the Euclidean distance between the test and reference embeddings — smaller means closer to the reference’s quality.

Loading a model is expensive: the first use of a given (domain, mode) pair downloads ~378 MB of weights from Zenodo into ~/.cache/scoreq/, and every construction loads an ONNX Runtime session. Construct one Scoreq per (domain, mode) pair and reuse it across calls rather than re-instantiating per signal.

Parameters:

  • domain (Literal['natural', 'synthetic']) – "natural" for recorded human speech (codecs, VoIP, telephony, enhancement, restoration), or "synthetic" for machine-generated speech (TTS, voice conversion, generative models). Choosing the wrong domain yields meaningless scores.

  • mode (Literal['nr', 'ref']) – "nr" for no-reference MOS prediction, "ref" for reference-based embedding distance.

Raises:

  • ValueError – If domain is not "natural"/"synthetic" or mode is not "nr"/"ref".

  • ScoreqError – If loading the model fails (e.g. the weight download fails).

Example

>>> from audio_samples import sine_wave
>>> from audio_samples_qoe import Scoreq
>>> model = Scoreq(domain="natural", mode="nr")
>>> test = sine_wave(220, 3.0, 16000)
>>> model.predict(test)
3.1...
property domain: Literal['natural', 'synthetic']

The domain this model was loaded for.

property mode: Literal['nr', 'ref']

The mode this model was loaded for.

predict(test)[source]

Predict a no-reference MOS for test.

Requires a model loaded with mode="nr". The GIL is released while the model runs.

Parameters:

test (AudioSamples | str | PathLike[str]) – Signal to score — an AudioSamples or a WAV/FLAC file path. Resampled to 16 kHz internally if not already at that rate; feed 16 kHz audio for exact agreement with the upstream Python/torchaudio implementation.

Returns:

The predicted MOS.

Raises:

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

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

  • ScoreqError – If this model was loaded with mode="ref", or the pipeline otherwise fails.

Return type:

float

predict_ref(test, reference)[source]

Return the embedding distance between test and reference.

Requires a model loaded with mode="ref". Smaller distances mean test is closer in quality to reference. The GIL is released while the model runs.

Parameters:

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

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

Returns:

The Euclidean distance between the two embeddings.

Raises:

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

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

  • ScoreqError – If this model was loaded with mode="nr", or the pipeline otherwise fails.

Return type:

float

Type Aliases

audio_samples_qoe.ScoreqDomain

"natural" (recorded human speech — codecs, VoIP, telephony, enhancement) or "synthetic" (machine-generated speech — TTS, voice conversion).

Type:

Which pre-trained Scoreq model family to use

alias of Literal[‘natural’, ‘synthetic’]

audio_samples_qoe.ScoreqMode

"nr" (no-reference — predict a MOS from the test signal alone) or "ref" (reference-based — Euclidean distance between test and reference embeddings).

Type:

Operating mode for Scoreq

alias of Literal[‘nr’, ‘ref’]