Этот репозиторий представляет собой baseline (базовое решение) для участия в хакатоне ReVoice-2025. Проект основан на модели Miipher и адаптирован для соревнования. Мы постарались сделать код максимально чистым, быстрым и удобным.

Рекомендуется использовать Python 3.10.11.

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 

Скрипт автоматически скачает веса Miipher и HiFiGAN в папку ./models.

python3 scripts/download_weights.py

Для обучения модели требуется подготовленный датасет (clean + noisy аудио + фонемы). Скрипт берет вашу папку с чистым аудио, зашумляет его (используя конфиг деградера) и генерирует фонемы (используя GigaAM для транскрипции, если нет текста).

Важно: Перед запуском отредактируйте examples/configs/degrader_config.yaml, указав путь к вашим шумовым файлам (параметр noise_dir и т.д., если используется).

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

Все настройки обучения находятся в examples/configs/config.yaml. Основные параметры, которые нужно проверить:

• data.train_dataset_path: Путь к папке, которую вы создали на шаге 3.
• data.val_dataset_path: Путь к валидационной выборке.
• train.trainer.devices: Количество и номера GPU (по умолчанию 1).

python3 examples/train.py

Следите за ходом обучения и метриками:

tensorboard --logdir logs/

Для восстановления речи из зашумленных файлов используйте скрипт run_miipher.py. Он принимает папку с входными файлами и папку для сохранения результата.

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

Аргументы:

• --input_dir: Папка с зашумленными файлами (.wav, .mp3, .flac).
• --output_dir: Папка, куда будут сохранены восстановленные файлы.
• --lang_code: Код языка для фонетизации (по умолчанию rus). Если есть текстовые транскрипты (.txt), скрипт попытается их найти. Иначе будет использован ASR (GigaAM).

Для подсчета метрик (SI-SNR, STOI, MelLoss) используйте eval.py. Скрипт сравнивает папку с восстановленными файлами (гипотезы) и папку с чистыми эталонными файлами (референсы).

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

Аргументы:

• --hyp_dir: Папка с вашими восстановленными файлами.
• --ref_dir: Папка с чистыми оригинальными файлами (файлы должны иметь совпадающие имена).
• --output_csv: Путь для сохранения таблицы с результатами (по умолчанию metrics_results.csv).

• examples/train.py — Основной скрипт запуска обучения.
• examples/configs/config.yaml — Конфигурация гиперпараметров, путей и модели.
• run_miipher.py — Скрипт для запуска инференса на папке.
• eval.py — Скрипт для подсчета метрик на папке.
• scripts/prepare_dataset.py — Скрипт генерации датасета (аугментация + фонемизация).
• scripts/download_weights.py — Загрузчик весов.
• src/miipher/lightning_module.py — Логика обучения (Pytorch Lightning), шаг обучения, валидация, метрики.
• src/miipher/dataset — Логика загрузки данных (Dataset, DataModule).
• src/miipher/metrics/eval_metrics.py — Реализация метрик SI-SNR, STOI, MelLoss.