{"id":6197,"library":"pystoi","title":"pystoi","description":"pystoi is a Python library that computes the Short Term Objective Intelligibility (STOI) measure, a metric highly correlated with the subjective intelligibility of degraded speech signals. It is an intrusive measure, requiring both clean and degraded speech inputs. It serves as an objective alternative for evaluating the effect of non-linear processing like noise reduction or binary masking on speech intelligibility. The current version is 0.4.1, and its development appears to be in maintenance mode.","status":"maintenance","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/mpariente/pystoi","tags":["audio","speech","intelligibility","speech processing","objective measure"],"install":[{"cmd":"pip install pystoi","lang":"bash","label":"Install pystoi"}],"dependencies":[{"reason":"Core numerical computations","package":"numpy","optional":false},{"reason":"For reading/writing audio files in examples and typical use cases","package":"soundfile","optional":true}],"imports":[{"symbol":"stoi","correct":"from pystoi import stoi"}],"quickstart":{"code":"import soundfile as sf\nimport numpy as np\nfrom pystoi import stoi\nimport os\n\n# Create dummy audio files for demonstration\nfs = 10000 # Sample rate\nduration = 1 # seconds\n\nclean_signal = np.random.rand(fs * duration).astype(np.float32) * 0.5 # Clean speech\ndenoised_signal = clean_signal + (np.random.rand(fs * duration).astype(np.float32) - 0.5) * 0.1 # Denoised (noisy) speech\n\n# Save dummy files\nsf.write('clean.wav', clean_signal, fs)\nsf.write('denoised.wav', denoised_signal, fs)\n\n# Load the audio files (replace with your actual paths)\nclean_audio, fs_clean = sf.read('clean.wav')\ndenoised_audio, fs_denoised = sf.read('denoised.wav')\n\n# Ensure sample rates are consistent, pystoi will resample if needed to 10kHz internally\nassert fs_clean == fs_denoised, \"Sample rates must match\"\n\n# Compute STOI\nscore = stoi(clean_audio, denoised_audio, fs_clean, extended=False)\n\nprint(f\"STOI score: {score:.4f}\")\n\n# Clean up dummy files\nos.remove('clean.wav')\nos.remove('denoised.wav')","lang":"python","description":"This quickstart demonstrates how to compute the STOI score between a clean and a degraded speech signal. It uses `soundfile` to read the audio, then calls the `stoi` function with the clean signal, degraded signal, and sampling frequency. The `extended` parameter can be set to `True` for extended STOI."},"warnings":[{"fix":"Ensure `clean_audio` and `denoised_audio` numpy arrays have identical `shape` before passing them to `stoi`.","message":"The `stoi` function requires the clean and degraded speech signals to have the exact same length. Providing inputs of different lengths will raise an `Exception`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Process audio files one by one in a loop, or consider alternative libraries/forks if batch processing is critical for your workflow.","message":"pystoi does not natively support batched processing of multiple audio files. Users requiring batch computation for performance may need to iterate or consider using forks like `batch-pystoi` (a separate package) which provides this functionality.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of performance limitations for very large datasets; ensure your environment is optimized for CPU-bound tasks.","message":"The `pystoi` library performs computations exclusively on the CPU. It does not leverage GPU acceleration, even when used within frameworks like PyTorch (e.g., via `torchmetrics` wrappers).","severity":"gotcha","affected_versions":"All versions"},{"fix":"If exact STOI values are required, rely on the `pystoi` library. If an approximate STOI suitable for gradient-based optimization in PyTorch is needed, `pytorch_stoi` might be considered, but be aware of the numerical differences.","message":"A separate project, `pytorch_stoi` (distinct from `pystoi`), provides a PyTorch implementation of STOI intended for use as a loss function. This implementation is an *approximation* and may not yield numerically identical results to the original `pystoi` library, which is the reference for exact STOI calculation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}