CaiusX/birdbrain

BirdBrain — real-time bird species recognition from African wildlife livestreams. BirdNET on a Raspberry Pi 5. # birdbrain Real-time bird species recognition from live African wildlife cams. Pulls audio from public Africam YouTube streams, runs BirdNET on rolling 3-second chunks, and surfaces detections on a small self-hosted dashboard. Runs on a single Raspberry Pi 5. The live playtest is at ** ** — read-only public view; admin actions are LAN-only. ## What's on the dashboard - **Activity map** — each site is a 24-hour clock dial sized by unique- species count over the last 24 h. - **Recent detections feed** — live, 5-second refresh, with per-detection spectrograms. - **Per-species page** with a Wikipedia photo, natural-range map, sample clips, hour-of-day / daily / confidence histograms, and AI commentary. - **Per-site page** with the live YouTube embed, recent unique species, and AI site commentary. - **Daily soundscape brief** — Claude-generated overall + per-site bullets written once per UTC day. ## Running it **Setting it up yourself?** New to this — `GETTING-STARTED.md` is a gentle, plain-language walkthrough; `INSTALL.md` is the detailed reference (Raspberry Pi or desktop, from clone to always-on services). Deploy is bare systemd user services on a Raspberry Pi 5 (Debian Bookworm, Python 3.12, `uv`). Two services: - **`birdbrain-pipeline`** — one worker per source; yt-dlp → ffmpeg → BirdNET. - **`birdbrain-web`** — FastAPI + Jinja + HTMX dashboard on `:8765`. Sources live in `sources.toml` (file-managed) or can be added at runtime via `/admin`. Either kind can be toggled on/off from `/admin` without a restart — the supervisor reconciles every 15 s. Background workers (in the web process) need an `ANTHROPIC_API_KEY` (loaded from `/etc/birdbrain/secrets.env`) to write the per-species, per-site and daily AI commentary. The detection pipeline does not need it. Public exposure is via Cloudflare Tunnel (`cloudflared` user service); `/admin` and all mutating endpoints return 404 over the tunnel, so the public side is effectively read-only without app-level auth. …