pystoi

library0.4.1pypypi✓ verified 87d ago

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.

ai-ml data

pip install pystoi

github ↗package ↗

INSTALL

IMPORT

SIG · PYSTOI

pystoi

ai-mlpythonv0.4.1

Install

7.3s avg

Import

2893ms

Disk

230MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 2.969s · 230.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 7.3s · import 2.818s · 222MB

230MB installed

● package 230MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

stoi

✓ from pystoi import stoi

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.

import soundfile as sf import numpy as np from pystoi import stoi import os # Create dummy audio files for demonstration fs = 10000 # Sample rate duration = 1 # seconds clean_signal = np.random.rand(fs * duration).astype(np.float32) * 0.5 # Clean speech denoised_signal = clean_signal + (np.random.rand(fs * duration).astype(np.float32) - 0.5) * 0.1 # Denoised (noisy) speech # Save dummy files sf.write('clean.wav', clean_signal, fs) sf.write('denoised.wav', denoised_signal, fs) # Load the audio files (replace with your actual paths) clean_audio, fs_clean = sf.read('clean.wav') denoised_audio, fs_denoised = sf.read('denoised.wav') # Ensure sample rates are consistent, pystoi will resample if needed to 10kHz internally assert fs_clean == fs_denoised, "Sample rates must match" # Compute STOI score = stoi(clean_audio, denoised_audio, fs_clean, extended=False) print(f"STOI score: {score:.4f}") # Clean up dummy files os.remove('clean.wav') os.remove('denoised.wav')

Debug

Known issues

gotchaThe `stoi` function requires the clean and degraded speech signals to have the exact same length. Providing inputs of different lengths will raise an `Exception`.

fix

Ensure `clean_audio` and `denoised_audio` numpy arrays have identical `shape` before passing them to `stoi`.

affects: All versions

gotchapystoi 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.

fix

Process audio files one by one in a loop, or consider alternative libraries/forks if batch processing is critical for your workflow.

affects: All versions

gotchaThe `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).

fix

Be aware of performance limitations for very large datasets; ensure your environment is optimized for CPU-bound tasks.

affects: All versions

gotchaA 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.

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pystoi'

The `pystoi` library has not been installed in the current Python environment or is not accessible.

fix

Install the library using pip: `pip install pystoi`

ValueError: Length of x and y must be the same

The clean (x) and degraded (y) speech signals provided to the `pystoi.stoi` function must have identical lengths for comparison.

fix

Ensure both input signals have the same length by trimming or padding one of them: `min_len = min(len(clean_speech), len(degraded_speech)); score = pystoi.stoi(clean_speech[:min_len], degraded_speech[:min_len], fs_sig=16000)`

TypeError: stoi() missing 1 required positional argument: 'fs_sig'

The `stoi` function requires the sampling rate of the input signals (`fs_sig`) as a mandatory positional argument, which was not provided.

fix

Provide the correct sampling rate (in Hz) for your speech signals: `import pystoi; score = pystoi.stoi(clean_speech, degraded_speech, fs_sig=16000)`

AttributeError: module 'pystoi' has no attribute 'Stoi'

The `pystoi` library provides a functional interface through the `stoi` function directly and does not expose a class named `Stoi` for instantiation.

fix

Call the `stoi` function directly from the `pystoi` package or import it: `import pystoi; score = pystoi.stoi(clean_speech, degraded_speech, fs_sig=16000)`

Upgrade

Version history

0.4.1latest on PyPI · released Dec 29, 2023

Audit

Dependencies

numpyrequiredCore numerical computations

soundfileoptionalFor reading/writing audio files in examples and typical use cases

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mpariente/pystoi ↗

packagehttps://pypi.org/project/pystoi/ ↗