scripts/REALTIME_README.md

# 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:

```bash
pip install sounddevice numpy librosa onnxruntime soundfile
```

## Usage

### Basic Usage

Start real-time detection with default settings:

```bash
python realtime_detection.py
```

### Advanced Options

```bash
# 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:

```bash
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:**

```bash
# 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:**

```bash
# 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

```bash
# Conservative detection for mixed environment
python realtime_detection.py --confidence 0.2 --top-k 3
```

### Bird Walk

```bash
# Sensitive detection for bird-rich areas
python realtime_detection.py --confidence 0.1 --top-k 8 --update-interval 0.5
```

### Indoor Testing

```bash
# High threshold for testing with recorded sounds
python realtime_detection.py --confidence 0.4 --top-k 5
```

## Tips for Best Results

1. **Positioning**: Place microphone outdoors or near open windows
2. **Timing**: Early morning and evening are typically best for bird activity
3. **Environment**: Quiet locations with minimal human/traffic noise
4. **Distance**: Microphone should be within 10-20 feet of singing birds
5. **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.
```