Upload README.md

README.md

@@ -0,0 +1,115 @@
+# 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.
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+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
+
+```bash
+python3 examples/train.py
+```
+
+### 6. Monitoring (TensorBoard)
+
+Monitor training progress and metrics:
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+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.
+