BirdNET-NG Feature Roadmap

Phase 1 — Core Loop (MVP) ✅

The minimum viable distributed bird identification system.

P1.1 — Satellite Audio Capture ✅

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

P1.2 — Satellite → Hub Transport ✅

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

P1.3 — Hub Audio Ingestion ✅

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

P1.4 — Inference Worker ✅

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

P1.5 — Web UI ✅

✓ Dashboard: satellite status cards, recent detections, species count
✓ Detection cards: 2-column flex layout with SpectrogramPlayer
✓ SpectrogramPlayer: unified spectrogram + audio player component on detection cards
✓ SpectrogramPlayer: click-to-seek on spectrogram, drag to select region for loop playback
✓ SpectrogramPlayer: playback cursor line synced with spectrogram
✓ SpectrogramPlayer: signal boost (1x–20x via Web Audio GainNode), speed control (0.25x–2x)
✓ SpectrogramPlayer: volume slider with mute toggle, download button
✓ SpectrogramPlayer: times displayed with centisecond precision
✓ Vote buttons (Yes/No/Unsure) under confidence bar
✓ Satellite table layout with sortable columns (Name, Status, Profile, Version, Last seen)
✓ Search by name, filter by status, satellite count (online/total) in header
✓ Slide-in side panel on row click (General, Hardware, Schedule, Hub Configuration, Actions)
✓ Smooth slide animation on panel open/close
✓ Satellite version shown with amber warning when satellite version != hub version
✓ Tenant selector with "All Tenants" option
✓ Dark theme, responsive layout
✓ Spectrogram visualization (Cooley-Tukey FFT, Viridis colormap, 0–12kHz)

P1.6 — Multi-Tenancy Foundation ✅

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

P1.7 — Deployment ✅

✓ Docker Compose for full 8-container hub stack
✓ Traefik integration (HTTPS + MQTTS TLS termination)
✓ Four FQDNs (web, MQTT, MinIO console, documentation site)
✓ All configuration via .env environment variables
✓ Persistent storage via bind mounts
✓ Satellite install script for Raspberry Pi

Phase 2 — Intelligence

Smart features that improve detection quality and user experience.

P2.1 — Geo-Aware Inference ✅

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

P2.2 — Rare Species Alerts ✅

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

P2.3 — Confidence-Based Re-Processing ✅

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

P2.4 — Satellite Health & Telemetry ✅

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

P2.5 — User Authentication & Authorization ✅

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

P2.6 — Multi-Tenant Membership ✅

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

P2.7 — Invite System ✅

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

P2.8 — Admin Page ✅

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

P2.9 — Settings Page ✅

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

P2.10 — UI Enhancements ✅

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

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

✓ Adaptive noise floor + spectral peak SNR detection (replaced RMS + bird-band frequency ratio)
✓ All filter settings configurable from hub tenant settings (filter_enabled, filter_min_rms, filter_peak_snr, filter_bird_band_check, filter_noise_floor_alpha)
✓ Settings pushed to satellites via MQTT config channel when changed
✓ Satellites report noise_floor_rms in heartbeat telemetry
✓ Default thresholds: min RMS 0.003, peak SNR 1.5, noise floor alpha 0.02
✓ Reduces unnecessary uploads and processing

P2.12 — Custom Watchlists for Species Alerts ✅

✓ Per-tenant watchlist_species array in tenant settings
✓ Alerts triggered when watchlisted species are detected

P2.13 — Web Container Auth Refactor ✅

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

Phase 3 — Community

Features that enable collaboration and data sharing.

P3.1 — Collaborative Verification ✅

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

P3.2 — Scheduled Recording Profiles ✅

✓ Profile definitions (dawn_chorus, night_migration, low_power, continuous)
✓ Sunrise/sunset calculation from GPS coordinates (NOAA solar algorithm)
✓ Recording scheduler pauses capture outside active windows
✓ Hub → satellite profile + filter settings push via MQTT
✓ Hub pushes config to all online satellites when tenant settings change
✓ Satellites apply config on reconnect
✓ Heartbeat interval configurable from tenant settings (default 30s)
✓ Per-satellite profile assignment in web UI
✓ Schedule preview on satellite cards (resolved sun times + windows)
✓ Schedule display in mobile app (read-only)
✓ Night migration uses sunset-relative times (adapts to season)

P3.3 — Data Federation & Export (partial)

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

P3.4 — Multi-Language Bird Names ✅

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

P3.5 — Multi-Hub Workers (partial)

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

Phase 4 — Scale & Polish

P4.1 — Phone App ✅

✓ Cross-platform mobile app (Capacitor)
✓ Android phone satellite app with in-app registration, telemetry, GPS
✓ Native AudioRecord plugin for Android
✓ Background mode for continuous recording
✓ In-app log viewer
✓ Tap-to-record status bar (recording rectangle is the toggle)
✓ Default state: paused (not recording)
✓ GPS gate: requires location before recording (auto or manual)
✓ Clear GPS/manual location toggle
✓ GPS auto-update toggle with configurable interval (30s–10min)
✓ Keep screen on toggle
✓ Settings redesigned as full page (not popup) with verbose chunk logging toggle
✓ All hub filter settings received and applied via MQTT
✓ Heartbeat keepalive (configurable interval, default 30s, QoS 1)
✓ Schedule display (read-only, from hub)
✓ Storage telemetry via Storage API
[~] Push notifications for rare species (WebSocket toasts implemented, no native push yet)

P4.2 — Analytics Page ✅

✓ Detection trends over time (daily trend chart)
✓ Hourly species activity chart
✓ Top species summary

P4.3 — User Preferences ✅

✓ Per-user language settings (primary_language, secondary_languages on users table)
✓ Date format preferences: primary display + secondary tooltip
✓ Date format options: relative, short, medium, long, ISO 8601
✓ User preferences API (PUT /api/auth/me/preferences)
✓ UserPreferences page in web UI

P4.4 — Species Images ✅

✓ Bird thumbnails from Wikipedia (Wikimedia Commons API)
✓ Background download queue (max 2 concurrent, configurable delay)
✓ Wikimedia rate limiting: sliding 1-hour window, auto-throttle at 80%, pause at 95%
✓ Unauthenticated: 500 req/hr; with OAuth 2.0 token: 10,000 req/hr
✓ Wikimedia OAuth token and contact email configurable in Platform Settings
✓ Respects Retry-After header on 429 responses
✓ Permanent storage in MinIO (no TTL expiry)
✓ Proxy endpoint serves from MinIO (Wikipedia never hit at request time)
✓ Placeholder display while downloading (pulsing indicator)
✓ Lightbox with full-size image + Wikipedia link
✓ Platform admin cache management (stats, retry failed, clear)

P4.5 — MQTT Heartbeat ✅

✓ Lightweight keepalive every 30 seconds (QoS 1)
✓ Decouples online status from audio chunk sending
✓ Heartbeat state visible on satellite cards (Recording, Paused, Scheduled off)
✓ Telemetry upgraded from QoS 0 to QoS 1 for reliability
✓ Satellite version reported in heartbeat, stored on satellites table
✓ Web UI shows amber warning when satellite version differs from hub version

P4.6 — Responsive Web UI ✅

✓ Hamburger menu on mobile (< 768px)
✓ Sidebar slides in as overlay with backdrop
✓ Responsive sidebar (scrollable, hidden scrollbar)
✓ Single-column card grids on mobile
✓ Scrollable tables
✓ Stacked filters

P4.7 — Versioning & Documentation ✅

✓ Unified semver across all packages (version-bump script syncs all package.json + pyproject.toml)
✓ Version displayed in web UI sidebar and mobile app header
✓ Documentation site (Express + markdown-it) with version switcher
✓ CHANGELOG.md with structured release notes
✓ Release protocol documented
✓ Design system documented (buttons, badges, color palette)

P4.8 — Species Catalog & Detection Map ✅

✓ Species catalog page with sortable cards and rich stats
✓ Per-species: detection count, confidence, first/last seen, satellite count
✓ Sort: most detected, most recent, alphabetical, confidence, rarest, most satellites
✓ Detection map with Leaflet.js + OpenStreetMap
✓ Satellite markers colored by status, sized by detection count
✓ Popup with detection stats and top 5 species

P4.9 — Account & User Management ✅

✓ Account page: edit name, email, change password, language preferences
✓ Account self-deletion with confirmation (blocks sole tenant owners)
✓ Login rate limiting (20 attempts/IP/15min)
✓ Account lockout after 5 failed attempts (15min)
✓ Last login tracking (timestamp + IP)
✓ Audit log: all admin and user actions recorded
✓ Audit Log page for platform admins (paginated, color-coded)
✓ Tenant ownership transfer
✓ User search filters (status, tenant)
✓ Platform admin auto-persisted from PLATFORM_ADMIN_EMAILS env var
✓ Auth resolves live user data from DB (not stale JWT)

P4.10 — Design System ✅

✓ Unified CSS classes for all buttons (btn-primary, btn-secondary, btn-danger, btn-ghost)
✓ Button sizes: btn-sm (tables), default (modals), btn-lg (forms)
✓ Hover, disabled, active states in CSS (no inline JS)
✓ Unified badge classes (online, offline, degraded, muted, accent, rare, danger)
✓ Responsive layout with mobile hamburger menu
✓ Version display in sidebar

P4.12 — Advanced Analytics (remaining)

Migration pattern visualization across satellite network
Biodiversity indices per location

P4.13 — Per-Satellite Configuration Overrides

Per-satellite filter settings override (RMS, SNR, bird-band check, noise floor alpha)
Configurable from hub satellite detail panel or directly on the satellite device
Tenant defaults apply unless satellite has explicit overrides
Visual indicator on satellite card when using custom overrides

P4.14 — Model Management

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