Bird Agent

Bird sound recognition and language system — identify species and call types from audio recordings. CLI-first, with a Gradio web GUI.

Features

• Species identification from audio files or live microphone
• Call type classification — alarm, mating, contact, food, territorial, flight call, song
• CLI tool — 5 commands: analyze, batch, listen, train, download
• Gradio web GUI — file upload, mic recording, batch processing
• Multi-model — SimpleCNN (CPU-friendly), Bird-MAE (ViT-Base), PANNs CNN14 (fallback)
• Data pipeline — download from xeno-canto, process your own recordings
• Training — multi-task learning (species CE + behavior BCE), MLflow tracking
• Windows-compatible — works cross-platform

Quick Start

# Install
pip install -e .

# Analyze a file
bird-agent analyze ~/Downloads/bird.wav

# Launch web GUI
python gui.py
# → http://127.0.0.1:7860

CLI Commands

Command	Description
bird-agent analyze <file>	Classify one audio file
bird-agent batch <dir>	Scan all audio files → JSON/CSV
bird-agent listen	Live microphone inference
bird-agent train	Run training pipeline
bird-agent download	Download from xeno-canto

Examples

# Analyze with custom settings
bird-agent analyze recording.mp3 --top-k 3 --threshold 0.5

# Batch process a directory
bird-agent batch recordings/ --output results.csv --format csv

# Download training data
bird-agent download --species "Turdus merula" --country India --limit 100

GUI

python gui.py

Opens a web interface with 4 tabs:

Tab	Description
Analyze File	Upload audio → species predictions + spectrogram
Record Live	Mic recording → instant analysis
Batch Process	Multi-file upload → combined results
About	System info and documentation

Project Structure

bird-agent/
├── pyproject.toml              # Dependencies + entry point
├── configs/config.yaml         # Species list, audio params, model settings
├── src/bird_agent/
│   ├── data/
│   │   ├── downloader.py       # xeno-canto API wrapper
│   │   ├── preprocessor.py     # Resample, bandpass, trim, mel-spectrogram
│   │   └── dataset.py          # PyTorch Dataset + augmentations
│   ├── models/
│   │   ├── classifier.py       # Bird-MAE, PANNs, SimpleCNN
│   │   └── behavior.py         # Call type classifier head
│   ├── training/
│   │   ├── train.py            # Multi-task training loop
│   │   └── evaluate.py         # Metrics + confusion matrix
│   ├── inference/
│   │   ├── cli.py              # Click CLI (5 commands)
│   │   └── live.py             # Sounddevice streaming
│   └── utils/audio_utils.py    # Audio helpers
├── scripts/
│   ├── ingest_user_data.py     # Convert user audio → spectrograms
│   └── fix_paths.py            # Repair metadata CSV paths
├── gui.py                      # Gradio web interface
├── bird-caller.py              # Bird attraction sound generator
└── tests/test_preprocessor.py  # Unit tests

Input Audio Formats

Format	Extension
WAV	.wav
MP3	.mp3
FLAC	.flac
OGG	.ogg
M4A	.m4a (needs ffmpeg)
AIFF	.aiff

All formats are converted internally to 16kHz mono → 128×224 log-mel spectrograms.

Data Pipeline

Audio File → Resample 16kHz → Bandpass (500-12000 Hz)
  → Trim Silence → Split 5s chunks → Log-Mel Spectrogram
  → Model (SimpleCNN/Bird-MAE/PANNs) → Species + Call Types

Training Your Own Model

# 1. Download data
bird-agent download --species "Parus major" --limit 50

# 2. Run training
bird-agent train

# 3. Evaluate

Or use your own recordings:

# Place files in data/raw/<species_name>/
# Then ingest
python scripts/ingest_user_data.py

Training uses multi-task loss: α × CrossEntropy(species) + β × BCE(behavior) with AdamW optimizer and cosine LR schedule. Logged via MLflow.

Models

Model	Params	Status
SimpleCNN	~300K	✅ Works on CPU
Bird-MAE (ViT-Base)	~86M	⚠️ Needs transformers ≤4.x
PANNs CNN14	~80M	⚠️ Needs manual checkpoint download

Known Issues

• Bird-MAE incompatible with transformers 5.x — use pip install transformers==4.46.0 if needed
• PANNs uses wget on Windows — download checkpoint manually
• CPU-only training — GPU recommended for Bird-MAE

License

MIT