BirdLense Hub — Overview
BirdLense Hub is open-source software for smart bird feeder and garden monitoring: it detects birds (and squirrels) on video, classifies species with on-device ML, records clips, and ties everything into a timeline you own.
Why it exists
- Privacy-first: processing runs on your machine (Docker). No vendor cloud for core recognition.
- Works with gear you already use: Go2RTC for streams, optional Frigate + Bird Classification, BirdNET over MQTT, Home Assistant, Telegram.
- Citizen science friendly: exports to eBird and iNaturalist, regional comparisons, dataset tools for retraining.
Who it’s for
| Audience | Start here |
|---|---|
| Home / nature enthusiast | INSTALL → SCENARIOS |
| Frigate / Home Assistant user | SCENARIOS (Frigate + MQTT), CONFIGURATION |
| Developer / contributor | LOCAL_DEV, Contributing, ARCHITECTURE |
| Writer / advocate | This page + FEATURES — factual bullets for articles and landing copy |
What runs where
- One container bundles nginx, the web API (Flask), optional MCP, and the processor (video pipeline, YOLO, ByteTrack, FFmpeg, MQTT client).
- Outside the container: Go2RTC (recommended), MQTT broker, optional Frigate, BirdNET-Pi/Go, ESPHome/Tasmota for feeders and sensors.
See the diagram and data paths in ARCHITECTURE.
Recognition stack (short)
- Detector + classifier (YOLO family): bird/squirrel in frame, then species. Default EU-oriented model (~491 species); US (NABirds) weights available — see TRAINING.
- Frigate can supply Bird Classification
sub_label; results merge with video ML. - BirdNET audio events merge in a time window when MQTT is configured.
Documentation map
| Need | Document |
|---|---|
| Install & deploy | INSTALL |
| “How do I set up X?” | SCENARIOS |
| Every knob in YAML/UI | CONFIGURATION |
| Terminology | GLOSSARY |
| Feature matrix & API hints | FEATURES |
| Something broke | TROUBLESHOOTING |
| Tests & post-deploy checks | TESTING |
| Full doc index | docs/README |
| Static site section map | SITE_MAP |
Machine-readable API: OpenAPI (YAML).
Building a site or blog from this repo
Use this file as the narrative “what & why”, INSTALL + SCENARIOS as getting-started chapters, FEATURES as a capability page, ARCHITECTURE for a technical deep dive. Conventions (placeholders, bilingual files): Documentation. Status of translations: I18N_STATUS.
Version
Current release line: see root README badge and Changelog.