BirdNET Real-Time Detection
Real-time bird species detection using your microphone and the BirdNET ONNX model.
Features
🎤 Live Microphone Input: Continuously captures and analyzes audio from your microphone 🐦 Real-Time Detection: Identifies bird species as they sing with configurable confidence thresholds 📊 Live Display: Dynamic terminal interface showing current detections and recent activity ⚡ Optimized Performance: Efficient audio processing with rolling buffers and threading 🔧 Configurable: Adjustable confidence thresholds, update intervals, and display options
Installation
Manual Installation
Install required packages:
pip install sounddevice numpy librosa onnxruntime soundfile
Usage
Basic Usage
Start real-time detection with default settings:
python realtime_detection.py
Advanced Options
# Higher confidence threshold for fewer false positives
python realtime_detection.py --confidence 0.3
# Show more detections
python realtime_detection.py --top-k 10
# Faster display updates
python realtime_detection.py --update-interval 0.5
# Custom model and labels
python realtime_detection.py --model custom_model.onnx --labels custom_labels.txt
List Audio Devices
To see available microphones:
python realtime_detection.py --list-devices
Command Line Arguments
--model: Path to ONNX model file (default:model.onnx)--labels: Path to species labels file (default:BirdNET_GLOBAL_6K_V2.4_Labels.txt)--confidence: Minimum confidence threshold (default: 0.1)--top-k: Number of top predictions to show (default: 5)--update-interval: Display update interval in seconds (default: 1.0)--list-devices: List available audio input devices
Display Interface
The real-time interface shows:
Current Detections
🐦 Current Detections (Top 5):
----------------------------------------
1. American Robin
████████████░░░░░░░░ 0.8542
2. Song Sparrow
██████░░░░░░░░░░░░░░ 0.3214
Recent Activity
📊 Recent Activity (Last 10):
----------------------------------------
14:25:32 - American Robin (0.854)
14:25:28 - Song Sparrow (0.321)
14:25:15 - House Finch (0.287)
Technical Details
Audio Processing
- Sample Rate: 48kHz (BirdNET requirement)
- Window Size: 3 seconds (144,000 samples)
- Buffer: 6-second rolling buffer for continuous analysis
- Processing: 100ms audio blocks with threaded processing
Performance Features
- Non-blocking Audio: Uses threading for audio capture and processing
- Efficient Buffering: Rolling deque buffer prevents memory buildup
- Real-time Display: Separate thread for UI updates
- Graceful Shutdown: Ctrl+C handling for clean exit
Requirements
- Python: 3.7+ (recommended: 3.9+)
- Audio Input: Working microphone or audio input device
- Memory: ~200MB RAM for model and audio buffers
- CPU: Moderate CPU usage for real-time inference
Troubleshooting
Audio Issues
No microphone detected:
# List available devices
python realtime_detection.py --list-devices
# Check system audio settings
# Ensure microphone permissions are granted
Audio quality issues:
- Check microphone positioning (closer to birds)
- Reduce background noise
- Adjust confidence threshold
Performance Issues
High CPU usage:
# Reduce update frequency
python realtime_detection.py --update-interval 2.0
# Increase confidence threshold
python realtime_detection.py --confidence 0.3
Memory issues:
- Close other applications
- The detector uses fixed-size buffers to prevent memory leaks
Detection Issues
No detections:
- Lower confidence threshold:
--confidence 0.05 - Check if birds are actually singing
- Verify microphone is working
Too many false positives:
- Increase confidence threshold:
--confidence 0.3 - Reduce background noise
- Position microphone outdoors
Example Sessions
Backyard Birding
# Conservative detection for mixed environment
python realtime_detection.py --confidence 0.2 --top-k 3
Bird Walk
# Sensitive detection for bird-rich areas
python realtime_detection.py --confidence 0.1 --top-k 8 --update-interval 0.5
Indoor Testing
# High threshold for testing with recorded sounds
python realtime_detection.py --confidence 0.4 --top-k 5
Tips for Best Results
- Positioning: Place microphone outdoors or near open windows
- Timing: Early morning and evening are typically best for bird activity
- Environment: Quiet locations with minimal human/traffic noise
- Distance: Microphone should be within 10-20 feet of singing birds
- Weather: Calm, clear conditions provide best audio quality
Stopping Detection
Press Ctrl+C at any time to stop the real-time detection and return to terminal.
The detector will display:
🛑 Detection stopped.