{"id":10029,"library":"pesq","title":"PESQ Score Calculator","description":"pesq is a Python wrapper for the Perceptual Evaluation of Speech Quality (PESQ) metric, implementing the ITU-T P.862 standard. It supports both narrow-band ('nb') and wide-band ('wb') calculations, providing an objective measure of speech quality. The current version is 0.0.4, with releases occurring infrequently but introducing new features like multiprocessing support.","status":"active","version":"0.0.4","language":"en","source_language":"en","source_url":"https://github.com/ludlows/python-pesq","tags":["audio-processing","speech-quality","pesq","telecommunications","speech-recognition"],"install":[{"cmd":"pip install pesq","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Numerical operations for audio data.","package":"numpy","optional":false},{"reason":"Scientific computing library, potentially for signal processing.","package":"scipy","optional":false},{"reason":"Reading and writing audio files (e.g., WAV).","package":"soundfile","optional":false},{"reason":"Used for compiling the C extensions that implement the core PESQ algorithm.","package":"cython","optional":false}],"imports":[{"symbol":"pesq","correct":"from pesq import pesq"},{"note":"Introduced in v0.0.4 for multiprocessing.","symbol":"pesq_batch","correct":"from pesq import pesq_batch"}],"quickstart":{"code":"import numpy as np\nfrom pesq import pesq\n\n# Define sampling rate and generate dummy audio signals (16 kHz, 3 seconds)\nfs = 16000\nduration = 3 # seconds\nt = np.linspace(0, duration, int(fs * duration), endpoint=False)\n\n# Reference signal (e.g., clean speech)\nref_signal = (0.5 * np.sin(2 * np.pi * 440 * t)).astype(np.float32)\n\n# Degraded signal (e.g., speech with noise or distortion)\ndeg_signal = (0.5 * np.sin(2 * np.pi * 440 * t + 0.1) + 0.1 * np.random.randn(len(t))).astype(np.float32)\n\n# Ensure signals are 16-bit PCM (by scaling to int16 range) if not already\n# The library expects float32, but underlying PESQ is 16-bit. \n# For this example, float32 is fine as it will be handled internally.\n\n# Calculate Wide-Band PESQ score\nscore_wb = pesq(fs, ref_signal, deg_signal, 'wb')\nprint(f\"PESQ Wide-Band (wb) score: {score_wb:.2f}\")\n\n# Calculate Narrow-Band PESQ score (requires adjusting signals if necessary)\n# score_nb = pesq(fs, ref_signal, deg_signal, 'nb')\n# print(f\"PESQ Narrow-Band (nb) score: {score_nb:.2f}\")\n\n# The `pesq` function also accepts file paths directly:\n# import soundfile as sf\n# import os\n# sf.write('ref.wav', ref_signal, fs, subtype='PCM_16')\n# sf.write('deg.wav', deg_signal, fs, subtype='PCM_16')\n# score_files = pesq(fs, 'ref.wav', 'deg.wav', 'wb')\n# print(f\"PESQ from files: {score_files:.2f}\")\n# os.remove('ref.wav'); os.remove('deg.wav')","lang":"python","description":"This quickstart demonstrates how to calculate a PESQ score using NumPy arrays for reference and degraded audio signals. It highlights the use of the `pesq` function with a specified sampling rate and mode ('wb' for wide-band). The library internally handles the necessary conversions, but input characteristics are crucial."},"warnings":[{"fix":"Ensure a C compiler and associated build tools are installed on your system before attempting `pip install pesq`.","message":"Due to its reliance on Cython for performance, installing `pesq` often requires a C compiler (e.g., GCC on Linux, Apple Clang on macOS, MSVC on Windows). Users may encounter `Failed building wheel` errors during `pip install` without one.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pre-process your audio signals to ensure they are consistent: resample to a common rate (e.g., 16 kHz), convert to 16-bit PCM representation (if not already), and trim/pad to equal lengths.","message":"The underlying PESQ algorithm is highly sensitive to input audio characteristics. Signals provided to `pesq` must effectively represent 16-bit PCM, have the same sampling rate, and typically be of equal length to avoid `ValueError` or incorrect scores.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always verify that the `mode` argument ('nb' or 'wb') passed to `pesq` or `pesq_batch` is appropriate for your audio data and the desired evaluation.","message":"Incorrectly specifying the PESQ mode ('nb' for narrow-band or 'wb' for wide-band) can lead to unexpected scores or errors. The chosen mode must match the characteristics and intended evaluation context of your audio.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to v0.0.3 or higher to benefit from improved error messages and more graceful error handling.","message":"Prior to v0.0.3, error handling behaviors were less robust. While not a breaking API change, errors might have been less descriptive or harder to catch.","severity":"deprecated","affected_versions":"<0.0.3"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install a C compiler for your operating system. For Debian/Ubuntu: `sudo apt-get install build-essential`. For macOS: `xcode-select --install`. For Windows: Install Visual Studio Build Tools with C++ desktop development workload.","cause":"Missing C compiler (e.g., GCC, MSVC) or development headers required for Cython extensions during installation.","error":"ERROR: Failed building wheel for pesq"},{"fix":"Ensure both `ref` and `deg` signals are 16-bit PCM (e.g., float32 scaled to int16 range, or loaded from 16-bit WAVs), have identical sampling rates, and are of the same length before passing them to `pesq`.","cause":"The reference or degraded audio signals do not meet the strict requirements of the PESQ algorithm (e.g., incorrect bit depth, mismatched sampling rates, or unequal signal lengths).","error":"ValueError: Input signals must be 16-bit PCM and have same sampling rate"},{"fix":"Verify that the file paths are correct and that the audio files exist at the specified locations. Use absolute paths or ensure your script's working directory is correct.","cause":"The file path provided for the reference or degraded audio file does not exist or is not accessible by the script.","error":"OSError: pesq: Cannot open input file 'non_existent_file.wav'"},{"fix":"If using `pesq_batch`, wrap your single reference/degraded signals in a list. For multiple pairs, ensure both the `ref` and `deg` arguments are lists of corresponding signals/paths.","cause":"`pesq_batch` expects iterables of signals (e.g., lists of NumPy arrays or file paths), not single arguments.","error":"TypeError: argument of type 'int' is not iterable"}]}