HackSmu-7

Elephant rumble isolation toolkit for noisy wildlife recordings.

What This Implements

• CSV-driven segmentation with 5-second windows.
• Butterworth bandpass preprocessing (10 Hz to 250 Hz).
• Log-Mel spectrogram feature generation.
• 2D U-Net mask estimator in PyTorch with skip connections.
• Hybrid training loss: spectrogram MSE + SDR loss term.
• Inference pipeline that reconstructs waveform using Griffin-Lim.

Expected Metadata CSV Format

Required columns:

• Selection
• Sound_file
• Start_time
• End_time
• Call_type

Install

pip install -r requirements.txt

Train

python main.py train --metadata_csv data/metadata.csv --audio_dir data/audio --output_dir checkpoints --epochs 40 --batch_size 8 --sr 2000 --call_type_filter contains_rumble

Example with Dice loss enabled/tuned:

python main.py train --metadata_csv data/metadata.csv --audio_dir data/audio --output_dir checkpoints --epochs 100 --batch_size 8 --sr 2000 --dice_weight 0.3 --call_type_filter contains_rumble

Notes:

• The default sample rate is 2000 Hz (sufficient to model energy up to 250 Hz).
• Ground-truth masks are derived from timestamp overlap inside each 5-second segment.
• Training objective can mix MSE, SDR, and Dice loss using --mse_weight, --sdr_weight, and --dice_weight.
• Training writes metrics to checkpoints/metrics.csv and plots to checkpoints/training_curves.png.
• Metrics include train/validation loss, MSE, SDR loss, mask precision, recall, F1, and IoU.

Inference

python main.py infer --metadata_csv data/metadata.csv --audio_dir data/audio --checkpoint checkpoints/best.pt --output_dir outputs --sr 2000 --call_type_filter contains_rumble

Output files are written as:

• isolated_[Selection]_[Original_Filename].wav

Each output clip is trimmed to the exact annotation interval defined by Start_time and End_time.

Project Files

• utils.py: data loading, filtering, segmentation, spectrogram conversion, mask generation, reconstruction.
• model.py: compact 2D U-Net for soft mask prediction.
• train.py: dataset and optimization loop.
• infer.py: batch inference over metadata selections.
• main.py: CLI entrypoint with train and infer commands.

GitHub Pages Hosting

You can host the web UI on GitHub Pages.

Important limitation:

• GitHub Pages is static hosting only. Python scripts such as training/inference (main.py, train.py, infer.py) do not run on Pages.

This repository now includes a workflow at .github/workflows/pages.yml that:

• Converts trimmed_raw/*.wav and outputs/*.wav into MP3 files.
• Publishes a static site artifact containing:
  • index.html
  • data/metadata.csv
  • trimmed_raw/*.mp3
  • outputs/*.mp3

To enable Pages deployment:

1. Push this repository to GitHub.
2. In GitHub, open Settings -> Pages.
3. Set Source to GitHub Actions.
4. Push to main (or run the workflow manually from Actions).

After deployment, your app will be available at:

• https://<your-username>.github.io/<your-repo-name>/

Notes:

• Keep audio files reasonably small; GitHub Pages is best for demos, not large-scale audio hosting.
• If no MP3 files exist in trimmed_raw or outputs, the UI will load but audio tracks will be missing.