Damon Kohler

Tags

Tags

BirdNET-Go

18 min read

Recommendations

Summary

BirdNET-Go is a self-contained, real-time bird sound identification system written in Go that embeds the BirdNET AI model (6,500+ species) into a single binary alongside a Svelte 5 web frontend, TensorFlow Lite inference, and all static assets. Its defining capability is analyzing audio from IP camera RTSP streams, eliminating the need for dedicated outdoor microphones — any existing security camera with a microphone becomes a bird monitoring station. The project has no connection to BirdCAGE (a separate, unrelated Python wrapper around the same BirdNET model) despite both wrapping the BirdNET model; BirdNET-Go embeds TFLite directly via CGo rather than shelling out to the Python BirdNET-Analyzer.

  • Single binary, zero external dependencies — the entire application (Go backend, Svelte 5 frontend, TFLite models, species labels) compiles into one executable that runs on everything from a Raspberry Pi 3 to a Docker container
  • RTSP is the killer feature — repurpose existing IP cameras instead of installing dedicated microphones; user reports indicate foam windscreens and disabling camera noise suppression dramatically improve detection quality
  • Nightly builds are the real product — the latest stable release (v0.6.4, March 2025) is over a year behind the nightlies, which include HA auto-discovery, the new UI, multi-source audio capture, and 50+ bug fixes
  • No Redis, no external caching — all caching is in-process (sync.Pool for audio buffers, filesystem for spectrograms, in-memory with mutexes), consistent with the single-binary philosophy

Key Findings

  • BirdNET-Go has 1,022 GitHub stars, 88 forks, and active development with the latest nightly build released 2026-04-14 (GitHub)
  • The project uses the BirdNET v2.4 TFLite model exclusively; multi-model support (Perch v2, BirdNET v3.0, ONNX backend) is wired up but untested and not shipping as of the latest nightly (nightly-20260414 release notes)
  • HA MQTT auto-discovery was added in the January 2026 nightly, creating sensors for last species, confidence, scientific name, and sound level per audio source (nightly-20260111)
  • BirdCAGE (a Python-based BirdNET wrapper) has not been updated since August 2024 (last push: 2024-08-02) and has 29 open issues with 222 stars — BirdNET-Go is the clear successor project
  • Audio clip retention supports three policies: none, age (configurable in days/weeks/months/years), and usage (disk utilization threshold, default 80%) (BirdNET-Go Guide)
  • The notification system supports three provider types: Shoutrrr (20+ services via URL format), webhooks (custom HTTP with Go templates), and scripts (arbitrary shell commands with JSON/env input) (guide)
  • There is no official Home Assistant addon; a community addon by alexbelgium exists but users report daily crashes and RTSP compatibility issues (HA Community)
  • Redis is not used anywhere in BirdNET-Go — confirmed by code search (6 results, all incidental string matches) and architecture documentation (ARCHITECTURE.md)
  • The Svelte 5 UI fully replaced the legacy HTMX-based interface in the December 2025 nightly (nightly-20251223)
  • A custom classifier (birdnet-go-classifiers) adds non-bird sound classes including Dog, Engine, Human vocal, and Siren — the Siren class specifically reduces Eastern Screech-Owl false positives; Engine class targets vehicle noise but community reports indicate distant motorbikes and aircraft still trigger some species
  • Peer-reviewed research (Springer, Journal of Ornithology, 2025) confirms species-specific confidence thresholds are universally superior to a single global threshold — optimal thresholds varied across species but were generally lower than 0.35, meaning a universal 0.8 is both too aggressive for well-detected species and insufficient for problematic ones (Setting BirdNET confidence thresholds)
  • BirdNET-Go includes a built-in audio equalizer supporting HighPass, LowPass, BandPass, and BandReject filters — a high-pass at 300Hz removes the bulk of traffic rumble (concentrated 100-300Hz) while preserving most bird vocalizations (passerines: 2-8kHz, owls: 300Hz-1kHz)
  • The dynamic threshold system can amplify false positive problems: if road noise triggers a high-confidence false detection above the trigger value, the system lowers the threshold for that species, making subsequent false positives easier to trigger

Open Questions

  1. When will BirdNET v3.0 and Google Perch v2 models become usable features? The infrastructure is in place but models are untested and no timeline is published.
  2. Will a bat detection model from the BattyBirdNET-Pi project be bundled? The nightly release notes mention it as planned.
  3. How does detection accuracy compare between RTSP camera audio and dedicated USB microphones in a controlled setting? Community reports are anecdotal.
  4. Will the community HA addon stabilize, or is standalone Docker the long-term recommended approach?
  5. What is the Prometheus metrics schema? The telemetry endpoint exists but detailed metric names and labels are not documented in the wiki.
  6. How effective is the custom classifier’s Engine class at different distances? Community reports suggest close-range engines are caught but distant motorbikes and aircraft still trigger false detections.
  7. Can BirdNET-Go’s sound level data be used in HA automations to automatically suppress detections during high-noise periods?

Details

Architecture and Design Philosophy

BirdNET-Go’s architecture is defined by a single decision: embed everything into one binary. The Go backend, Svelte 5 frontend, TensorFlow Lite models, species labels for 40+ languages, and all static assets compile into a single executable via Go’s embed directive. This eliminates the dependency management problems that plague Python-based alternatives like BirdCAGE (which forks the BirdNET-Analyzer and shells out to it as a subprocess).

  • Language: Go 1.25+ with Echo v4 web framework
  • AI inference: TensorFlow Lite via go-tflite CGo bindings (BirdNET v2.4 model, FP32, ~50-200MB footprint)
  • Frontend: Svelte 5 + TypeScript + Tailwind CSS v4.1, compiled to static assets and embedded in the binary
  • Database: GORM ORM supporting SQLite (default, zero-config) and MySQL
  • Caching: In-process only — sync.Pool for audio buffers, filesystem FIFO queue for spectrograms, in-memory with RWMutex for label caches and thresholds
  • License: CC-BY-NC-SA 4.0

Non-commercial license

BirdNET-Go uses CC-BY-NC-SA 4.0, inherited from the BirdNET model. This restricts commercial use. Any derivative or integration must comply with this license.

Audio Pipeline and Detection Architecture

The detection pipeline processes audio in 3-second chunks at 48kHz mono PCM, running through multiple filtering stages before a detection is accepted.

  • Multi-source capture (new in nightly-20260414): simultaneous audio from multiple soundcards, each with independent gain and EQ settings; sources can be added/removed from the UI without restart
  • RTSP ingestion: FFmpeg extracts audio from IP camera streams; TCP transport recommended for stability
  • Camera audio optimization: disable noise suppression (removes bird sounds), increase sampling from default 8kHz to 48kHz, install foam windscreens ($9 for 6 packs)
  • Detection pipeline stages (in order):
    1. Range Filter — geographic/seasonal plausibility using FP16 range models
    2. Dynamic Threshold — per-species adaptive confidence learned from detection history (24-hour window, 30-day persistence)
    3. Deep Detection — requires multiple confirmations within a time window when overlap is set high (e.g., 2.7); significantly reduces false positives at the cost of CPU
    4. Privacy Filter — suppresses detections when human speech is detected above a confidence threshold
    5. Dog Bark Filter — prevents misidentification during dog barking (configurable species list and remember duration)
  • Action queue: asynchronous job processing (capacity 1,000) with exponential backoff retry; supports DatabaseAction, SSEAction, MqttAction, BirdWeatherAction, SaveAudioAction

Recording Retention and Storage Management

BirdNET-Go exports 3-second audio clips of detected bird calls and manages storage automatically through configurable retention policies.

  • Export formats: WAV (default), MP3, FLAC, AAC, Opus
  • Retention policies (configured in realtime.audio.export.retention):
PolicyBehaviorConfiguration
noneNo automatic cleanupClips accumulate indefinitely
ageDelete clips older than thresholdmaxage: 30d (accepts d/w/m/y)
usageDelete oldest clips when disk exceeds thresholdmaxusage: 85% (default)
  • Minimum clips per species (minclips: 5): prevents complete removal of rare species recordings during cleanup
  • Check interval: 15 minutes by default (checkInterval: 15)
  • Orphaned clip cleanup: the nightly-20260414 release fixes a bug where clip_name database references persisted after files were deleted from disk

Web UI and Frontend

The Svelte 5 frontend fully replaced the legacy HTMX-based interface in December 2025. It provides a data-rich dashboard with real-time updates via Server-Sent Events (SSE).

  • Dashboard views: main detection list with spectrograms, analytics dashboard with 30-day trends, species detail modals, search with inline review
  • System overview page: live sparklines for CPU, memory, disk, and temperature
  • Species tracking: badges for “New Species” (all-time), “New This Year,” and “New This Season” with configurable windows and hemisphere-aware season definitions
  • Live audio streaming: HLS-based with RAM disk (tmpfs) for segment storage
  • Spectrogram rendering: SoX (preferred) or FFmpeg fallback with multiple size variants (400-1200px) and lazy loading
  • Bundle sizes: Main 705KB, Vendor 40KB, Charts 202KB, MapLibre 917KB
  • Internationalization: 13 locales with complete translations
  • Authentication: Basic auth, Google OAuth2, GitHub OAuth2, subnet bypass, auto-TLS via Let’s Encrypt

Notification System

BirdNET-Go provides a comprehensive push notification system with three provider types, metadata-based filtering, and built-in resilience (retries, circuit breakers, rate limiting).

  • Shoutrrr provider: unified URL format for 20+ services
    • Discord, Telegram, Slack, Matrix, Mattermost, Zulip
    • Pushover, Pushbullet, Ntfy
    • SMTP, SendGrid, Mailgun
    • Home Assistant, Gotify
    • Opsgenie, PagerDuty, Bark (iOS)
  • Webhook provider: custom HTTP (POST/PUT/PATCH) with Go template payloads, bearer/basic/custom auth, multiple endpoints with failover
  • Script provider: executes arbitrary shell commands with JSON stdin and/or environment variables
  • Filtering dimensions: type (error/warning/info/detection/system), priority (critical/high/medium/low), component, metadata (confidence thresholds, species names)
  • Built-in connection testers: verify MQTT and BirdWeather connectivity from the web UI with multi-stage diagnostics
  • Notification URLs: configurable hostname (security.host or BIRDNET_HOST env var) ensures clickable links work from phones/remote devices

No Apprise integration

BirdNET-Go uses Shoutrrr (Go-native) rather than Apprise (Python). Since Shoutrrr already covers 20+ services including ntfy, Gotify, and Discord, Apprise is unnecessary. Apprise would also break the single-binary, no-Python design.

Home Assistant Integration

Home Assistant integration has evolved through three approaches, with MQTT auto-discovery being the newest and simplest.

  • MQTT auto-discovery (added nightly-20260111): publishes HA discovery configs automatically; creates sensors per audio source for last species, confidence, scientific name, and sound level; bridge device with connectivity status; configurable discovery prefix
  • Command-line sensors + template sensors (community approach from Kyle Niewiada’s blog): polls /api/v2/analytics/species/daily and /api/v2/analytics/species/summary endpoints; template sensors persist data through API downtime; MQTT trigger forces immediate command-line sensor refresh
  • Triggered template sensors (HA Community approach): subscribes to the birdnet MQTT topic and accumulates detections in sensor attributes; resets daily at midnight
  • Dashboard cards: markdown cards with sparkline charts, latest detections with relative timestamps, birds-of-interest filtering by species name; requires Mushroom and stack-in cards from HACS for richer layouts
  • HA addon status: no official addon; community addon by alexbelgium exists but has stability issues (daily crashes, RTSP compatibility problems); standalone Docker is the recommended approach
Integration MethodProsCons
MQTT auto-discoveryZero config, automatic sensorsRequires nightly build; limited to last detection per source
Command-line + template sensorsRich data (daily/overall summaries, hourly counts)Manual config; jq dependency; attribute size limits
Triggered template sensorsReal-time, no pollingResets daily; attribute size limits at high detection volumes

Release Strategy and Update Mechanisms

BirdNET-Go follows a dual-track release model where nightly builds carry the bulk of new features and the gap between stable and nightly is substantial.

  • Stable releases: last tagged release is v0.6.4 (March 15, 2025); release cadence slowed significantly after v0.6.x
  • Nightly builds: frequent, feature-rich releases (14 nightlies between October 2025 and April 2026); the latest (nightly-20260414) is described as a “large architectural release” with 76+ commits
  • Docker images: available on both ghcr.io/tphakala/birdnet-go (primary) and tphakala/birdnet-go (Docker Hub mirror); identical images
  • Update process: docker-compose pull && docker-compose up -d or re-run the install.sh script which detects existing installations and offers an update option
  • Install script: handles prerequisites, Docker image pull, configuration wizard (audio input, location, language), systemd service creation, and optional Sentry error tracking

Docker Deployment

Docker is the recommended deployment method, with a well-structured compose file that includes performance optimizations.

  • Registry options: ghcr.io/tphakala/birdnet-go (primary) or tphakala/birdnet-go (mirror)
  • Compose features: environment variables for TZ/UID/GID, volume mounts for config and data persistence, tmpfs RAM disk for HLS streaming segments (50MB), /dev/snd device mapping for soundcard access
  • HTTPS healthcheck: container healthcheck supports HTTPS endpoints with redirect validation (added nightly-20260414)
  • Cloudflare Tunnel: optional cloudflared sidecar for secure internet access without port forwarding
  • User permissions: configurable UID/GID (default 1000:1000) via environment variables
  • No self-build needed: official images include all dependencies (TFLite C library, FFmpeg, SoX); building from source is only necessary for development contributions

Health Monitoring and Telemetry

BirdNET-Go provides several monitoring capabilities, though they are distributed across different subsystems rather than a unified health dashboard.

  • Prometheus endpoint: configurable telemetry at localhost:9090 (or custom bind address); exposes birdnet_sound_level_db, processing duration histograms, and publishing counters
  • Stream health monitoring: tracks connectivity status of audio streams with health checks
  • System overview page: web UI shows live sparklines for CPU, memory, disk usage, and temperature
  • Sound level monitoring: 1/3 octave band analysis (ISO 266 standard, 25Hz-20kHz) with MQTT/SSE/Prometheus integration; adds ~5-10% CPU overhead on RPi 4
  • Support bundles: birdnet support command generates diagnostic dumps with sensitive data masked; can include GitHub issue numbers for Sentry correlation
  • Sentry integration: opt-in error tracking with production noise filtering (transient signals, auth errors, operational throttling suppressed)

BirdCAGE Comparison

BirdCAGE and BirdNET-Go serve the same purpose but differ fundamentally in architecture and project health.

AspectBirdNET-GoBirdCAGE
LanguageGoPython
Model integrationEmbedded TFLite via CGoForked BirdNET-Analyzer subprocess
Last commit2026-04-14 (active)2024-08-02 (stagnant)
GitHub stars1,022222
Open issues9929
BinarySingle self-containedPython app + dependencies
RTSP supportNative via FFmpegSupported
HA auto-discoveryYes (MQTT)No
Web UISvelte 5 (modern)Basic

False Positive Reduction

Confidence threshold alone is insufficient for eliminating false positives from road noise. BirdNET confidence scores are species-specific and not comparable across species — for some species 0.60 is correct 99% of the time, while for others 0.99 may still be wrong. A multi-layered strategy combining several built-in features is required.

Apply these in order of expected impact:

  1. Enable deep detection (overlap: 2.7) — requires 8 confirmations in a 12-15 second window; road noise is typically transient (single vehicle pass), so this filters most single-event noise
  2. Install the custom classifier — adds Engine and Siren detection classes
  3. Enable equalizer high-pass filter at 300-400Hz to attenuate traffic rumble
  4. Set per-species thresholds for known false-positive species after reviewing 1-2 weeks of detections
  5. Exclude species that never produce real detections at your location
  6. Tighten the range filter (rangefilter.threshold: 0.05) to reduce the candidate species pool
  7. Optimize microphone placement — use a garden-facing camera or dedicated microphone shielded by the building

Deep Detection (Overlap Setting)

The single most effective built-in tool for reducing false positives from transient noise. Requires multiple confirmations of the same species within a time window before accepting a detection.

birdnet:
  overlap: 2.7
OverlapRequired DetectionsUse Case
0.01Standard mode (no deep detection)
1.52Light filtering
2.44Moderate filtering
2.78Recommended for noisy environments
2.924Very strict (may miss real birds)

CPU cost: overlap 2.7 on a Raspberry Pi 5 is manageable; on a Pi 3B+ it may cause lag. Can be combined with lower base thresholds since the multi-detection requirement compensates.

Per-Species Confidence Thresholds

Overrides the global birdnet.threshold for individual species. Target species that produce high-confidence false positives at your location.

realtime:
  species:
    config:
      "Eurasian Eagle-Owl":
        threshold: 0.95
      "Tawny Owl":
        threshold: 0.95
      "Eurasian Collared-Dove":
        threshold: 0.95

Per-species thresholds take precedence over dynamic threshold adjustments.

Audio Equalizer Filters

Traffic noise concentrates in low frequencies (below 500Hz, peaking 100-300Hz). A high-pass filter removes the bulk of this while preserving most bird vocalizations.

realtime:
  audio:
    equalizer:
      enabled: true
      filters:
        - type: HighPass
          frequency: 300
          q: 0.7
          passes: 1

Low-frequency callers

A high-pass at 300Hz will attenuate owls (300Hz-1kHz), doves (300-600Hz), and bitterns. If monitoring these species is a priority, use a lower cutoff (150-200Hz) or rely on other filtering layers instead.

Alternative: configure an ALSA-level high-pass filter (Linux only, for soundcard sources) using LADSPA plugins before audio reaches BirdNET-Go, reducing processing load (Discussion #174).

Species Exclusion List

Configured via realtime.species.exclude in config.yaml or via Settings > Species > “Always Exclude Species” in the web UI. Has absolute veto power — species on this list are never detected regardless of confidence. Changes apply immediately without restart when made through the web UI.

Build this list empirically: run BirdNET-Go for 1-2 weeks, review all detections, identify species that are 100% false positives at your location.

Dynamic Threshold Pitfall

The dynamic threshold system progressively lowers thresholds for species showing repeated high-confidence detections. This can amplify false positive problems: if road noise triggers a high-confidence false detection above the trigger value, the system lowers the threshold for that species, making subsequent false positives easier.

Mitigation: set per-species thresholds (which override dynamic adjustments) for species prone to road noise confusion, or raise the trigger value to 0.95.

realtime:
  dynamicthreshold:
    enabled: true
    trigger: 0.95
    min: 0.20
    validhours: 24

Custom Classifier

The custom classifier from birdnet-go-classifiers augments the base BirdNET v2.4 model with improved non-bird sound detection:

  • Engine — targets vehicle and motor noise
  • Siren — specifically added to reduce Eastern Screech-Owl false matches
  • Dog — dog bark detection
  • Human vocal — speech detection

Community reports: catches many engine sounds but distant motorbikes and aircraft at night still trigger false bird detections. The maintainer actively collects problematic audio files to improve future classifier iterations — submitting false positive clips helps the project (Discussion #1278).

For persistent problems, you can train your own custom classifier using traffic noise samples from your location as a Background class (Training a Custom Classifier).

Species Commonly Confused with Road Noise

Owl species are the primary false positive offenders due to low-frequency vocalizations overlapping with traffic and mechanical sounds:

SpeciesConfused With
Eurasian Eagle-OwlDog barks, low-frequency traffic
Tawny OwlCrowd noise, police sirens, TV audio
Eastern Screech-OwlPolice/emergency sirens
Little OwlMechanical sounds (high FP rate even at 99% confidence)
Eurasian Scops-OwlMechanical beeping, midwife toad calls

Dove/pigeon species produce low-frequency calls in the 300-600Hz range that overlap with engine idle:

SpeciesConfused With
Eurasian Collared-DoveEngine idle/rumble (three-note “coo-COO-coo” pattern)
Stock DoveMechanical hum
Common Wood-PigeonTraffic rumble

Sound Level Correlation

Enable sound level monitoring to correlate high ambient noise with detections:

realtime:
  audio:
    soundlevel:
      enabled: true
      interval: 10

Exposes sound level data via MQTT, SSE, and Prometheus. In Home Assistant, create automations that flag or suppress bird detections when concurrent sound levels indicate high ambient noise.

Microphone Placement for Road Noise

  • Shield the microphone from the road direction — use the building as a barrier
  • If using RTSP, prefer a garden-facing camera over a street-facing one
  • Mount higher (2-3m+) to reduce ground-level traffic noise pickup
  • For dedicated microphones, recommended hardware: PUI Audio AOM-5024L-HD-R capsule (DIY) or Clippy EM272 (pre-made), both omnidirectional with high sensitivity and low self-noise
  • USB audio interfaces with built-in low-cut/high-pass filters eliminate low-frequency rumble before it reaches BirdNET-Go

Sources

Accepted

SourceTierWhy Credible
tphakala/birdnet-go GitHub Repository (retrieved: 2026-04-14)HighOfficial project repository with README, releases, and source code
BirdNET-Go Wiki Guide (retrieved: 2026-04-14)HighOfficial project documentation maintained by the developer
BirdNET-Go ARCHITECTURE.md (retrieved: 2026-04-14)HighOfficial architecture documentation in the repository
BirdNET-Go Docker Compose Guide (retrieved: 2026-04-14)HighOfficial deployment documentation
BirdNET-Go nightly-20260414 Release Notes (retrieved: 2026-04-14)HighOfficial release notes from the project maintainer
BirdNET-Go nightly-20260111 Release Notes (retrieved: 2026-04-14)HighOfficial release notes documenting HA auto-discovery feature
BirdNET-Go MQTT discovery.go source (retrieved: 2026-04-14)HighPrimary source code for HA MQTT auto-discovery implementation
Backyard Bird Tracking With AI-Powered BirdNET-Go - Kyle Niewiada (retrieved: 2026-04-14)MediumDetailed blog post with working HA sensor configs and dashboard cards; author is a BirdNET-Go contributor
Displaying Birdnet-go detections - HA Community (retrieved: 2026-04-14)MediumActive HA community discussion with real-world integration approaches
BirdNET Discussion - HA Community (retrieved: 2026-04-14)MediumCommunity discussion on addon status and MQTT configuration
Home Assistant Add-on Discussion #55 (retrieved: 2026-04-14)MediumGitHub discussion with project maintainer confirming no official addon
DeepWiki - tphakala/birdnet-go (retrieved: 2026-04-14)MediumAI-generated project analysis; cross-referenced against primary sources
birdnet-go-classifiers Repository (retrieved: 2026-04-15)HighOfficial custom classifier from project maintainer; adds Engine, Siren, Dog, Human vocal classes
Training a Custom Classifier Wiki (retrieved: 2026-04-15)HighOfficial documentation for training location-specific classifiers
Discussion #1278 - Improved Classifier (retrieved: 2026-04-15)HighMaintainer-led discussion on classifier improvements with community feedback on false positive reduction
Discussion #174 - ALSA High-Pass Filter (retrieved: 2026-04-15)HighMaintainer-authored solution for OS-level audio filtering
BirdNET-Go Hardware Wiki (retrieved: 2026-04-15)HighOfficial hardware recommendations including microphone selection
Setting BirdNET Confidence Thresholds - Springer 2025 (retrieved: 2026-04-15)HighPeer-reviewed research confirming species-specific thresholds are superior to universal thresholds
BirdNET-Pi Discussion #559 - Persistent Call Species (retrieved: 2026-04-15)MediumCommunity experience data with specific false positive species patterns
BirdNET-Pi Discussion #262 - Misidentifications (retrieved: 2026-04-15)MediumCommunity-reported species confusion patterns transferable to BirdNET-Go
Chris Dzombak - Microphone Setup for BirdNET-Pi (retrieved: 2026-04-15)MediumDetailed hardware recommendation from practitioner

Rejected

SourceWhy Rejected
Unraid BirdNET-Go Support ThreadPlatform-specific community support thread; not generalizable
Captain Bodgit BirdNET Systems TestingPersonal blog without stated expertise; anecdotal comparison
Various bird identification app roundup articlesSEO content aggregation; no original analysis of BirdNET-Go
Various BirdForum threads on false positivesForum discussions without verifiable expertise; anecdotal

Revision History

DateScopeKey Changes
2026-04-14Initial research12 accepted sources, 3 rejected; covers architecture, HA integration, notifications, Docker, retention, UI, health monitoring, Redis (confirmed absent), release strategy
2026-04-15False positive reduction11 new sources (8 accepted, 1 rejected); new section on reducing false positives from road noise covering deep detection, per-species thresholds, audio equalizer filters, custom classifiers, species confusion patterns, microphone placement, and sound level correlation
2026-07-18Garden projection scrubPublished in place as a garden page (publish: true, stage: seedling): rewrote 6 body wikilinks to unpublished notes as plain prose or external links per the Content Model scrub checklist; no content-substance changes.

Graph View

Backlinks

Stories about this page