{"id":7858,"library":"warpq","title":"WARP-Q: Quality Prediction For Generative Neural Speech Codecs","description":"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.","status":"active","version":"1.5.2","language":"en","source_language":"en","source_url":"https://github.com/wjassim/WARP-Q","tags":["audio","speech processing","quality prediction","deep learning","PyTorch","codec"],"install":[{"cmd":"pip install warpq","lang":"bash","label":"Install WARP-Q"}],"dependencies":[{"reason":"Core deep learning framework for models.","package":"torch","optional":false},{"reason":"Audio I/O and transformations, dependent on PyTorch.","package":"torchaudio","optional":false},{"reason":"Numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Scientific computing utilities, often for audio processing.","package":"scipy","optional":false},{"reason":"Progress bars for iterative tasks.","package":"tqdm","optional":false},{"reason":"Reading and writing sound files.","package":"soundfile","optional":false},{"reason":"Optional dependency for Perceptual Evaluation of Speech Quality (PESQ) metric comparison.","package":"pesq","optional":true},{"reason":"Optional dependency for Short-Term Objective Intelligibility (STOI) metric comparison.","package":"pystoi","optional":true}],"imports":[{"symbol":"WARPQ","correct":"from warpq import WARPQ"}],"quickstart":{"code":"import warpq\nimport os\n\n# NOTE: Replace 'ref_audio.wav' and 'deg_audio.wav' with actual paths to your audio files.\n# Ensure these files exist in the current directory or provide full paths.\n# For example, you might create dummy files for testing:\n# import soundfile as sf\n# import numpy as np\n# sf.write('ref_audio.wav', np.random.rand(16000), 16000)\n# sf.write('deg_audio.wav', np.random.rand(16000), 16000)\n\nref_audio_path = os.path.join(os.getcwd(), 'ref_audio.wav') # Example path\ndeg_audio_path = os.path.join(os.getcwd(), 'deg_audio.wav') # Example path\n\n# Create dummy audio files for demonstration if they don't exist\nif not os.path.exists(ref_audio_path) or not os.path.exists(deg_audio_path):\n    import soundfile as sf\n    import numpy as np\n    sample_rate = 16000\n    duration = 1 # second\n    data = np.random.rand(int(sample_rate * duration)).astype(np.float32) * 0.5\n    sf.write(ref_audio_path, data, sample_rate)\n    sf.write(deg_audio_path, data * 0.9, sample_rate)\n    print(f\"Created dummy audio files: {ref_audio_path}, {deg_audio_path}\")\n\ntry:\n    # Initialize WARP-Q model. model_path=None uses a default pretrained model.\n    model = warpq.WARPQ(model_path=None)\n\n    # Predict the WARP-Q score\n    score = model.predict(ref_audio_path, deg_audio_path)\n    print(f\"WARP-Q score for {os.path.basename(deg_audio_path)} (vs {os.path.basename(ref_audio_path)}): {score:.4f}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your audio files exist and are valid (e.g., .wav format, same sample rate).\")\n    print(\"Also verify PyTorch and torchaudio are correctly installed.\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists(ref_audio_path):\n        os.remove(ref_audio_path)\n    if os.path.exists(deg_audio_path):\n        os.remove(deg_audio_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install warpq` to install the package. If using virtual environments, ensure the correct environment is activated.","cause":"The `warpq` package is not installed in the current Python environment or the environment is not active.","error":"ModuleNotFoundError: No module named 'warpq'"},{"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.","cause":"The reference and degraded audio files passed to `model.predict()` have different sampling rates.","error":"RuntimeError: Input audio files must have the same sampling rate."},{"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.","cause":"The path provided for the reference or degraded audio file does not point to an existing file.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_audio_file.wav'"},{"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)`.","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.","error":"AttributeError: 'module' object has no attribute 'load_model'"}]}