MTUCI / ru-Miipher

ReVoice-2025 — Speech Enhancement Hackathon (Baseline)

This repository represents a baseline (basic solution) for participating in the ReVoice-2025 hackathon. The project is based on the Miipher model and adapted for the competition. We tried to make the code as clean, fast, and convenient as possible.

🚀 Quick Start

1. Environment Setup

Python 3.10.11 is recommended.

git clone https://github.com/mtuciru/ReVoice-2025
cd ReVoice-2025

python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt
pip install --no-dependencies git+https://github.com/Wataru-Nakata/ssl-vocoders.git

export PYTHONPATH=./src 

2. Downloading Pre-trained Weights

The script will automatically download Miipher and HiFiGAN weights to the ./models folder.

python3 scripts/download_weights.py

3. Dataset Preparation

Training the model requires a prepared dataset (clean + noisy audio + phonemes). The script takes your folder with clean audio, adds noise (using the degrader config), and generates phonemes (using GigaAM for transcription if no text is present).

Important : Before running, edit examples/configs/degrader_config.yaml , specifying the path to your noise files ( noise_dir parameter etc., if used).

python3 scripts/prepare_dataset.py \
  --input_dir /path/to/clean_audio \
  --output_dir /path/to/processed_dataset \
  --degrader_config examples/configs/degrader_config.yaml

4. Training Configuration

All training settings are located in examples/configs/config.yaml . Main parameters to check:

• data.train_dataset_path : Path to the folder you created in step 3.
• data.val_dataset_path : Path to the validation set.
• train.trainer.devices : Number and IDs of GPUs (default 1 ).

5. Starting Training

python3 examples/train.py

6. Monitoring (TensorBoard)

Monitor training progress and metrics:

tensorboard --logdir logs/

7. Inference (Speech Restoration)

To restore speech from noisy files, use the run_miipher.py script. It takes a folder with input files and a folder to save the result.

python3 scripts/run_miipher.py \
  --input_dir /path/to/noisy_audio \
  --output_dir /path/to/restored_audio \
  --lang_code rus \
  --miipher_ckpt ./models/miipher.ckpt \
  --vocoder_ckpt ./models/hifigan.ckpt

Arguments:

• --input_dir : Folder with noisy files ( .wav , .mp3 , .flac ).
• --output_dir : Folder where restored files will be saved.
• --lang_code : Language code for phonetization (default rus ). If text transcripts ( .txt ) exist, the script will try to find them. Otherwise, ASR (GigaAM) will be used.

8. Quality Evaluation (Metrics)

To calculate metrics (SI-SNR, STOI, MelLoss), use eval.py . The script compares the folder with restored files (hypotheses) and the folder with clean reference files (references).

python3 eval.py \
  --hyp_dir /path/to/restored_audio \
  --ref_dir /path/to/clean_reference_audio \
  --output_csv metrics_results.csv

Arguments:

• --hyp_dir : Folder with your restored files.
• --ref_dir : Folder with clean original files (files must have matching names).
• --output_csv : Path to save the results table (default metrics_results.csv ).

📂 Project Structure

• examples/train.py — Main script for starting training.
• examples/configs/config.yaml — Configuration for hyperparameters, paths, and the model.
• run_miipher.py — Script for running inference on a folder.
• eval.py — Script for calculating metrics on a folder.
• scripts/prepare_dataset.py — Script for dataset generation (augmentation + phonemization).
• scripts/download_weights.py — Weight downloader.
• src/miipher/lightning_module.py — Training logic (Pytorch Lightning), training step, validation, metrics.
• src/miipher/dataset — Data loading logic (Dataset, DataModule).
• src/miipher/metrics/eval_metrics.py — Implementation of SI-SNR, STOI, MelLoss metrics.