Python implementation of the cyclic MVDR beamformer — an extension of the classic MVDR that exploits both spatial and spectral correlations to better suppress almost-periodic noise (e.g., engines, fans, musical instruments).

By exploiting correlations across microphones and frequency components, the cyclic minimum-variance distortionless-response (cMVDR) beamformer achieves improved noise reduction, especially in low signal-to-noise ratio (SNR) scenarios. The package includes tools for estimating resonant frequencies via periodogram analysis and computing optimal frequency shifts for inharmonic signals.

Applicable to speech enhancement, hearing aids, smart devices, and acoustic scene analysis.

📖 Paper https://arxiv.org/abs/2510.18391v1

🖥️ Code https://github.com/Screeen/cmvdr/

• Python 3.9+ (for compatibility with librosa). Tested on Python 3.11 too.
• Tested on macOS 14.4.1 and on Ubuntu 24.04.3 LTS.

The Python package can be cloned using pip and installed:

1. Clone the repository:

git clone [email protected]:Screeen/cmvdr.git
cd cmvdr

2. Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package in editable mode:

pip install --upgrade pip
pip install -e .

This will automatically install all dependencies defined in pyproject.toml.

After installation, verify that the package is properly installed:

python -c 'import cmvdr; print("cMVDR package successfully imported!")'

To verify the installation, run the provided tests:

python -m unittest discover -s tests

To quickly test the cMVDR implementation, run the demo script:

source script/run_demo.sh

After installation, you can use the cmvdr and cmvdr-eval command line tools. This is the easiest way to apply the cMVDR beamformer and evaluate its performance. cmvdr runs the beamforming algorithm on a specified file or folder, while cmvdr-eval evaluates the quality of the output. For usage instructions, run:

cmvdr --help
usage: cmvdr [-h] -i INPUT_PATH [-o OUTPUT_PATH] [-n NOISE_PATH] [-v]

Run cMVDR inference on a single file or a folder of audio files.

options:
  -h, --help            show this help message and exit
  -i INPUT_PATH, --input_path INPUT_PATH
                        Path to the input audio file or folder.
  -o OUTPUT_PATH, --output_path OUTPUT_PATH
                        Path to the output folder. If not provided, output will be saved in the same folder as input.
  -n NOISE_PATH, --noise_path NOISE_PATH
                        Path to the noise audio file or folder (optional, to estimate noise frequency). To match input
                        files, append _fileid_123.wav to the noise and the noisy files.
  -v, --verbose         If set, print detailed logs to the console.

and

cmvdr-eval --help
usage: cmvdr-eval [-h] -d FOLDER_DENOISED [-r FOLDER_REFERENCE] [--sort-by-snr]

Evaluate audio files in a folder.

options:
  -h, --help            show this help message and exit
  -d FOLDER_DENOISED, --folder_denoised FOLDER_DENOISED
                        Path to the folder containing denoised audio files.
  -r FOLDER_REFERENCE, --folder_reference FOLDER_REFERENCE
                        Path to the folder containing clean reference audio files (optional).
  --sort-by-snr         Sort results by SNR brackets (optional). Default is False.

📝 Note: After installing the package with pip install -e ., you can run experiments directly from the repository root directory.

Experiment parameters are controlled via YAML files in the configs/ folder. Edit cmvdr.yaml and default.yaml to set your desired parameters such as:

• data_type (choose from synthetic or instruments)
• num_montecarlo_simulations
• ...

source script/run_synthetic.sh

source script/run_all.sh

python main.py --data_type synthetic  # or instruments

To apply the cMVDR beamformer to your own audio files, you can use the inference script. This script processes audio files in a specified folder and saves the output to another folder.

After installing the package, run:

python -m script.cmvdr_inference

Specify the folder containing audio files in the configs/inference_cmvdr.yaml YAML file:

data:
  input_dir: ../datasets/test_cmvdr/noisy
  output_dir: ../datasets/test_cmvdr/noisy_output

As an alternative, you can run the script directly from the command line, using for example the demo audio files:

cmvdr --input_dir ./demos/noisy --output_dir ./demos/noisy_output

Synthetic data experiments require downloading room impulse responses (RIRs) and clean speech:

• RIRs: https://www.iks.rwth-aachen.de/en/research/tools-downloads/databases/multi-channel-impulse-response-database/
• Speech: Speech Intelligibility CD by Neil Thompson Shade

Instrument data experiments also require downloading instrument samples:

• Instrument samples: https://theremin.music.uiowa.edu/MIS.html.

If you get

ImportError: cannot import name 'kaiser' from 'scipy.signal' (.../.venv/lib/python3.X/site-packages/scipy/signal/__init__.py). Did you mean: 'kaiserord'?

Open the file

nano .../SVD-direct/env/lib/python3.X/site-packages/pysepm/util.py

and replace

from scipy.signal import firls,kaiser,upfirdn

with

from scipy.signal import firls,upfirdn
from scipy.signal.windows import kaiser

If you don't have uv installed or prefer using standard pip, use Method 1 above or:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate  
pip install --upgrade pip
pip install -e .  # Use -e for editable installation

If you installed the package with pip install -e . and have import issues, make sure:

1. Your virtual environment is activated
2. You're running Python from the correct environment
3. The installation completed without errors

You can verify the package is installed by running:

pip list | grep cmvdr

Your Python package (sounddevice or something else that uses PortAudio) can’t find the underlying PortAudio C library on your system. Installing the Python package alone isn’t enough — the native library must also be installed. How you fix it depends on your OS. You can still run the experiments, but you won't be able to listen to the audio output.

ImportError: numpy.core.multiarray failed to import (auto-generated because you didn't call 'numpy.import_array()' after cimporting numpy; use '<void>numpy._import_array' to disable if you are certain you don't need it).
-bash: read: `REPLY?Press enter to exit': not a valid identifier

This error can occur if you have an incompatible version of NumPy installed. Run

pip install https://github.com/ludlows/python-pesq/archive/master.zip