birdie-pi — Modular BirdNET Detection System

Repository: https://github.com/netnutmike/birdie-pi
Language: Python (services) + React/TypeScript (frontend)
License: MIT
Status: Active Development
Created: February 22, 2026
Last Updated: March 24, 2026

What It Does

A distributed, microservices-based bird detection platform built on BirdNET AI. Deploy multiple audio listeners (Raspberry Pis or standard hardware) across different locations, centralize species identification processing via the BirdNET ML model, and explore detections through a modern web dashboard.

Key capability: Identify 6,000+ bird species in real-time using AI, with notifications, web dashboard, and citizen science integration.

Architecture Overview

Edge Devices (Listeners)
    ↓ Audio Segments (Redis/MQTT)
Message Queue (Redis or MQTT)
    ↓ Consume
Decoder Service (BirdNET processing)
    ↓ Detections
API Backend (FastAPI, Python)
    ↔ Database (PostgreSQL or SQLite)
    ↓ HTTP/WebSocket
Web Frontend (React/TypeScript)

Components:

  • Listener Service — Audio capture on edge devices (sample rate, device config, segment duration)
  • Decoder Service — BirdNET ML model processing (confidence threshold, species filtering)
  • API Backend — FastAPI REST API, database, integrations (email, Discord, Slack, Pushover via Apprise)
  • Web Frontend — React dashboard with detections, spectrograms, analytics, live streams
  • Message Queue — Redis or MQTT for async communication
  • Database — PostgreSQL (production) or SQLite (dev)

Features

✅ Distributed Audio Capture — Multiple listeners on Raspberry Pis or other hardware
✅ Real-time Bird Detection — 6,000+ species via BirdNET AI
✅ Notifications — Email, Discord, Slack, Pushover (Apprise integration)
✅ Web Dashboard — Browse detections, spectrograms, analytics, live audio streams
✅ BirdWeather Integration — Contribute to citizen science platform
✅ Species Images — eBird / Macaulay Library photos
✅ Multi-Deployment — Docker Compose (single-host) or Kubernetes (distributed)
✅ Multi-Architecture — Docker images for arm64 (Raspberry Pi) and amd64

Quick Start

Prerequisites

  • Docker + Docker Compose
  • For development: Python 3.11+, Poetry, Node.js 18+

1. Clone and configure

git clone https://github.com/netnutmike/birdie-pi.git
cd birdie-pi
cp config/.env.example .env
# Edit .env with your settings

2. Start services

docker-compose up -d

3. Access dashboard

Open http://localhost:3000 in browser.

Tech Stack

  • Backend: Python 3.11+, FastAPI, Poetry
  • Frontend: React, TypeScript, Node.js 18+
  • Infrastructure: Docker, Docker Compose, Kubernetes
  • Message Queue: Redis or MQTT
  • Database: PostgreSQL (prod) or SQLite (dev)
  • ML Model: BirdNET (Cornell Lab of Ornithology)

Documentation

  • User Guide — Installation, config, daily usage
  • Developer Guide — Architecture, local dev, testing
  • API Documentation — REST endpoints, WebSocket, auth (also at /docs when running)
  • Deployment Guide — Docker Compose, Kubernetes, Raspberry Pi
  • SETUP.md — Quick reference for project setup

Status & Notes

Current State (as of March 24, 2026):

  • Core microservices implemented and tested
  • Docker Compose setup functional (both production and development)
  • Installation script working for Raspberry Pi deployments
  • Kubernetes manifests ready for distributed deployments
  • Documentation complete (user guide, developer guide, API docs, deployment guide)

Outstanding:

  • Field deployment validation (real bird detection testing across multiple Pis)
  • Performance tuning for sustained 24/7 operation
  • Raspberry Pi resource optimization (CPU, memory, storage)
  • BirdWeather integration testing in production
  • Community contributions and feedback loop

Known Considerations:

  • BirdNET model performance varies by region and season
  • Microphone quality critical for accurate detection
  • Network bandwidth depends on audio segment frequency and quality
  • Database growth with long-running deployments (retention policies needed)

Deployment Scenarios

Single-Host Docker Compose

Ideal for testing and small deployments:

docker-compose up -d

Distributed Kubernetes

For scaled multi-location deployments:

kubectl apply -f deploy/k8s/

Raspberry Pi Cluster

Multiple Pis running listeners + central processing server:

bash scripts/install.sh  # On each Pi

Key Integrations

  • BirdWeather — Citizen science platform (contribute detections)
  • Apprise — Multi-platform notifications (email, Discord, Slack, Pushover, SMS, etc.)
  • eBird / Macaulay Library — Bird species photos and information
  • BirdNET — AI model by Cornell Lab of Ornithology

Next Steps for Development

  1. Deploy to test environment with 2-3 Raspberry Pis
  2. Validate bird detection accuracy and notification delivery
  3. Monitor system performance under 24/7 operation
  4. Gather user feedback and refine UX
  5. Document deployment best practices and lessons learned

Project file created April 2, 2026. For the latest code, see GitHub: https://github.com/netnutmike/birdie-pi