birdzam

Birdzam Audio Classifier

A deep learning project for bird audio classification using mel-spectrograms and convolutional neural networks. The model is trained on bird recordings from Poland, sourced from the GBIF Xeno-canto dataset, with support for data augmentation and class balancing.

Features

• Mel-Spectrogram Processing: Converts audio waveforms to mel-spectrograms for deep learning
• Data Augmentation: Time-shifting and volume adjustment for underrepresented classes
• Stratified Dataset Splitting: 75% train, 15% validation, 10% test with balanced class distribution
• Class Weighting: Handles class imbalance using weighted loss and balanced sampling
• Comprehensive Metrics: Per-class accuracy, precision, recall, F1-score, and confusion matrix
• Training Checkpoints: Save and resume training progress

Dataset

This project uses bird audio recordings from the Xeno-canto - Bird sounds from around the world dataset available on GBIF (Global Biodiversity Information Facility).

Dataset Selection Criteria

• Geographic Filter: Only recordings from Poland
• Minimum Duration: Audio clips must be at least 5 seconds long
• Occurrence Threshold: Only bird species with more than 100 recordings were included
• Audio Processing: Longer recordings were split into 5-second chunks (maximum 6 chunks per recording)

Data Preparation Pipeline

1. Download and merge GBIF Darwin Core Archive files (multimedia, verbatim, occurrence)
2. Filter for audio files from Poland
3. Select species with sufficient representation (>100 occurrences)
4. Download audio files and split into 5-second segments
5. Convert to FLAC format at 44.1 kHz sample rate

Dataset Structure

data/audio/
├── taxonKey1/
│   ├── audio1.flac
│   ├── audio2.flac
│   └── ...
├── taxonKey2/
│   └── ...
└── taxonKeyN/
    └── ...

Each folder represents a bird species (identified by GBIF taxonKey), containing 5-second audio clips in FLAC format.

Audio Processing Pipeline

1. Waveform Loading: Load audio files using torchaudio
2. Augmentation (training only):
   • Volume adjustment: ±6 dB random gain
   • Time-shifting: Up to 40% of audio length
3. Mel-Spectrogram Conversion:
   • FFT size: 2048
   • Mel bins: 128
   • Amplitude to dB with 80 dB top
4. Normalization: Global mean and standard deviation

Data Augmentation

Augmentation is selectively applied to classes with fewer than 500 samples during training.

Training

Prepare Dataset

First, prepare the dataset by running the data preparation pipeline to download and process audio files from GBIF. Then initialize the dataset for training:

Training Configuration

• Optimizer: Adam (lr=0.0005, weight_decay=1e-4)
• Scheduler: OneCycleLR (max_lr=0.001)
• Loss: CrossEntropyLoss with class weights
• Batch Size: 64
• Sampler: WeightedRandomSampler for balanced batching

Evaluation

Metrics

Overall Accuracy: 0.7120
Precision (macro): 0.7146
Recall (macro): 0.7595
F1 Score (macro): 0.7220

Visualizations

Notes

• Classes with fewer than 500 samples are augmented during training
• The dataset is split with stratification to maintain class balance
• No data leakage: train, validation, and test sets are completely disjoint
• The model automatically uses GPU if available