🐦 SongbirdCam

North American Songbird Detection Web App — Raspberry Pi

A self-hosted web application that detects and identifies North American songbirds from RTSP camera streams using AI, saves JPEG snapshots to a local database, and displays Camect-style statistics and detection history. No cloud, no subscription.

---

Features

Feature	Description
RTSP Detection	Ingests any RTSP camera stream (IP cams, NVR, etc.)
Bird Detection	YOLOv8 visual detection (bird present in frame)
Species ID	BirdNET TFLite (984 NA species via audio) + NABirds visual classifier
Detection Delay	Configurable per-detection cooldown to avoid flooding
JPEG Snapshots	Cropped bird image saved per detection
SQLite Database	All detections stored locally, no cloud needed
Dashboard	Total detections, unique species, today's count, rarest sighting
Timeline Chart	Daily detection counts over selected date range
Species Donut	Top species breakdown
Heatmap	Hour × day-of-week activity pattern
Gallery	Paginated photo gallery filterable by species/date
Species Leaderboard	Ranked table with detection counts and confidence
Settings UI	Configure RTSP streams, delay, confidence, region
Raspberry Pi	Runs on Pi 4B (2GB+) or Pi 5

---

Quick Start (Raspberry Pi)

git clone https://github.com/youruser/songbirdcam
cd songbirdcam
bash setup_pi.sh

Then open http://<pi-ip>:5000 in your browser.

---

Manual Install

# 1. Create a virtual environment
python3 -m venv venv && source venv/bin/activate

# 2. Install Python dependencies
pip install flask opencv-python-headless ultralytics tflite-runtime numpy pillow

# 3. Run the app
python app.py

Visit http://localhost:5000

---

AI Models

Visual Detection — YOLOv8

• Base model: yolov8n.pt (COCO class 14 = bird)
• Species model: Fine-tune on NABirds V1 (400 North American species, 48k images)
• Recommended fine-tune: EfficientNetB2 or YOLOv8s on NABirds dataset

Audio Species ID — BirdNET

• Model: BirdNET v2.4 TFLite (Cornell Lab / Chemnitz University)
• Coverage: 984 North American + European species
• Input: 3-second audio chunks extracted from RTSP audio track via FFmpeg
• Download: BirdNET-Analyzer releases

---

Hardware Requirements

Hardware	Minimum	Recommended
Raspberry Pi	Pi 4B 2GB	Pi 5 4GB
Storage	16GB SD card	64GB SSD
Camera	Any RTSP-capable IP cam	PoE cam with clear view
Microphone	Optional (for BirdNET audio)	USB mic near feeder

---

RTSP Camera Setup

Most IP cameras and NVRs provide RTSP streams. Common URL formats:

rtsp://admin:password@192.168.1.100:554/stream1
rtsp://192.168.1.100:554/live/ch00_0
rtsp://192.168.1.100/h264Preview_01_main

Add your URL(s) in Settings → RTSP Streams.

---

Directory Structure

songbirdcam/
├── app.py              # Flask web app + REST API
├── detector.py         # RTSP stream capture + YOLOv8 detection pipeline
├── classifier.py       # Species classification (BirdNET + NABirds)
├── templates/
│   └── index.html      # Single-page web UI
├── detections/         # Saved JPEG snapshots
├── models/             # TFLite model files (BirdNET)
├── songbird.db         # SQLite database (auto-created)
├── setup_pi.sh         # Raspberry Pi installer
└── requirements.txt

---

API Reference

Endpoint	Method	Description
/api/detections	GET	Paginated detections (filter: species, days, page)
/api/detections/<id>	DELETE	Delete a detection + its image
/api/stats/overview	GET	Summary stats (total, species count, today, rarest)
/api/stats/by_species	GET	Detections grouped by species
/api/stats/by_day	GET	Daily detection counts
/api/stats/by_hour	GET	Hourly distribution
/api/stats/heatmap	GET	Hour × day_of_week counts for heatmap
/api/settings	GET/POST	Read/write configuration
/api/streams	GET/POST	List / add RTSP streams
/api/streams/<id>	DELETE	Remove a stream
/api/detector/start	POST	Start detection engine
/api/detector/stop	POST	Stop detection engine
/api/detector/status	GET	Running status

---

Species Classification Roadmap

1. Phase 1 (current): YOLOv8 detects "bird" class → BirdNET audio ID
2. Phase 2: Fine-tune YOLOv8s or EfficientNetB2 on NABirds V1 (400 species)
3. Phase 3: Combine visual + audio scores for higher confidence ID

---

Credits

• BirdNET — Cornell Lab of Ornithology & Chemnitz University
• NABirds — Cornell Lab of Ornithology
• Ultralytics YOLOv8
• Inspired by Camect and BirdNET-Pi

---

License

MIT License. Free to use and modify.