BirdNET-NG Feature Roadmap

Phase 1 — Core Loop (MVP) ✅

The minimum viable distributed bird identification system.

P1.1 — Satellite Audio Capture ✅

• [x] Audio capture from USB/I2S microphone via ALSA (arecord)
• [x] 3-second chunking with configurable overlap
• [x] WAV encoding at 48kHz mono (BirdNET native sample rate)
• [x] Local disk storage (write-before-send)
• [x] SQLite outbox queue (sql.js, persisted to disk)
• [x] Simulated capture mode (sine wave) for development
• [x] Replay capture mode (real bird audio from WAV files) for testing

P1.2 — Satellite → Hub Transport ✅

• [x] MQTT client with auto-reconnect
• [x] Base64 audio payload with JSON metadata envelope
• [x] Outbox drain loop with exponential backoff
• [x] Hub-side acknowledgment (chunk marked acked only after storage confirmed)
• [x] Configurable retention policy for local cleanup

P1.3 — Hub Audio Ingestion ✅

• [x] MQTT subscriber receiving audio chunks
• [x] Store audio blobs in MinIO (keyed by {tenant_id}/{satellite_id}/{chunk_id}.wav)
• [x] Insert audio_chunks record in PostgreSQL
• [x] Enqueue processing job in BullMQ

P1.4 — Inference Worker ✅

• [x] BullMQ consumer pulling audio processing jobs (async Python worker)
• [x] Download audio from MinIO
• [x] Run BirdNET TFLite model (via birdnetlib, tflite-runtime 2.14)
• [x] Write detection results to PostgreSQL
• [x] Basic species identification with confidence scores
• [x] Geo-aware species filtering (location + date)

P1.5 — Web UI ✅

• [x] Dashboard: satellite status cards, recent detections, species count
• [x] Detection list with filtering (satellite, min confidence slider)
• [x] Audio playback for detections
• [x] Satellite fleet cards (status, location, CPU temp, storage, battery, uptime)
• [x] Tenant selector with "All Tenants" option
• [x] Dark theme, responsive layout
• [x] Spectrogram visualization (Cooley-Tukey FFT, Viridis colormap, 0–12kHz)

P1.6 — Multi-Tenancy Foundation ✅

• [x] Tenant registration and management
• [x] API key generation scoped to tenant (viewer, member, admin, satellite roles)
• [x] Row-level tenant isolation on all queries
• [x] Tenant-scoped MinIO paths
• [x] API key authentication middleware with role-based guards
• [x] Tenant scoping enforcement (scoped keys cannot access other tenants)
• [x] Internal API key for web frontend (cross-tenant admin)

P1.7 — Deployment ✅

• [x] Docker Compose for full 7-container hub stack
• [x] Traefik integration (HTTPS + MQTTS TLS termination)
• [x] Three FQDNs (web, MQTT, MinIO console)
• [x] All configuration via .env environment variables
• [x] Persistent storage via bind mounts
• [x] Satellite install script for Raspberry Pi

Phase 2 — Intelligence

Smart features that improve detection quality and user experience.

P2.1 — Geo-Aware Inference ✅

• [x] Satellite GPS coordinate reporting
• [x] Live GPS via gpsd for Pi satellites
• [x] Species range filtering based on location + month
• [x] BirdNET location filter integration in inference worker
• [x] Reduced candidate list → faster and more accurate inference

P2.2 — Rare Species Alerts ✅

• [x] Frequency-based rarity model (first sighting + low frequency detection)
• [x] Real-time alert generation on unusual detections
• [x] WebSocket push to connected UI clients (toast notifications)
• [x] Webhook support (Slack, custom URL)
• [x] Per-tenant custom watchlists (tenant settings, watchlist_species array)

P2.3 — Confidence-Based Re-Processing ✅

• [x] Configurable "uncertain" confidence band (default: 0.4–0.7)
• [x] Auto-requeue uncertain detections with lower threshold (0.05)
• [x] Second pass updates confidence with GREATEST(old, new)
• [x] Flag for human verification if still uncertain (pending_review)

P2.4 — Satellite Health & Telemetry ✅

• [x] Periodic telemetry reports from satellites (battery, storage, CPU, network)
• [x] Fleet dashboard in web UI (satellite cards with telemetry)
• [x] Satellite offline detection with configurable timeout
• [x] Alerts: offline, low storage, overheating, high packet loss

P2.5 — User Authentication & Authorization ✅

• [x] Email/password registration with bcrypt password hashing
• [x] JWT cookie-based sessions (httpOnly, secure, 7-day expiry)
• [x] Login and registration pages with form validation
• [x] Auth-gated routing (unauthenticated users see only login/register)
• [x] Auto-login after registration
• [x] Logout with cookie clearing
• [x] /api/auth/me endpoint returns current user + tenant memberships
• [x] Blocked user detection at login time

P2.6 — Multi-Tenant Membership ✅

• [x] Users are global (no tenant_id on users table)
• [x] Multi-tenant membership via tenant_members join table
• [x] Per-tenant roles: viewer, member, admin, owner
• [x] Tenant selector in sidebar for users with multiple memberships
• [x] Platform admin with cross-tenant access (via DB flag or env var)
• [x] Platform admin hidden from tenant member lists
• [x] Self-service tenant creation (gated by platform setting)

P2.7 — Invite System ✅

• [x] Admin-generated single-use invite links
• [x] Invite scoped to tenant + role (viewer, member, admin)
• [x] 72-hour default expiry (configurable per invite)
• [x] Registration via invite bypasses self-registration setting
• [x] Invite link displayed with copy-to-clipboard
• [x] Pending invite list with revoke capability
• [x] Invite validation before user creation (no orphan accounts)

P2.8 — Admin Page ✅

• [x] Platform tab: global user management table with search
• [x] Platform tab: block/unblock users
• [x] Platform tab: delete users with modal confirmation
• [x] Platform tab: reset password with modal dialog
• [x] Platform tab: platform admin accounts shown as read-only
• [x] Platform tab: platform admin self-service password change
• [x] Tenants tab: member list with role display
• [x] Tenants tab: role change via dropdown (viewer/member/admin)
• [x] Tenants tab: remove member with modal confirmation
• [x] Tenants tab: invite link generation with role selection
• [x] Tenants tab: pending invites list with revoke
• [x] Tenants tab: tenant selector for multi-tenant admins

P2.9 — Settings Page ✅

• [x] Tenant settings: confidence thresholds (high, low, minimum) with sliders
• [x] Tenant settings: offline timeout (minutes)
• [x] Tenant settings: verification consensus (votes needed)
• [x] Tenant settings: satellite retention (hours)
• [x] Platform settings: self-registration toggle
• [x] Platform settings: tenant creation toggle
• [x] Platform settings: invite links toggle
• [x] Settings API: /api/settings/tenant (GET/PUT)
• [x] Settings API: /api/settings/platform (GET/PUT)

P2.10 — UI Enhancements ✅

• [x] WebSocket connection status indicator (Live / Reconnecting...)
• [x] Toast notifications for action feedback (success and error)
• [x] Modal confirmations for all destructive actions
• [x] User menu in sidebar (name, email, platform admin badge, sign out)

P2.11 — On-Device Audio Pre-Filtering ✅

• [x] RMS silence rejection on satellite and mobile
• [x] Bird-band frequency check (reject audio outside bird frequency range)
• [x] Reduces unnecessary uploads and processing

P2.12 — Custom Watchlists for Species Alerts ✅

• [x] Per-tenant watchlist_species array in tenant settings
• [x] Alerts triggered when watchlisted species are detected

P2.13 — Web Container Auth Refactor ✅

• [x] nginx no longer injects HUB_INTERNAL_API_KEY on API requests
• [x] All user auth flows through JWT cookies (set by login, forwarded by browser)
• [x] Internal API key retained for backwards-compatible machine access only

Phase 3 — Community

Features that enable collaboration and data sharing.

P3.1 — Collaborative Verification ✅

• [x] Backend voting endpoint (confirm / reject / unsure)
• [x] Configurable consensus threshold (default: 3, adjustable in tenant settings)
• [x] Verification review queue in web UI (card-based with spectrogram + audio)
• [x] Keyboard shortcuts (1=Yes, 2=No, 3=Unsure, arrows=navigate)
• [x] Auto-advance to next unvoted detection
• [x] Progress bar and vote tracking
• [x] Verification statistics and user leaderboard

P3.2 — Scheduled Recording Profiles ✅

• [x] Profile definitions (dawn_chorus, night_migration, low_power, continuous)
• [x] Sunrise/sunset calculation from GPS coordinates (NOAA solar algorithm)
• [x] Recording scheduler pauses capture outside active windows
• [x] Hub → satellite profile push via MQTT
• [x] Per-satellite profile assignment in web UI
• [x] Schedule preview on satellite cards (resolved sun times + windows)
• [x] Schedule display in mobile app (read-only)
• [x] Night migration uses sunset-relative times (adapts to season)

P3.3 — Data Federation & Export (partial)

• [x] CSV/JSON export of detections (filterable, downloadable from UI)
• [x] eBird checklist generation
• [x] xeno-canto recording submission
• [x] iNaturalist observation export
• [ ] Scheduled automatic exports

P3.4 — Multi-Language Bird Names ✅

• [x] Species translation service (38 languages, loaded from BirdNET label files)
• [x] SpeciesName component with SpeciesI18nProvider context
• [x] User preferences for primary and secondary display languages

P3.5 — Multi-Hub Workers (partial)

• [x] Worker registration and heartbeat
• [~] Contributed worker onboarding (partial: worker dashboard shows connected workers)
• [x] Worker performance metrics (avg processing time, queue stats)
• [x] Worker dashboard in web UI
• [ ] GPU vs CPU worker differentiation

Phase 4 — Scale & Polish

P4.1 — Phone App ✅

• [x] Cross-platform mobile app (Capacitor)
• [x] Android phone satellite app with in-app registration, telemetry, GPS
• [x] Native AudioRecord plugin for Android
• [x] Background mode for continuous recording
• [x] In-app log viewer
• [x] Pause/resume recording
• [x] GPS gate: requires location before recording (auto or manual)
• [x] GPS auto-update toggle with configurable interval (30s–10min)
• [x] Keep screen on toggle
• [x] Settings panel: rename satellite, manage GPS, unregister with confirmation
• [x] Heartbeat keepalive (30s, QoS 1)
• [x] Schedule display (read-only, from hub)
• [x] Storage telemetry via Storage API
• [~] Push notifications for rare species (WebSocket toasts implemented, no native push yet)

P4.2 — Analytics Page ✅

• [x] Detection trends over time (daily trend chart)
• [x] Hourly species activity chart
• [x] Top species summary

P4.3 — User Preferences ✅

• [x] Per-user language settings (primary_language, secondary_languages on users table)
• [x] User preferences API (PUT /api/auth/me/preferences)
• [x] UserPreferences page in web UI

P4.4 — Species Images ✅

• [x] Bird thumbnails from Wikipedia (Wikimedia Commons API)
• [x] Background download queue (configurable delay between fetches)
• [x] Permanent storage in MinIO (no TTL expiry)
• [x] Proxy endpoint serves from MinIO (Wikipedia never hit at request time)
• [x] Placeholder display while downloading (pulsing indicator)
• [x] Lightbox with full-size image + Wikipedia link
• [x] Platform admin cache management (stats, retry failed, clear)

P4.5 — MQTT Heartbeat ✅

• [x] Lightweight keepalive every 30 seconds (QoS 1)
• [x] Decouples online status from audio chunk sending
• [x] Heartbeat state visible on satellite cards (Recording, Paused, Scheduled off)
• [x] Telemetry upgraded from QoS 0 to QoS 1 for reliability

P4.6 — Responsive Web UI ✅

• [x] Hamburger menu on mobile (< 768px)
• [x] Sidebar slides in as overlay with backdrop
• [x] Single-column card grids on mobile
• [x] Scrollable tables
• [x] Stacked filters

P4.7 — Versioning & Documentation ✅

• [x] Unified version across all packages (version-bump script)
• [x] VitePress documentation site with version switcher
• [x] CHANGELOG.md with structured release notes

P4.8 — Advanced Analytics (remaining)

• [ ] Migration pattern visualization across satellite network
• [ ] Biodiversity indices per location

P4.9 — Model Management

• [ ] Support multiple BirdNET model versions
• [ ] A/B testing of model versions
• [ ] Custom fine-tuned model deployment
• [ ] Model performance comparison dashboards