WARP-Q: Quality Prediction For Generative Neural Speech Codecs

1.5.2 · active · verified Thu Apr 16

WARP-Q is a Python library designed for predicting the quality of generative neural speech codecs. It offers a robust framework to assess speech quality, providing access to pretrained models for immediate use and the flexibility to load custom models. The current version is 1.5.2, and the library maintains an active development status with notable API updates, including a significant overhaul at v1.0.0.

Common errors

```
ModuleNotFoundError: No module named 'warpq'
```
cause The `warpq` package is not installed in the current Python environment or the environment is not active.

fix Run `pip install warpq` to install the package. If using virtual environments, ensure the correct environment is activated.
```
RuntimeError: Input audio files must have the same sampling rate.
```
cause The reference and degraded audio files passed to `model.predict()` have different sampling rates.

fix Before calling `predict`, resample one or both audio files to a consistent sampling rate. For example, using `torchaudio` or `scipy.io.wavfile` to read and then `scipy.signal.resample` to adjust.
```
FileNotFoundError: [Errno 2] No such file or directory: 'your_audio_file.wav'
```
cause The path provided for the reference or degraded audio file does not point to an existing file.

fix Double-check the file paths. Ensure they are correct, including file extensions, and that the files exist at the specified locations. Use absolute paths or verify the current working directory for relative paths.
```
AttributeError: 'module' object has no attribute 'load_model'
```
cause Attempting to use an old API function (e.g., a direct `load_model` function) from a `warpq` version prior to v1.0.0. The current API primarily uses the `WARPQ` class.

fix Update your code to initialize the `WARPQ` class and then call its `predict` method: `from warpq import WARPQ; model = WARPQ(); score = model.predict(ref_path, deg_path)`.

Warnings

breaking The `warpq` API underwent a significant breaking change with the release of v1.0.0. Code written for versions prior to 1.0.0 will not be compatible with the current API due to changes in class structures, module organization, and method signatures.
Fix: Refactor your code to use the `WARPQ` class, typically imported as `from warpq import WARPQ`, and its `predict` method. Consult the latest GitHub README for updated usage patterns.
gotcha `warpq` relies heavily on PyTorch and torchaudio. Users often encounter complex installation issues (e.g., CUDA compatibility, specific hardware drivers) when setting up PyTorch, which can prevent `warpq` from functioning correctly.
Fix: Ensure PyTorch and torchaudio are correctly installed for your specific environment (CPU/GPU) *before* installing `warpq` if you anticipate issues. Refer to the official PyTorch installation guide for best practices tailored to your system.
gotcha When predicting scores, the library expects the reference and degraded audio files to have the same sampling rate. Providing files with mismatched sampling rates will result in a runtime error.
Fix: Resample your audio files to a common sampling rate using libraries like `torchaudio.transforms.Resample`, `librosa`, or `scipy.signal.resample` before passing them to the `warpq.WARPQ().predict()` method.

Install

pip install warpq Install WARP-Q

Imports

WARPQ
```
from warpq import WARPQ
```

Quickstart

This quickstart demonstrates how to initialize the WARP-Q model and predict the quality score between a reference and a degraded speech audio file. It uses a default pretrained model and includes logic to create dummy audio files if they don't exist, making it runnable out-of-the-box. Ensure your actual audio files are in a compatible format (e.g., WAV) and have the same sampling rate.

import warpq
import os

# NOTE: Replace 'ref_audio.wav' and 'deg_audio.wav' with actual paths to your audio files.
# Ensure these files exist in the current directory or provide full paths.
# For example, you might create dummy files for testing:
# import soundfile as sf
# import numpy as np
# sf.write('ref_audio.wav', np.random.rand(16000), 16000)
# sf.write('deg_audio.wav', np.random.rand(16000), 16000)

ref_audio_path = os.path.join(os.getcwd(), 'ref_audio.wav') # Example path
deg_audio_path = os.path.join(os.getcwd(), 'deg_audio.wav') # Example path

# Create dummy audio files for demonstration if they don't exist
if not os.path.exists(ref_audio_path) or not os.path.exists(deg_audio_path):
    import soundfile as sf
    import numpy as np
    sample_rate = 16000
    duration = 1 # second
    data = np.random.rand(int(sample_rate * duration)).astype(np.float32) * 0.5
    sf.write(ref_audio_path, data, sample_rate)
    sf.write(deg_audio_path, data * 0.9, sample_rate)
    print(f"Created dummy audio files: {ref_audio_path}, {deg_audio_path}")

try:
    # Initialize WARP-Q model. model_path=None uses a default pretrained model.
    model = warpq.WARPQ(model_path=None)

    # Predict the WARP-Q score
    score = model.predict(ref_audio_path, deg_audio_path)
    print(f"WARP-Q score for {os.path.basename(deg_audio_path)} (vs {os.path.basename(ref_audio_path)}): {score:.4f}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your audio files exist and are valid (e.g., .wav format, same sample rate).")
    print("Also verify PyTorch and torchaudio are correctly installed.")
finally:
    # Clean up dummy files
    if os.path.exists(ref_audio_path):
        os.remove(ref_audio_path)
    if os.path.exists(deg_audio_path):
        os.remove(deg_audio_path)

view raw JSON →