This repository provides a clear, reproducible baseline for the BirdCLEF 2025 challenge using log‑mel spectrogram features and a Random Forest classifier. It is organized for portfolio readability and practical reuse.
- Goal: detect bird species from audio soundscapes (BirdCLEF 2025).
- Approach: extract log‑mel spectrogram features, train a classical model (Random Forest) as a strong baseline, and provide an end‑to‑end pipeline from exploration to inference.
- Status: baseline complete and reproducible; room for improvements listed in Roadmap.
notebooks/: ordered notebooks forming the pipeline (from EDA to inference)data/: raw and intermediate data (ignored in Git)processed/: processed features and artifacts (ignored)images/: optional figures exported from notebooks (ignored)requirements.txt: Python dependenciesMakefile: convenience targets for env setup and notebook utilities
eda.ipynb— Quick exploratory data analysis.01-metadata-exploration.ipynb— Explore dataset metadata and taxonomy.02-loadlisten-sample.ipynb— Load sample audio withlibrosaand listen to clips.03-fourierTransformation-melSpectogram.ipynb— Fourier transforms and mel spectrograms.04-denoise.ipynb— (Optional) Denoising experiments withnoisereduce.05-humanVoice-trim.ipynb— Remove speech and chunk audio (5s).06-feature-extraction.ipynb— Compute log‑mel spectrogram features.07-featureEngineering-modelTraining.ipynb— TrainRandomForestClassifieron features.08-testing-pipeline.ipynb— End‑to‑end test on training soundscapes.09-inference.ipynb— Generate predictions/submission with saved model & encoder.
- Python: 3.10+ recommended.
- Create and activate a virtualenv, then install requirements:
python -m venv .venv && source .venv/bin/activatepip install -r requirements.txt
- Download the BirdCLEF 2025 dataset from Kaggle.
- Place raw audio/metadata under
data/(kept out of Git). - Large artifacts (trained models, encoders, processed features) are also ignored by default.
- Run notebooks in order from
notebooks/to reproduce the baseline. - After training,
notebooks/09-inference.ipynbcreates a submission using saved model and label encoder (configure paths at the top of the notebook). - Optional: strip notebook outputs before committing to keep diffs small:
pip install nbstripout && nbstripout --install && nbstripout notebooks/*.ipynb
- Model: Random Forest on log‑mel spectrogram features.
- Observed: achieves a reasonable baseline on validation; exact metrics depend on split and preprocessing (see
07-...and08-...notebooks for details). - Artifacts: model and label encoder saved locally (ignored from Git).
- Upgrade model family (e.g., CNNs on spectrograms or audio transformers).
- Add cross‑validation and hyperparameter tuning (Optuna/RandomizedSearchCV).
- Improve data augmentation and noise handling.
- Refactor shared logic from notebooks into small utility modules for reuse.
- Optional automation with Papermill to run the pipeline end‑to‑end.
- Developed with
scikit-learn==1.2.2andnumpy==1.23.5; seerequirements.txtfor more. .gitignoreexcludes datasets, large artifacts, and transient files.- No external secrets or tokens are stored in this repo.