BirdNet-Behavior

Real-time acoustic bird classification with behavioral analytics — written in Rust, runs on a Raspberry Pi.

BirdNet-Behavior listens to your microphone or RTSP camera, identifies birds in real time with a BirdNET neural network (BirdNET V2.4 by default), and serves a fast, beautiful web dashboard you open in any browser. It ships as one self-contained binary — the ONNX Runtime and DuckDB analytics engine are compiled in, so there’s no Python, no pip, no virtualenv. Drop it on a modern 64-bit Pi and run it.

Where to start

Why a rewrite?

BirdNet-Behavior is a rewrite of BirdNET-Pi in Rust, derived from it and licensed accordingly. It keeps everything BirdNET-Pi does and adds behavioral analytics, a redesigned UI, MQTT/Home Assistant integration, and a much lighter runtime.

It is a rewrite of BirdNET-Pi in Rust, derived from it and licensed accordingly (the repository’s LICENSE says “derived from”). See Credits & License for full attribution.

A modern, two-audience interface

The UI is organized into six homes — the tabs across the top, and the phone bottom bar:

Every screen is designed to serve two people at once: the hobbyist who wants a delightful at-a-glance view, and the researcher who needs methodological rigor. Each page leads with a plain-English headline, then layers the dense numbers and charts beneath. The whole UI supports light and dark themes (with automatic OS-preference detection) and reflows cleanly from a wall-mounted kiosk down to a phone.

Read on for installation, or jump into the field guide for a tour of every screen.

Installation

There are two supported ways to install BirdNet-Behavior, and each is one command. The bare-metal installer puts a native binary and a hardened systemd service on a Raspberry Pi or a modern x86_64 Linux machine. Docker carries its own runtime, so it also works where the native binary cannot run (Raspberry Pi OS Bookworm), and it suits a machine that already runs containers. Neither is the lesser path; choose by what the host is.

Supported hardware & OS

Runtime requirement: glibc ≥ 2.39. The prebuilt binaries are built on Ubuntu 24.04 to match the baseline that pyke’s ONNX Runtime requires, so they do not run on Raspberry Pi OS Bookworm / Debian 12 (glibc 2.36). install.sh checks this and refuses with a clear message rather than installing a binary that won’t start. Bookworm users: use Docker. Each prebuilt binary also ships the DuckDB behavioral-analytics engine built in and on by default — the installer’s systemd unit enables it automatically (for a manual run, pass --analytics-db).

• Storage: about 1.5 GB free to start, most of it for recordings and the database. The default classifier is about 85 MB (BirdNET V2.4: a 54 MB model and a 30 MB range filter); the BirdNET+ V3.0 preview you can choose instead is 541 MB, plus a 14 MB occurrence model. The installer warns below 600 MB free for V2.4 and 900 MB for V3.0, because the model installer will not run without its own size plus a 512 MiB margin free.
• Audio input — one of:
  • a USB microphone or USB sound card (arecord from alsa-utils), or
  • an IP camera or any RTSP stream (ffmpeg).

Which classifier a new install runs

A new bare-metal install, a new Docker volume and the macOS formula run BirdNET V2.4 with its v2 range (occurrence) filter — the network BirdNET-Pi and birdnet-go run, so the station agrees with them about what it heard (Same audio, same detections says what was measured). BirdNET+ V3.0 preview, the network earlier releases installed for everyone, is an explicit choice:

# bare metal: a flag, or the environment variable; Docker: BIRDNET_CLASSIFIER in .env
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/tomtom215/BirdNet-Behavior/releases/latest/download/install.sh | sudo bash -s -- --classifier birdnet-v3

The values are birdnet-v24 and birdnet-v3 (--classifier, or BIRDNET_CLASSIFIER for the installer, the container and quickstart.sh, which writes it to .env only if you set it). An existing station never changes model on an install, update, repair or reinstall: the installer reads the classifier that /etc/birdnet/birdnet.conf names and keeps it, and says so (a --classifier that disagrees is reported as not applied). A Docker volume that already holds the V3.0 model file keeps V3.0 and logs one line saying how to change that. Changing a running station’s classifier splits its history between two networks that name and score birds differently, so it is something you do on purpose, by editing MODEL_PATH, LABELS_PATH and METADATA_MODEL_PATH; the classifiers page has the details.

Where the files come from. The installer and the container ask the binary to install V2.4 (birdnet-behavior --install-model birdnet-v24 and birdnet-v24-range-v2), and the binary checks each file against a SHA-256 compiled into it. The model comes from birdnet-go’s published ONNX build on Hugging Face (huggingface.co/tphakala/BirdNET-v2.4) and the range filter from raw.githubusercontent.com (tphakala/birdnet-go), each at a pinned revision. The label file is not downloaded: the binary carries it, with BirdNET-Pi’s English names. So a default install needs huggingface.co and raw.githubusercontent.com as well as github.com (for the binary), and nothing in it comes from this project’s own model release. (The V2.4 files are also mirrored in this repository’s models-v2.4 release, published on 2026-10-20 with publish-model.yml; nothing fetches from it yet, because the binary’s catalogue names one origin per file.) V3.0 still comes from this project’s models-v3.0-preview3 release, with Zenodo as the fallback. Either way you never locate a model yourself; the files are installed into the data directory’s models/ folder on bare metal and /data/model in Docker.

Option 1 — Docker quick start

One command. It asks two or three plain-English questions, auto-detects your USB mic, writes a minimal .env, and starts the container. No git clone, no editor, no hand-picking compose overlays.

bash <(curl -fsSL https://raw.githubusercontent.com/tomtom215/BirdNet-Behavior/main/quickstart.sh)

See Running with Docker for the manual path, docker run, and audio-source overlays.

Option 2 — Bare-metal installer (no Docker)

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/tomtom215/BirdNet-Behavior/releases/latest/download/install.sh | sudo bash

That address always serves the newest published release’s install.sh, the same file that release lists in SHA256SUMS and attests with build provenance — not whatever the development branch holds that minute. (Fetching it from the branch, as earlier versions of this page said, ran unreleased code as root.) --proto '=https' --tlsv1.2 refuses a downgrade on the way.

The installer runs pre-flight checks (required tools, free disk, glibc version), detects your architecture, downloads the pre-built binary, installs the classifier (BirdNET V2.4 and its range filter unless you chose otherwise, above), creates the config/recording/model directories, installs and enables a systemd service, auto-detects your ALSA microphone, and starts the service immediately. When it finishes it runs post-install validation — the binary runs, systemd-analyze verify passes, directory ownership and config are correct, the doctor preflight is clean, and the port is listening.

The dashboard binds to all interfaces (0.0.0.0:8502) so it is reachable across your LAN right away. Viewing is open; everything that changes something — the /admin panel, and deleting, relabelling, reviewing or locking a detection — is gated by a strong admin password the installer auto-generates (username admin) — it is printed once in the post-install summary and stored as CADDY_PWD in /etc/birdnet/birdnet.conf. Save it. If you answer “restrict to this device” in the interactive prompts (or set BIRDNET_LISTEN=127.0.0.1:8502), the dashboard is reachable only from the Pi itself. If your config has an RTSP_URL, the installer also installs ffmpeg (required for RTSP capture) via apt, or prints the exact command if it can’t.

# Install a specific release (defaults to the latest). The `-s --` passes the
# argument through to the installer. Replace 0.17.1 with a release that exists:
# https://github.com/tomtom215/BirdNet-Behavior/releases
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/tomtom215/BirdNet-Behavior/releases/latest/download/install.sh | sudo bash -s -- --version 0.17.1

Don’t run the installer with sudo bash <(curl ...). Process substitution hands bash a file descriptor owned by your user; sudo closes it crossing to root, so the script disappears with /dev/fd/63: No such file or directory. The pipe forms above (curl ... | sudo bash) avoid that entirely. If you’d rather inspect the script first, download it and run it directly:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/tomtom215/BirdNet-Behavior/releases/latest/download/install.sh -o install.sh
sudo bash install.sh --version 0.17.1

Update, repair, reinstall, uninstall

When install.sh detects an existing install it offers a menu — update, repair, reinstall, or uninstall — or you can pass the command explicitly:

sudo bash install.sh update      # swap in the latest binary, restart (the default)
sudo bash install.sh repair      # fix a broken install without re-downloading
sudo bash install.sh reinstall   # re-download and reinstall from scratch
sudo bash install.sh uninstall   # remove the software (see Uninstalling below)

Update stops the service, swaps in the new binary, and restarts it; your configuration and the SQLite/DuckDB databases are preserved, and schema migrations run automatically on the next start. Repair re-creates missing directories, fixes ownership/permissions, rewrites the systemd unit, and restarts — without re-downloading anything. It is the go-to fix for a service that won’t start (a stale unit, wrong permissions, a missing directory).

A non-interactive run (no TTY, or --noninteractive) auto-updates an existing install rather than prompting.

Uninstalling

The quickest route is the installer’s own subcommand, which removes the software and keeps your data by default (set BIRDNET_PURGE=1, or answer the interactive prompt, to also delete the data and config):

sudo bash install.sh uninstall      # remove the software, keep all data
sudo BIRDNET_PURGE=1 bash install.sh uninstall   # also remove data + config

For full control, uninstall.sh ships next to the binary in every release tarball (and as a standalone release asset). It is safe by default — it removes only the software (the systemd service, the tmpfs mount unit, and the binary) and keeps your database, recordings, settings, and the downloaded model unless you opt in. It is idempotent (re-running is harmless) and refuses to touch system directories.

sudo ./uninstall.sh                 # remove the software, keep all data
sudo ./uninstall.sh --dry-run       # preview the exact plan, change nothing
sudo ./uninstall.sh --purge         # remove EVERYTHING (db, recordings, model, config, zram unit)

# Or pick precisely what to delete:
sudo ./uninstall.sh --remove-db --remove-recordings

It auto-detects your real data directory from the installed config and service files, so it removes exactly what was installed. If the config and service are already gone, it can’t detect the data directory and refuses to delete from a guessed path — re-run with --data-dir <path> (it tells you which path it guessed). Both uninstallers run systemctl reset-failed so no ghost failed unit lingers. On macOS it instead unloads the launchd LaunchAgent; pass --purge to also remove the user data directory.

Docker deployments are torn down with Compose instead — from the directory holding your docker-compose.yml:

docker compose down            # stop + remove the container, keep named volumes
docker compose down -v         # also remove volumes (deletes the database!)

Building from source

Prerequisites: Rust 1.95+ and git.

git clone https://github.com/tomtom215/BirdNet-Behavior.git
cd BirdNet-Behavior

cargo build --release                              # optimized build; DuckDB analytics is a default feature (~7 min first build)
cargo build --release --no-default-features        # without analytics (~3–5 min)
cargo build --release --features profiling         # with CPU profiles for administrators (see System)
cross build --release --target aarch64-unknown-linux-gnu   # cross-compile for a Pi

Once installed, head to First Steps to open the dashboard.

Running with Docker

The quick-start script is the easiest path. If you prefer to do it by hand, you only need to decide two things:

1. Station location — latitude and longitude.
2. Audio source — one of: USB/ALSA mic, PulseAudio/PipeWire, or an RTSP stream URL.

Everything else has sensible defaults — including DuckDB behavioral analytics, which is built into the image and enabled by default.

1. Clone and create your .env

git clone https://github.com/tomtom215/BirdNet-Behavior.git
cd BirdNet-Behavior
cp .env.example .env

2. Edit the REQUIRED section

Pick one audio variable and leave the others blank.

# Station location
BIRDNET_LATITUDE=42.3601
BIRDNET_LONGITUDE=-71.0589

# Timezone — detections are filed under the container's local hours, which
# come from this. Unset, the container runs on UTC and says so at start.
TZ=America/New_York

# Audio source — set exactly ONE
BIRDNET_ALSA_DEVICE=plughw:CARD=PRO,DEV=0   # USB/ALSA mic — see the note below
# BIRDNET_RTSP_URL=rtsp://cam.lan:554/stream
# BIRDNET_PIPEWIRE_DEVICE=default

# Image tag — pin a release such as 0.17.1 (the releases are listed at
# https://github.com/tomtom215/BirdNet-Behavior/releases), or leave it as latest
# (analytics is built in)
BIRDNET_IMAGE_TAG=latest

# Classifier — leave unset. A new volume then runs BirdNET V2.4 (with its range
# filter); a volume that already holds the BirdNET+ V3.0 model keeps V3.0.
# BIRDNET_CLASSIFIER=birdnet-v24     # or birdnet-v3 for the V3.0 preview

Name the card, do not number it. Run arecord -l on the host and read the word after card N: — that is the card’s id, and plughw:CARD=<id>,DEV=0 addresses it by that id. A card index (the 1 in plughw:1,0) is assigned in detection order, so a reboot, a re-plug, or a second sound device can renumber it, and nothing in this station re-resolves a device string once capture has started: the supervisor retries the old name forever and the microphone stays down until someone intervenes. See Audio & Microphones for the full explanation and for how to pin a name with a udev rule.

3. Start the stack

docker compose up -d pulls the image and starts everything — analytics is built in, so there is no variant to choose.

# A) RTSP camera / multi-stream / file-watch mode — no microphone hardware
docker compose up -d

# B) USB / ALSA microphone (most Raspberry Pi setups)
docker compose -f docker-compose.yml -f docker-compose.alsa.yml up -d

# C) PulseAudio / PipeWire (desktop Linux)
docker compose -f docker-compose.yml -f docker-compose.pulse.yml up -d

Your recordings, database, and cached model live in the birdnet-data named volume, so they survive restarts and image upgrades.

4. Watch the first-run model install

On a new volume the container installs the classifier before it starts the web server, and says which one in a single Classifier: log line. By default that is BirdNET V2.4 and its range filter v2, about 85 MB: the container asks the binary (birdnet-behavior --install-model birdnet-v24, then birdnet-v24-range-v2), which downloads each file, checks it against a SHA-256 compiled into the binary, and renames it into place only when it matches. The model comes from Hugging Face and the range filter from raw.githubusercontent.com (see Installation); the label file is written by the binary itself. A file that is already on the volume is not fetched again, so a restart installs nothing, and the install happens once per named volume.

docker compose logs -f birdnet

Which classifier a start runs, first match:

So an upgrade never switches a running station’s model: every volume created by a release that defaulted to V3.0 holds the V3.0 file. Setting BIRDNET_CLASSIFIER=birdnet-v24 on such a volume does move it to V2.4, and its history then contains rows from two networks (see the classifiers page).

With BIRDNET_CLASSIFIER=birdnet-v3 the container instead downloads the BirdNET+ V3.0 model (~541 MB) and its occurrence model from this project’s models-v3.0-preview3 release, with Zenodo as the fallback. That download resumes if it is interrupted (curl --continue-at -); the V2.4 install does not resume, it starts the file again on the next start. The health check has a 15-minute start period to accommodate a slow first run either way.

Once you see Starting birdnet-behavior, open http://localhost:8502.

If the download fails, the entrypoint fails loud (not silent) with the exact cause and remediation. See Troubleshooting → Model not found.

Single docker run (no compose)

For the absolute minimum — no clone, no compose files — edit the four marked values and paste:

docker run -d \
  --name birdnet-behavior \
  --restart unless-stopped \
  -p 8502:8502 \
  -v birdnet-data:/data \
  --device /dev/snd \
  --group-add audio \
  -e BIRDNET_LATITUDE=42.3601 \
  -e BIRDNET_LONGITUDE=-71.0589 \
  -e BIRDNET_ALSA_DEVICE=plughw:CARD=PRO,DEV=0 \
  -e BIRDNET_LISTEN=0.0.0.0:8502 \
  ghcr.io/tomtom215/birdnet-behavior:latest
docker logs -f birdnet-behavior         # watch the model install

For RTSP, drop --device /dev/snd --group-add audio and set BIRDNET_RTSP_URL= instead of BIRDNET_ALSA_DEVICE.

Pre-built images

Published for linux/amd64 and linux/arm64, and signed with cosign (keyless). There is no separate -analytics image — every image has analytics built in.

Data layout & compose reference

All persistent data lives in one Docker volume at /data. Name it (-v birdnet-data:/data, as the compose file does): the image declares /data a volume, so a docker run with no -v still gets one there, but an anonymous volume with a random name that nothing reattaches to the next container, and that docker rm -v or docker run --rm deletes.

The data is lost with the container only when the data directory is not on a mount at all: DB_PATH in a mounted birdnet.conf pointing outside /data, or an image built without the VOLUME line. The station says so in three places: the Station Health banner, the badge in the page header, and Data volume in --doctor (a warning, not an error, because the station works) with the fix. The check reads the container’s mount table, not the volume’s name, so a volume of any kind (an anonymous one too) or a bind mount counts as somewhere the data outlives the container.

The layout inside it:

/data/
  model/        the classifier's ONNX model + labels (and the occurrence filter), installed on first start
  recordings/   Audio segments from the capture pipeline
  cache/        Wikipedia species image cache
  analytics.db  DuckDB behavioral analytics (compose sets BIRDNET_ANALYTICS_DB)
  BirdNet-Behavior/
    birds.db    SQLite detections database (see note below)

The image sets no DB_PATH, so the database file is named by the binary’s default, $HOME/BirdNet-Behavior/birds.db — and the container user’s home directory is /data. Set DB_PATH in a mounted birdnet.conf to put it somewhere else.

Hardware & Audio Sources

You don’t need much — a Raspberry Pi (or any Linux box) and something to listen with. This page helps you choose.

Which computer?

BirdNet-Behavior is undemanding — there’s no Python interpreter or virtualenv resident around the model — so the limiting factor is usually storage for recordings, not compute. Budget about 1.5 GB free to start, most of it for recordings and the database (the default BirdNET V2.4 files are about 85 MB; the V3.0 preview’s are 541 MB).

Which microphone?

Any of these work — the goal is a clean signal, not an expensive one.

• USB conference/lavalier mics and USB sound cards with an electret capsule are the easy default. They show up as an ALSA card (arecord -l) and need no drivers.
• Dedicated USB measurement mics (e.g. an omnidirectional electret) give the best results outdoors.
• An old USB webcam’s mic will even work for a first test.

What matters more than the mic:

• Placement — outside, off a hard wall (which echoes), with a simple foam windscreen. Wind is the number-one source of false positives.
• Levels — aim for peaks near −6 dB on the Audio settings level meter. Too hot clips the loudest calls; too quiet buries the faint ones.

RTSP cameras (no microphone hardware)

Many bird-box and feeder cameras expose an RTSP stream that carries audio. Point BirdNet-Behavior at the URL and it treats the camera as a microphone — no sound card required. You can run several streams at once.

BIRDNET_RTSP_URL=rtsp://cam.lan:554/stream
# or multiple, comma-separated:
BIRDNET_RTSP_URLS=rtsp://cam1.lan/stream,rtsp://cam2.lan/stream

RTSP capture needs ffmpeg on the host. When your config already has an RTSP_URL, the bare-metal installer (install/repair) installs it for you via apt, or prints the exact command if it can’t; the Docker image bundles it. Add the camera under Cameras and streams on the Capture tab — which also takes HTTP/Icecast, HLS, RTMP, UDP and SRT streams — and prefer TCP transport on busy Wi-Fi. --doctor checks that the address resolves and its port answers.

“Watch a folder” mode

If you already have a pile of recordings, BirdNet-Behavior can classify a folder of audio files instead of listening live — handy for batch-processing field recordings.

Next: Configuration to wire your choice in, then First Steps.

Configuration

A setting can come from four places. When more than one names the same setting, this is the order (highest wins):

CLI flag or its BIRDNET_* variable  >  the Settings page  >  /etc/birdnet/birdnet.conf  >  built-in default

That is one rule, and the rest of the manual means it: the Settings page says the same, and the code that does it is src/cli.rs and src/helpers/settings_overlay.rs.

• A CLI flag and its BIRDNET_* variable are the same setting (the binary reads the variable when the flag is absent), so set one or the other. Either counts as explicit and beats the Settings page for good: a Docker station started with -e BIRDNET_SEGMENT_DURATION=30 keeps 30 whatever that field of the page says.
• The Settings page is the SQLite settings table, edited at /admin/settings; it is also the canonical place for everything that has no flag or variable — the detection confidence threshold, per-species thresholds, sensitivity, email SMTP, quarantine rules, and so on. You do not need to touch any of these to get started. Each key in birdnet.conf (and each value passed as a flag or variable at install time) is copied into the table the first time the station sees it — insert-only, so nothing you saved on the page is ever overwritten. Once a key has a row there, editing that key in the file changes nothing: the page’s value is the one used. (That is why changing LATITUDE in the file does not move a station that has already started once: change it on the page.) Most values saved on the page take effect at the next restart.
• birdnet.conf (kept for BirdNET-Pi compatibility) supplies the settings the page has no field for, and the first value of those it has.
• A setting with no field on the page skips that level: the flag or variable, else the file, else the default.

Environment variables & CLI flags

The full list lives in birdnet-behavior --help, and .env.example documents every variable the binary reads; a test keeps the two and the code from drifting apart. Each row shows the environment variable, the matching CLI flag, and the birdnet.conf INI key (for BirdNET-Pi compatibility).

A key the station does not read is reported rather than ignored: a birdnet.conf line such as CONFIDENC=0.90, or an environment variable such as BIRDNET_LATITUD, is named at startup in the journal and by --doctor, with the nearest real name when one is close (“did you mean CONFIDENCE?”). Before this, a misspelt key was parsed, stored and silently left at its default.

Invalid settings are not run. On startup the station validates the configuration. If a value is out of range (e.g. a latitude outside ±90, or a malformed RECORDING_SCHEDULE), it runs on the last configuration that passed, or — when there is none — starts web-only, recording nothing, so the dashboard can still tell you what is wrong. Both are reported in the journal and by birdnet-behavior --doctor; run the doctor on a config before deploying it, or apply it with --apply-config, which refuses a file that does not validate.

BIRDNET_LISTEN binds all interfaces by default (0.0.0.0:8502), so the dashboard is reachable across your LAN out of the box. Viewing is open; anything that changes something requires a password — the /admin panel, and also deleting, relabelling, reviewing or locking a detection, or saving the onboarding wizard. A fresh bare-metal install auto-generates CADDY_PWD (username admin) and prints it once in the post-install summary — change it via CADDY_PWD in birdnet.conf. To restrict the dashboard to the local machine, set BIRDNET_LISTEN=127.0.0.1:8502. The authentication (CADDY_PWD) and cross-origin (BIRDNET_CORS_ALLOWED_ORIGINS) settings are covered in Remote Access & Security.

What the station connects to

Two connections are made on the station’s own initiative, with no configuration:

One more can happen once, on a first run: if the bundled duckdb-behavioral extension cannot be loaded from the local cache or the copy embedded in the binary, DuckDB tries the community registry (extensions.duckdb.org). Release binaries carry the extension, so this normally never fires.

Everything else is off until you configure it, and configuring it is the consent: Apprise, BirdWeather, MQTT, SMTP e-mail, the heartbeat ping, and the weather poll (api.open-meteo.com by default; api.met.no, api.weather.com or api.pirateweather.net for the other WEATHER_PROVIDERs — itself opt-in via BNB_WEATHER_ENABLED=1). The location button calls ipwho.is (and get.geojs.io if that does not answer), over TLS and only when you press it. The request tells that service this station’s public IP address, which is how it finds the area; no station data is sent. You review the coordinates before saving them.

Offline mode

BIRDNET_OFFLINE=1        # or: --offline

Turns off both default-on connections at once — the update check and the image downloads — so the station makes no outbound connection you did not ask for. Integrations you configured explicitly keep working: offline mode is about unsolicited traffic, not about muting your alerts.

Use it on metered or cellular links, on air-gapped deployments, and wherever “what does this contact?” needs a single answer. Already-cached species images are still served; only new downloads stop.

birdnet-behavior --doctor reports the current posture under Outbound connections, so you can confirm it rather than infer it.

Web-UI-only settings

These are stored in the SQLite settings table and have no environment variable or command-line flag; a few also have a birdnet.conf key, noted beside them. That key is copied into the settings table the first time the station sees it; after that the value saved on the page is the one the station uses. Set them at /admin/settings — see Settings & Detection.

Retention is off by default. Nothing is deleted by age unless you ask for it: set Keep Clip Audio (days) in the UI (CLIP_RETENTION_DAYS) to reclaim the audio of older detections. Independently of that, the disk manager purges the oldest recordings once the disk hits DISK_PURGE_THRESHOLD (default 95%) and keeps at most BIRDNET_MAX_FILES_PER_SPECIES per species. Pin clips you want to keep with the lock action on any detection — locked clips are never purged by either limit.

All three limits, plus the temporary streaming folder’s retention and size ceiling, can be set from Settings → General → System & Display in the web UI; you never have to edit a config file to change them. A value given on the command line or as a BIRDNET_* variable wins over the UI, which in turn wins over the config file (the order at the top of this page).

When a clip is purged the detection itself is kept — its filename and the date the audio was reclaimed stay on the record, so counts, species lists, trends and exports are unaffected. Only the audio goes.

First Steps

After starting (via the installer or Docker), open the web dashboard:

http://<your-ip>:8502

Not sure of your Pi’s IP? Run hostname -I on the Pi, or check your router’s device list.

The dashboard binds to all interfaces by default, so it’s reachable from any device on your LAN — no extra step. Viewing needs no login; the Admin panel, the Settings management tabs and every action that changes something do. The bare-metal installer prints an auto-generated admin password once in its post-install summary (username admin) — log in with that when you open /admin. Lost it? See Remote Access & Security to read or reset CADDY_PWD. To restrict the dashboard to the Pi itself, set BIRDNET_LISTEN=127.0.0.1:8502.

If you set your latitude/longitude and an audio source, detections start appearing within a minute or two of the first bird call — no further configuration required.

A two-minute tour

The UI has six homes — the tabs along the top (and the phone bottom bar):

1. Today (/) — the home and right-now view: live signal, the day strip, and the full searchable detection log. See Today.
2. Species (/species) — browse every species you’ve recorded as a list, a photo grid or your growing life list. See Species & the Life List.
3. Patterns (/patterns) — the analytics: when birds are active, the dawn chorus, migration, who sings together, trends. See Patterns.
4. Recordings (/recordings) — play back captured clips and listen to live audio.
5. Reports (/reports) — the weekly recap, year in review and history calendar. See Reports.
6. Settings (/station) — health at a glance, plus all configuration and admin. Start with General (/station/settings) for optional fine-tuning: confidence threshold, per-species overrides, email, quarantine rules.

First-run wizard

You do not need a terminal, a config file or a command-line flag to get a new station detecting. Open /onboarding (a fresh station is sent there automatically the first time you open the dashboard) and answer a seven-step wizard — about two minutes:

1. Welcome — on a station with no admin password (a Docker run without CADDY_PWD, say) this step asks you to choose one, and the browser that finishes setup is signed in with it. If the installer generated a password for you, you are asked to sign in first and then land on the wizard.
2. Model — the bird-identifying model is a download of about 54 MB that the program does not ship. This step says whether it is installed; if not, one button downloads and checks it, with a progress bar. A download that fails says why and can be retried.
3. Location — latitude and longitude (with a lookup from a place name), the station’s name, and the language bird names are shown in. The location it saves must be a real coordinate pair (both values, within ±90 / ±180) and a time zone this host knows, or it is left unset and the server log says why.
4. Microphone — the sound cards the system lists that can record are offered by name, with a Test button that records two seconds and shows how loud it was. A network camera’s address (RTSP) or a device name can be typed instead. What you choose becomes the same audio source Settings → Capture shows.
5. Accuracy — plain-language presets for the minimum confidence a detection needs before it is recorded. The default is 0.70, BirdNET-Pi’s own default (it was 0.75 up to v0.17.1), so that a station nobody has customised stores the rows BirdNET-Pi stores for the same audio. Change it later under Settings → Capture → Detection Settings, where per-species thresholds also live.
6. Alerts — plain-language presets for when to be notified.
7. Done — saves everything and shows what is true now: whether the model is installed, which microphone was chosen, and the one button that restarts the station so it starts listening. A station that is not run by a service manager restarts itself in place; no terminal is needed.

Everything the wizard shows is read from the station itself — if a read fails the page says so instead of drawing a wizard from defaults that would overwrite your real settings. If nothing is configured as a microphone, the final page says so plainly, because a station with no source detects nothing.

After the wizard

Every setting can be changed later from Settings in the browser. Each setting carries a badge saying whether it applies immediately or after a restart; when something is waiting for a restart, a banner at the top of Settings says which settings and offers the restart button. The complete list of where each setting lives — and the few that are deliberately file-only, with the reason — is in Where to change it.

Health check

At any time you can run the built-in diagnostic, which prints a one-screen report covering CPU, configuration, audio reachability, the model file, database integrity, disk, and network — each problem with a concrete suggested fix:

# Bare metal: the service runs as the account that ran the installer (there is
# no "birdnet" user); this prints that account and runs the doctor as it
sudo -u "$(systemctl show -p User --value birdnet-behavior)" birdnet-behavior --doctor

# Docker
docker compose exec birdnet birdnet-behavior --doctor

See Troubleshooting if anything looks off.

Today

Today (/) is the home — the page you leave open. It answers “what’s happening in the yard right now?” before you ask, and it’s the merge of what used to be two separate screens (the Dashboard and the Today log): the live “right now” view and the full searchable day are now one calm page.

Coming from an older build (or from BirdNET-Pi)? The old /today address still works — it redirects here.

The five layers

1 · The glance. The hero leads with a plain-English, comparative headline — “A busy morning.” — computed from today’s count against your last 30 days, so a quiet day and a record day read differently at a glance. Beside it, the live signal card shows the last 30 seconds of audio. It is honest: it animates only while real audio is arriving from the capture device and falls back to a flat baseline labelled idle when nothing has been heard recently — never a fake waveform. A row of pills carries the recording state, current weather, sunrise/sunset, and your station’s name and coordinates. If the station cannot read its list of audio sources, the recording pill says the state is unknown rather than claiming there is no microphone.

2 · The nudge (only when it matters). A calm strip appears under the hero only when something needs your eye: rare detections waiting in the review queue, or an outage warning when capture has gone quiet during daylight. When all is well and quiet, it’s absent entirely. If the station cannot read the review queue, the strip says so instead of staying absent, because absent is how “nothing is waiting” looks.

3 · The shape of the day. The day strip plots the whole day on one 24-hour timeline — an hourly histogram of how busy each hour was, an amber temperature line overlaid on the same axis, labelled sunrise/sunset markers, and a “now” line. The header carries the day’s peak hour, dawn-chorus count and total.

4 · The heartbeat. One unified log. The live feed streams new detections as they arrive — each row a time, a species avatar (its four-letter banding code in the species’ own colour), the names, a mini call-waveform, the confidence, and a play button; a freshly arrived detection rises in with a brief moss pulse. The full day sits behind one “Show the full day” disclosure, where you can search (prefix NOT to exclude), filter by Rare / First today / High confidence, and lock, re-label or delete any detection. The list auto-refreshes, so a page left open stays current.

5 · The support rail. Today’s top species (with sparklines), the day’s best recordings, a one-line station-health readout, and quiet “looking back” links into Reports.

Arranging the page

A station on a kitchen tablet or a visitor-centre wall rarely needs everything an operator debugging a microphone does. The Today Page Layout section at the foot of the full settings page (/admin/settings, the Settings entry of the admin menu) lists the page’s parts in their current order, each with Move up, Move down and Show/Hide. Every press is saved at once.

Parts move within their own area: the headline, the nudge and the day strip among themselves at the top; the top-species, best-recordings and station cards within the side column. The detection log keeps its place and can only be hidden. Hide the log and the side column takes the full width; hide every side card and the log does. The order is the page’s real order, so a screen reader and the Tab key follow what is on screen.

The list also holds Your picture: one photograph of the site, or the last frame of a camera, with a title, between the day strip and the log. It is empty, and so invisible, until you give it a file under Settings → General → System & Display → Today page picture (see Settings).

A new station shows everything until its first detection, so the setup checklist in the headline cannot be hidden by accident.

First run

A brand-new station — one that has never heard a bird — shows a friendly “getting ready” checklist in place of the live signal (microphone detected, model loaded, disk headroom, listening…) plus illustrated empty states, so the very first hour is an activation moment rather than a blank page. The page comes alive the moment the first call lands.

Light & dark

The whole UI honours your operating system’s colour-scheme preference and remembers any manual override. Dark mode is a cool “observatory” black tuned so the moss and dawn accents glow rather than muddy.

Every page carries the same top navigation, theme toggle and global species search, so you’re never more than one click from any home.

Species & the Life List

What the Species home shows — the list of every bird the station has recorded, how to browse it by taxonomy, the per-species page and the life list — and how to read each; for anyone, hobbyist or researcher, who wants to browse or review what the station has heard.

Species list

The Species page (/species) is the browsable index of every bird you’ve recorded — searchable and sortable by most-heard, A→Z, or newest.

Each row carries the species avatar, common and scientific name, all-time count, a 14-day sparkline, average confidence, and first/last-heard dates.

Browsing by taxonomy

When the station has its classifier label file, the List and Photos views carry a row of order chips — Piciformes, Strigiformes, Anseriformes — with the number of your species in each. Clicking one narrows the page to that order; clicking All orders widens it again. The chips are built from the species you have recorded, not from the classifier’s 11 560, so a garden with forty birds gets a handful of orders rather than seventy-five, and every chip leads somewhere.

The chips and the search box compose: search inside an order, or pick an order while a search is active, and neither drops the other. The view switcher keeps the order too, so List → Photos stays on the same birds.

Three ranks are browsable — class, order and genus — and each is a link on the species detail page, so “the other Dryobates I’ve heard” is one click from a woodpecker. Genus has no chip row: 2 907 genera is not a control.

There is no family. The shipped label file states a class and an order and nothing between them (its header is idx;id;sci_name;com_name;class;order), so a family would have to be inferred from the genus, and a guess sitting beside two stated facts is worse than an absent rank. A station whose label file has no taxonomy columns at all — the V2.4 text format has none — simply gets no chips, and its pages are exactly as they were.

Species detail

Click any species for its detail page (/species/detail?name=…): a full-bleed Wikipedia photo, the scientific name and description, its class · order · genus (each a link back to the list filtered to that rank), an hourly activity profile (columns from zero, the busiest hour labelled, a tooltip for every hour), the last 14 days as columns against the average, Through the year (a calendar with a cell for every day of the past 365: how many times it was heard, with the days the station was not listening hatched so they are not read as days the bird was quiet), companion species (the birds it’s most often heard alongside), and a strip of recent recordings.

Why isn’t a bird heard here?

A bird you can hear and the station never logs is, sometimes, a bird the station’s range filter drops. The station asks a range model which species occur around where it is in each week of the year and holds back any it scores below the Species Frequency Threshold (default 3 %); see the settings. Until now nothing said which birds that was.

The link Why isn’t a bird heard here? at the top of the Species page (/species/occurrence) is the answer. Type a bird’s name, in English, in the scientific form or in the station’s own language, and it says in a sentence whether the station admits that bird this week, with the numbers: “Held back: the range model gives it 0.4 % here in week 22; this station admits species at 3 % and above.” A bird the model scores well but that your own include or exclude list keeps out is said to be held back by your lists, not by the model, and a bird under the threshold that you put on the Always allowed list is said to be allowed by it. The week defaults to the current one; the selector goes through the model’s 48-week year, four weeks to a month, so you can ask what the station would admit in May. Below the answer is the list of the birds the station does admit that week, a hundred at a time.

When a species page is for a bird the filter would hold back this week, a line under its headline says so and links to the answer for that bird.

If there is nothing to show, the page says why instead of showing an empty list, which would read as “nothing occurs here”: the station has no location, no range model is loaded (so the filter is off and every bird the classifier knows is a candidate, wherever the station is), or the model would not run. The same answer is available to scripts as GET /api/v2/species/occurrence. The numbers are the filter’s own: the species the page marks admitted are exactly those the detection daemon lets through for that place and week, and a test holds that against the real V2.4 range filter.

The station’s location is shown to one decimal place (about 11 km): enough to say which region’s birds the question is about.

Life list

The Life List (/species?view=lifelist — the old /life-list still redirects in) is your birding journal — every species, once. It leads with three tallies (species, total detections, active days) and a smooth accumulation curve showing the list growing month by month (a dot in each month that added a bird; point at a month for the total so far and how many came that month), then a per-month “new species” chart and the full ranked table with average-confidence pills.

Confidence pills and bars use one colour rule everywhere in the app: green at 90 % and up, amber for a detection within ten points of the station’s own cut-off (borderline), neutral in between. Because the edge follows your cut-off, a station that keeps 80 % and up has two tiers only: everything under 90 % reads as borderline. A key above each list says which applies, and none of the colours is the alert red.

Patterns

Patterns (/patterns) is the analytics home — “when & where?”. It gathers the station’s deeper readings behind one tab strip, each tab leading with a single picture and a plain-English read, with the dense numbers tucked behind a “see the numbers” disclosure. A hobbyist never meets six analytical surfaces at once; a researcher still reaches every one in a click.

The old standalone addresses still work and redirect into the right tab: /heatmap → When active, /analytics/dawn-chorus → Dawn chorus, /migration → Migration, /correlation → Who sings together, /timeseries → Trends, /analytics → Behavior.

Every chart is rendered server-side as inline SVG — no JavaScript charting runtime — so the page stays light on a Raspberry Pi and works offline. The three deepest readings have their own pages, linked above.

The soundscape terrain

The When active tab leads with the station’s last 30, 90 or 365 days as a landscape: the hours of the day across, the days down (the newest at the bottom), and the colour of each patch how much was heard in that hour of that day. It opens as a flat grid of those numbers. 3D terrain raises the same numbers into a height-field you can turn: drag (or one finger) to orbit, scroll after clicking it or pinch to zoom, the arrow keys to turn, plus and minus to zoom, Home to put it back, Shift with the arrows to move a reading cursor. Colour by switches from how much to which species was heard most in each hour.

Height and colour are the square root of the count, so a quiet hour beside a busy one is still there. A day the station was not listening, and an hour that has not happened yet, are flat and hatched: that is not the same as quiet. The 3D view loads its one library (a part of three.js, about 134 kB compressed) only when you choose it; a browser without WebGL keeps the grid and says so. Every reading is written under the picture and the numbers are in a table behind “See the numbers”. Design notes and the checks behind it: docs/design/charts-relational.md.

Behavioral Analytics

BirdNet-Behavior turns a stream of detections into behavior. The analytics screens answer when the yard is alive and who sings with whom.

Activity heatmap — “When the yard is alive”

The When active and Dawn chorus tabs of Patterns (/patterns) stack several bespoke visualizations:

• Activity streamgraph — species composition over time, drawn from a centered baseline. Each band is a species and its thickness is that day’s count; the eight busiest are drawn one by one and every other species is one more band, so the whole is the day’s real total. Point at a day (or use the arrow keys) for every species’ count; point at a band, or at a name in the key, to bring that species forward and put the rest in the background. The curves between days are smooth but never rise above a peak or below a trough the counts did not have. A day the station was not listening is hatched, so it is not read as a silent day.
• Activity grid — an hour × day-of-week mosaic of rounded cells on the sequential sand-to-brick ramp (one hue family, steps by the square root of the count so one detection and ten are told apart). The colour is the average per day in that slot, so a 90-day window’s thirteen Mondays are compared with its twelve Tuesdays fairly. The totals for each weekday are beside the grid and the totals for each hour are under it; the busiest cell is ringed and named. Three states are kept apart: a count is a colour, a quiet hour is an empty cell, and a weekday the station was off for is hatched; an hour of today that has not happened yet is an outline that says “Not yet”.
• Circadian rhythm — a polar plot where each species occupies its own concentric ring that swells where it’s active across the 24-hour clock, with a sky strip (night, first light, day), three-hour ticks, the sun and a solid “now” hand; see The Dawn Chorus.
• Detections by hour — the day’s totals as columns on an axis from zero, with the night shaded behind them (from your station’s sunrise and sunset) and dawn and dusk in colour. It is a bar chart rather than a clock because the question is how much more: length on a common baseline is read more accurately than an arc, and the dawn chorus tab already has the clock for who sings when. Only the busiest hour is labelled; point at any hour for its count, its share of the day and, on Today, its three busiest species.
• Seasonal phenology — a migration ridgeline, one gradient-filled ridge per species, with spring and fall season bands behind; see Migration & Phenology.

Pointing at a chart

Every chart here answers to a pointer, a finger and a keyboard alike. Point at it (or touch it, or Tab to it and use the arrow keys) and a small card reads out what is under you: the day and every species’ count, the hour and its share of the day, the cell and its count. Left and Right step along the chart, Up and Down step by row (the grid), by week (the calendar) or from species to species (the streamgraph), Escape lets go, and each step is read aloud to a screen reader. The same figures are always in the table under the chart, behind “Show as a table”. Nothing moves when you do this, and with reduced motion on (in your system, or under Settings → General → Display → Motion) the charts simply appear instead of growing into place. The reasoning behind how these charts are drawn, and what they refuse to do, is in docs/design/charts.md.

Co-occurrence — “Who sings with whom”

The Who sings together tab of Patterns (/patterns?tab=together) shows which species are detected together — heard in the same five-minute block of the same day. A pair’s strength is its overlap: the blocks they share, as a share of the blocks in which either was heard. A pair needs at least three shared blocks to be drawn.

• The acoustic network — the data drawn as a chord diagram: each species an arc, each pair that is heard together a ribbon whose width and colour are how much of their time they share. The species stand in the order that crosses the fewest ribbons, so groups that sing together sit together. It shows the 12 strongest links (choose 24 or All). Point at a name and only its ribbons stay in the foreground; point at a ribbon and only it and its two species do. The ring needs a wide screen: on a phone you get the ladder instead, a staircase matrix with each name at the foot of its own step (read across a row to its name, up a column to the other).
• Co-occurrence matrix and strongest pairs — the same numbers as a table behind “See the numbers”.
• Top co-occurring species and a companion lookup let you ask “what’s usually nearby when I hear X?”

The richest DuckDB-powered views — activity sessions, species retention, next-species prediction, year-on-year trends — are on by default: every release has the analytics engine built in, and the installer and Docker compose enable it automatically. If you’ve turned it off on a low-RAM board, these panels explain what they’d show and how to switch it back on. See Configuration.

Behavior — the research tier

The Behavior tab of Patterns (/patterns?tab=behavior) draws what the analytics engine computes; each picture keeps its numbers in a table.

• Bursts of singing — a lane per day with the hours along it and a bar for each burst, from the moment it began to the moment it ended; bursts of different species that overlap are stacked, never drawn over each other. The legend brings one species forward.
• Who keeps coming back — species grouped as resident, regular, migrant and rarity (how much of the station’s time they were present), with the weeks each was heard and how often it was heard again a day, two, three, a week, a fortnight and a month later, each a cell that also prints its number.
• Neighbouring species — who is heard just before and just after the latest species, as a flow with that species in the middle (ranked bars on a phone); a ribbon’s width is the share of sessions.
• The morning running order — a lane per voice of your dawn, the clock from 04:00 to 09:00 along it, a dot for every morning’s first-heard time, thin lines joining the newest mornings from lane to lane, a tick at each voice’s typical time and the newest complete morning drawn large. A line that slants steadily to the right as it goes down is a morning in the usual order.

Migration & Phenology

The Migration tab of Patterns (/patterns?tab=migration) turns a year of detections into a picture of when each species moves through your yard. It’s the seasonal companion to Today’s right-now view: instead of “what’s singing this minute?”, it answers “who has arrived, who’s peaking, and who’s overdue?”

What you’re looking at

• Four KPI tiles across the top:
  • First-of-year arrivals — species whose first-ever detection at the station falls in the current year.
  • Peak diversity week — the calendar week with the most distinct species so far.
  • Earliest vs last year — of the birds that arrived in both this year and last (first heard from the end of January on), the one that came furthest ahead of its arrival last year, in days (a negative number means earlier). It needs a last year that was recorded from its start: a station that began part-way through it says “last year was only partly recorded” rather than comparing a first date that is only where recording began.
  • Still expected — species that arrived within the next six weeks of the prior year and haven’t been logged yet this year. It says “needs a year of records” where there is no last year to expect from.
• The ridgeline (“joyplot”) is the heart of the page: one ridge per seasonal species, stacked and ordered by peak week, a ridge being the species’ detections each week as a share of its own busiest week. A ridge’s colour is the season it peaks in (green for the spring migration window, amber for the fall one, grey for neither; the windows swap south of the equator). Point at a week to read every species heard in it with its real count and how many different species were heard; the weeks that have not happened yet are hatched, not drawn as zero.
• The species-per-week lane under the ridges is distinct species heard each week, on the same weeks.
• Editorial cards call out what just arrived, what’s currently peaking, and what is missing: the birds that arrived in these weeks last year and have not been heard yet.

How a species qualifies as “migratory”

The ridgeline uses a deliberately cheap heuristic on the current year’s data: a species earns a ridge when its busiest week is at least three times its median active week (a sharp seasonal pulse), holds at least five detections, and it has been heard across at least four weeks. When more than twelve qualify, the twelve most sharply seasonal are drawn. Year-round residents — which detect at a steady level — are filtered out so the plot stays about movement, not abundance. Early in the year the page is naturally sparse; it fills in as the season progresses.

This is a station-local view built entirely from your own detections table — no external range maps. It reflects what your microphone hears, which is exactly the point.

Not the same as “Migrating from BirdNET-Pi”

This page is about bird migration through your yard. If you’re looking to import data from an existing BirdNET-Pi install, that’s a different feature — see Migrating from BirdNET-Pi and the import panel under Settings → Data (/station/data#import; the old /admin/migrate redirects there).

The Dawn Chorus

The Dawn chorus tab of Patterns (/patterns?tab=dawn) shows the daily rhythm of your yard: which species sing when, wrapped around a 24-hour clock and anchored to the real sunrise and sunset for your location.

What you’re looking at

• The rings plot detection activity around a 24-hour dial (midnight at the top, noon at the bottom). Each species is a coloured ring that swells outward at the hours it was heard, scaled to its own busiest hour so a quiet wren reads as clearly as a loud cardinal. Point at a ring (or tab to it and use the arrow keys: left and right move by the hour, up and down from ring to ring) and it comes forward and says the hour, the count, that hour’s share of the bird’s day and its busiest hour. A swell sits on the middle of its hour: a bird heard through 06:00-06:59 peaks at 06:30.
• The sky strip round the rim is drawn from the station’s coordinates: night, first light (civil dawn), daylight and last light, with the sun where the colour changes. The times are in the key beside the chart. Birds start singing in first light, so it is drawn beside sunrise.
• The middle says the time now (the line from the centre is the same hand) and the window the rings are drawn from (60 days); the four arcs round it are the moon’s phase.
• The key beside the chart names every ring with its busiest hour; hover or focus a name to bring its ring forward, click to hold it.
• Each bird’s day lays the same species flat: one row each, a column per hour, the dawn window shaded and the sun’s day a line. The numbers are in a table under it.

Setting your location

The sunrise/sunset markers use the station’s configured coordinates — the latitude / longitude settings you enter in the onboarding wizard or under Location & Recording Schedule on the settings form. With no coordinates the ribbons still draw, but the sun markers and the night wedge are omitted rather than guessed (see below). BNB_STATION_LAT / BNB_STATION_LON are read only by the weather integration and have no effect here.

A note on time zones

Everything on this clock is in the station’s local time: the ribbons are bucketed from the local hour in each recording’s filename, and the sunrise/sunset markers are computed for your configured coordinates and then shifted into the same local frame. Set your station’s timezone with timedatectl set-timezone (which is what --doctor checks) and set your coordinates on the Settings page — the two together are what makes the sun markers land where the sun actually was.

This page previously told you to run the station on UTC. That was advice for a defect, not a design: the markers were computed in UTC and drawn over local-time ribbons, so on any non-UTC station they were offset by the UTC difference, and they contradicted --doctor, which has always told operators to set their local timezone. The markers were additionally computed for a hard-coded (40.0 N, 74.0 W) unless two undocumented environment variables were set, on a day-of-year that drifted about a day a year. All three are fixed; run the station on its real timezone.

No coordinates set? The ribbons still draw — they need no location — but the sun markers and the night wedge are omitted rather than guessed. A sun drawn where your station is not would answer “does this species sing before sunrise?” wrongly while looking authoritative.

Like the migration view, this is built entirely from your own detections — no external data.

Recordings & Live Audio

Recordings (/recordings) is the audio home — both the saved clips and the live stream.

The home has two views, switched on the sub-tab row: Clips (browse what your station already caught) and Live (listen along in real time).

Clips (/recordings?view=clips)

Clips is a flat, newest-first list of every detection that saved an audio clip. Each row carries the time, the species (with its banding-code avatar) and a confidence bar; play it with the ▶ button, download it, lock it, or delete it.

• Filter chips narrow the list to All, Best (high-confidence), Rare (a confident first-ever record) or Locked clips, and the search box finds a species by name. The chips and search are real links, so any view is bookmarkable.
• Now playing rides the page header while a clip plays and floats up into a compact bar when you scroll past it, with a live progress scrubber.
• Lock (🔒) protects a clip from the disk purge — the same lock you can set from Today; locked clips also show under the Locked filter.
• Select turns on checkboxes and a bulk bar so you can lock, download or delete a whole batch at once.

Live (/recordings?view=live)

Open the Live view to listen along with your station in real time — a per-source audio player and a scrolling spectrogram, with a live trickle of detections as they’re classified. The spectrogram is honest: it scrolls only while audio is arriving and shows a flat baseline otherwise, never a fake waveform. Today’s live-signal card links straight here, and you can preselect a microphone with /recordings?view=live&source=<id>.

The pre-spine /listen, /livestream and /live addresses still work — they permanently redirect to /recordings?view=live.

Species photos

The species Gallery now lives as the Photos view of the Species home (/species?view=photos) — a photo-card grid of every detected species, searchable and sortable. The standalone /gallery address still works.

Each card shows the species photo (cached from Wikipedia, with attribution), the common and scientific name, the detection count, and a confidence pill. Species without a cached photo fall back to an on-brand placeholder tinted in the species’ own color and stamped with its banding code — so the grid stays cohesive even before images load.

All bird photos are cached locally from Wikimedia Commons under CC BY-SA, and the attribution is shown on each image as the license requires.

Reports

BirdNet-Behavior turns your data into editorial recaps you’d actually want to read. Reports (/reports) gathers the look-back in one place, behind three tabs.

Weekly

The Weekly tab (/reports) is a Sunday-paper recap of the week — total detections, species count, new arrivals, a daily-activity chart and the week’s leaderboard. Navigate between weeks with the prev/next controls.

Year in Review

The Year in Review tab (/reports?tab=year) is a celebratory recap of the calendar year so far — 1 January to today. Every figure on it covers that period and nothing earlier; on New Year’s Day it starts again from nothing.

• a display headline and four big-number tiles (detections, species heard, species new to your list — first heard on this station this year — and the busiest day),
• a calendar of the year — a cell for every day since 1 January, a column a week, coloured by how many detections that day (the busiest day is ringed and named; a day the station was not listening is hatched, so it is not mistaken for a quiet one) — that shows its rhythm at a glance,
• the year’s species leaderboard with banding-code avatars,
• a milestones strip (first voice of the year, most-heard species, busiest day, newest arrival),
• and a closing tally.

History calendar

The History tab (/reports?tab=history) is a calendar browser. Each day tile is intensity-coded by detection count; select a day to see its hourly activity and top species.

Reviewing Detections

BirdNet-Behavior classifies every clip automatically, but you are the final arbiter. The detection-review queue lets you record a verdict — confirmed or rejected — on individual detections, building a clean, human-checked record over time.

Reviews vs. quarantine

These are two different quality-control surfaces; it helps to keep them straight:

A rejected review flags a likely misidentification for your own records — it does not remove the detection. Quarantine is the tool for keeping a dubious record out of the log entirely.

The triage queue (/detection-reviews)

The queue lists recent detections that have no verdict yet, newest first, each with its species, time, and confidence. Two buttons record a verdict:

• ✓ Confirm — the identification looks right.
• ✗ Reject — likely a misidentification.

A running tally at the top shows how many detections you have confirmed, rejected, and have left to review. Recorded verdicts move to the Recent verdicts list, where an Undo button clears a verdict and returns the detection to the queue. Re-reviewing a detection simply replaces its previous verdict — there is never more than one verdict per (date, time, species).

Reviewing from a detection

You don’t have to work the queue to leave a verdict. Every detection-detail page carries a Review this detection widget with the same Confirm / Reject buttons and a badge showing the current verdict, so you can judge a clip the moment you’re looking at it — spectrogram, audio and all.

Comments: why, not just what

A verdict says what the station decided. Six months later the question is why — and “call length says Downy, but the spectrogram is Hairy” is the sentence that makes a record defensible to somebody who was not there.

Under the review widget, every detection-detail page carries a Comments thread. Write a note, it appears with your username and the time, and it stays that way: a comment is never edited. The database refuses it — there is a trigger on the table that aborts any attempt to rewrite a comment’s text, author or timestamp — so what you read is what was written.

Two things follow from that, and both are deliberate:

• Many comments per detection. Two observers disagreeing is the point. This is the difference from the review widget’s own notes field, which is keyed on the detection and replaces whatever was there: a second reviewer’s note silently erased the first one’s reasoning, and neither of them was named.
• A comment can be withdrawn, not rewritten. Remove deletes it outright — which is what a note containing a typo, or a neighbour’s name, needs. The audit log records the removal, its author and its id, and never the text: a comment deleted because of what it said must not survive in the log that recorded its deletion.

Comments are up to 2 000 characters, and writing one needs an admin sign-in — the same gate as confirming or rejecting. Anyone who can see the detection can read the thread.

Scripts can join in through the API: GET, POST and POST …/delete on /api/v2/detections/comments (see the API reference). Those comments are attributed to api rather than to a name the caller supplies — a bearer token is not a person, and a name the caller chose is not attribution. A script with something to say about who is speaking says it in the comment.

Sharing a detection for a second opinion

Not sure about a call? Both the detection-detail page and every row in the quarantine queue have a Share button that copies a public /r/<token> link. The share page resolves quarantined rows too, so you can send a rare bird that hasn’t been admitted to the log to another birder for a second opinion before you decide.

Detection Detail & Share Links

Every detection in the app — a feed row on Today, a point in a chart — links through to a detail page that shows everything known about that one moment, and lets you hand it to someone else with a single public link.

The detail page

/detections/detail?date=…&time=…&name=… is the canonical detail view. A detection has no numeric id; it is identified by the (Date, Time, Com_Name) triple, which is what the route’s three query parameters carry.

It shows:

• the species (common + scientific name), confidence, and exact timestamp;
• the 3-second clip, rendered as both a spectrogram image and an inline audio player, when a recording is on disk for that detection;
• the correlation id the detection daemon stamped on every log line, DB write and notification for the source file — copy it and grep your logs to pull the exact decode→infer→notify slice that produced the row;
• the audio source that heard it (the stream label — e.g. cam1 or local — recorded on every detection since the multi-stream update);
• an “also heard by” corroboration card on a multi-source station: when another stream detected the same species at nearly the same moment, it is shown here. Independent agreement across microphones is a stronger signal that a detection is real — useful when the identification matters, such as a rare-species record. The card is read-only and never merges or hides rows;
• a Share clip button;
• a Review this detection widget — confirm or reject the identification in place (see Reviewing Detections).

Share links (/r/<token>)

The Share clip button copies a public, self-contained URL of the form /r/<token> to your clipboard. Anyone with the link sees a clean, single-detection page — species, time, spectrogram and audio — with no navigation into the rest of your station and no login.

How the token works:

• It encodes (date, time, com_name, expiry) and a truncated HMAC-SHA256 signature, base64url-encoded. Links default to a 30-day lifetime.
• Verification is constant-time. A tampered or expired token renders a neutral “This clip is gone” page (HTTP 404, noindex) that leaks nothing about whether the detection exists.
• /r/<token>/audio.wav and /r/<token>/spectrogram.png resolve the recording by filename and serve it through the same handlers as the normal media routes, so the clip and spectrogram render without exposing any internal id — and without depending on those routes being reachable.

The signing key

With BNB_SHARE_SECRET unset — the usual case — tokens are signed with a key derived from the station’s own session secret, which is random and kept beside the database. Links therefore survive restarts, and changing that secret invalidates them.

Set BNB_SHARE_SECRET only to rotate share links on their own:

# 32+ random bytes
BNB_SHARE_SECRET="$(openssl rand -base64 48)"

A value shorter than 32 bytes, or one still containing CHANGE-ME, is ignored with a warning and the derived key is used instead.

Share links are deliberately read-only and scoped to one detection. They are not affected by — and do not bypass — the admin password or any reverse-proxy auth in front of the main UI. On a station in private mode they are behind the sign-in like everything else unless BIRDNET_PUBLIC_ACCESS includes share, which opens the links you mint and nothing else.

RSS & Calendar Feeds

The station publishes lightweight, public, read-only feeds so you can follow your yard from a feed reader or a calendar app without leaving a browser tab open.

The rare feeds list first-ever-at-this-station detections with confidence above 0.85 (strictly > 0.85) — a low-noise stream of genuinely new birds. The today feed is every detection from the current day (chatty by design).

Discovery

The dashboard advertises the rare RSS feed in its <head>, so feed readers offered the page will find it automatically:

<link rel="alternate" type="application/rss+xml"
      title="BirdNet · rare detections" href="/feeds/rare.rss">

Each feed item links back to the detection detail page for that bird, and the iCal events carry a stable UID, a 3-minute duration, and the same detail link.

BNB_BASE_URL — make the links absolute

Feed items need absolute URLs so they work in an external reader. Set BNB_BASE_URL to how the station is reached from outside:

BNB_BASE_URL=http://birdnet.local        # mDNS on the LAN
# or
BNB_BASE_URL=https://birds.example.com    # behind a reverse proxy

If unset it defaults to http://localhost:8502 (the server’s own port). A request can name its own base with ?base=…, which is how a reverse proxy gets the scheme and path prefix right, but only for an address the station already knows: the host the request was addressed to, or the host of BNB_PUBLIC_URL or BNB_BASE_URL. Any other ?base= is ignored and the default is used, so a feed address cannot be made to point at someone else’s site. If a proxy rewrites Host and your readers pass ?base=, set BNB_BASE_URL. Cap item counts with ?limit=….

Caching

RSS responds with Cache-Control: private, max-age=300 (5 minutes); iCal with private, max-age=3600 (one hour), since calendar clients repoll slowly. Both say private, so a shared cache or CDN in front of the station will not keep a copy. An empty station still returns valid, well-formed XML/iCalendar.

These endpoints are unauthenticated and expose the same information as the public dashboard. If you gate the UI behind a reverse proxy, decide whether to expose /feeds/* alongside it.

Display Preferences

BirdNet-Behavior adapts to how and where you watch it — a phone on the trail, a wall-mounted Pi touchscreen, a desktop in a bright room. The Display Preferences card on the Station Health tab (/station) lets each viewer tune the interface; choices are stored locally in the browser, so they’re per-device and need no login.

What you can change

• Theme — Light, Dark, or follow the operating system. Dark mode is a cool “observatory” black tuned so the moss/dawn/rare accents glow.

• Density — Compact, Regular, or Comfy. Compact tightens spacing for dense dashboards and small screens; comfy opens it up for touch and across-the-room reading.

• Motion — Reduced honours users who prefer fewer animations (and is picked up automatically from the OS “reduce motion” setting); the live-feed pulse and chart transitions are quietened.

• Contrast — High strengthens borders and text contrast for bright environments and accessibility.

• Clock and Temperature — Station (follow the owner’s default, below), or 24-hour / 12-hour and °C / °F for this browser. A 12-hour clock prints 4:31 PM; midnight is 12:xx AM. Every time the pages show as text and every temperature goes through one formatter; the station stores and exports Celsius and 24-hour ISO times whatever is shown, and feeds, CSV, JSON and the API are not changed. Not converted: the hour labels, tooltips and readouts inside the charts, which are plain text in SVG and attributes, the admin tables whose times are labelled UTC, and the public share page, which is a document of its own.

• Listening — three aids for quiet clips and noisy sites, applied while a clip plays in this browser: Boost (up to +24 dB), Cut low rumble (a high-pass filter, 20 Hz to 8 kHz, logarithmic, for wind and traffic) and Even out loud and quiet parts (a compressor). They apply to every player on every page (the play buttons on Today, the Clips list, the live listen, a clip’s own page); the controls also sit in a Listening aids fold on a clip’s page. All three are off by default and then the clip is played exactly as the browser always did. Nothing is ever changed in the recording or in a download.

  The chain ends in a soft limiter, so the output never passes full scale: measured through the page’s own graph on four real clips (BirdNET-Pi’s magpie, birdnet-go’s tawny owl and soundscape, and a fixture clip) at up to +24 dB with the compressor on, the output peak stayed at or below −0.2 dBFS in all 28 cases; without the limiter the same settings reached +16 dBFS. A large boost on an already loud clip is limited, not clean: use it for quiet recordings. The controls are keyboard-operable, announce their values to a screen reader, and use no animation. Needs a browser with Web Audio; without one they say so and change nothing.

The station’s default

Settings → General → System & Display → Clock and Temperature unit set what a browser that has not chosen shows (time_format 24h or 12h, temperature_unit celsius or fahrenheit; served at GET /api/v2/display). The page is first printed in the canonical 24-hour, Celsius text and re-printed by static/display-format.js; the default is remembered for the tab in sessionStorage, so a 12-hour station flashes 24-hour text only on the first page of a tab, and with scripting off the canonical text stands. A test (the_clock_and_temperature_are_printed_in_one_place) fails on a page that prints a time or temperature by hand, and tools/visual-qa/display-format.mjs holds the browser’s formatter to the same table of cases as the Rust one.

How it’s applied (no flash on load)

Preferences are stored under the theme, bnb-density, bnb-motion, and bnb-contrast keys in localStorage (the listening aids under bnb-listen; a browser that blocks storage simply does not remember them). A tiny guard script runs before first paint — inline in the main layout, where it sets the data-theme / data-motion / data-contrast attributes and the --density variable on <html> immediately, and as /static/theme-guard.js for the standalone admin pages, which applies only the theme and density keys. That pre-paint step is what prevents the brief “flash of the wrong theme” (FOUC) when you reload a page.

Because the values live in the browser, they persist across reloads and survive station restarts, and two people looking at the same station on different devices each get their own settings.

Kiosk Mode

Kiosk mode (/kiosk) is a full-screen, auto-refreshing display for a wall-mounted screen — a Raspberry Pi touchscreen by the window, a spare monitor in the hallway, a TV in the visitor center.

It strips away the navigation chrome and shows the numbers that read from across the room — today’s count, the all-time total, species, and a stream of the most recent detections — refreshing on its own so it never goes stale.

To leave kiosk mode, click the dimmed Exit link in the top-right corner, or press Esc — either returns you to the full dashboard. (The link stays faint so it never competes with the display, and brightens on hover.)

Tips for a dedicated display

• Point a full-screen browser at http://<your-pi>:8502/kiosk.
• Kiosk mode defaults to the dark “observatory” theme, which is easy on the eyes for an always-on screen and avoids burn-in on OLED panels.
• On Raspberry Pi OS, Chromium’s --kiosk flag plus the URL is all you need in an autostart entry.

For an always-on Pi display, make sure a system CJK font (e.g. fonts-noto-cjk) is installed if you expect non-Latin species names — the dashboard itself ships all its Latin fonts self-hosted and never calls out to a font CDN.

Settings & Detection

The admin area lives under /admin. The Settings page (/admin/settings) persists everything you change into the SQLite settings table.

When a change takes effect

Every field on the page carries a small badge: Applies immediately (the part of the station that uses it reads the stored value again on its own, typically within about half a minute) or Applies after restart (the value is read once, when the station starts). The badge is drawn from one table in the code, and a test fails if a field on the page lacks one, so the page cannot disagree with itself.

When you have saved something that is still waiting for a restart, a banner at the top of the page lists which settings and offers the Restart button. Under a service manager (systemd, Docker’s restart policy) the button stops the process and the manager starts it again. A station started by hand restarts itself in place with the same arguments; if neither is possible the button says so instead of stopping the station and leaving it stopped.

The bird-identifying model

At the top of Settings → Capture (and as step 2 of the setup wizard), the Bird-identifying model panel says whether the classifier the station needs is installed. If it is missing, Install downloads it (checked against a pinned SHA-256, with a progress bar and a free-space check first) and the panel then offers the restart that loads it. This is the same installer as --install-model; the program, not the browser, does the download.

Numbers the page refuses

A number typed into a field is checked against the range the station actually accepts before it is saved, and the message names the range. The same bounds apply to PUT /api/v2/settings and, as warnings, to --doctor for the config file: frequency shift, sunrise/sunset recording offsets, notification cooldown, dead-man hours, clip retention days, files kept per species, disk purge threshold, extraction length, rare-species window, stream retention and size, SMTP port, email cooldown and clip loudness target. (They are warnings, not errors, in --doctor because an error makes the station fall back to its last-good configuration file.)

How a setting is resolved

Most settings can be supplied three ways — a CLI flag (or its BIRDNET_* environment variable), a line in birdnet.conf, and this page. When more than one is set, the station resolves them in this order:

1. An explicit CLI flag or BIRDNET_* variable — if you passed it, it wins.
2. This page — what you save here beats the config file.
3. birdnet.conf
4. The built-in default.

So a Docker station pinned with -e BIRDNET_SEGMENT_DURATION=30 keeps that value no matter what the form says, while a bare-metal station that never passes the flag is governed entirely by this page.

Settings not on this page

Two things are deliberately configured elsewhere in the browser:

• The admin password. It is stored as an Argon2id hash in the accounts database, seeded from the CADDY_PWD environment variable — never as a settings row. See Remote Access & Security.
• Per-source audio properties (channels, sample rate, gain, RTSP transport). Each microphone or stream carries its own, on Audio & Microphones.

A handful of settings are file-only on purpose, each for a stated reason — secrets that must not live in the database a backup copies, listen address and TLS (a typo locks you out of the page you would fix it on), and similar. Where to change it lists every setting, the browser page that owns it, and for the exceptions why.

Detection

• Confidence threshold — the minimum score a detection must clear to be logged (default 0.70, BirdNET-Pi’s own; it was 0.75 up to v0.17.1). Raise it to cut false positives; lower it to catch faint calls.
• Per-species thresholds — override the global threshold for individual species (useful for a noisy local mimic, or to be stricter about a rare bird).
• Sensitivity (0.5–1.5) — the BirdNET sensitivity parameter (also SENSITIVITY in birdnet.conf). It only affects BirdNET V2.4 models; the BirdNET+ V3.0 preview ignores it. It means what it means in BirdNET-Pi and BirdNET-Analyzer, so a value carried over from BirdNET-Pi reproduces that station’s confidence scores: the model’s raw score is passed through a sigmoid with slope clamp(2 − value, 0.5, 1.5). A higher value therefore flattens the curve, and at any confidence threshold above 0.5 (all the usual ones) it gives fewer detections, not more. birdnet-go’s sensitivity is the slope itself, so to carry a birdnet-go value across, enter 2 − value.
• Human-sound privacy — a station near a house will sometimes hear speech, and two independent rules keep it out of the log and the saved clips: a window, and the windows either side of it, are suppressed when either fires. Each is a field in the Detection section.
  • The rank rule, Privacy Rank (PRIVACY_RANK, default 10, 0 = off, up to 12000), is BirdNET-Pi’s own: it fires when a human class (speech, whistling, other human sounds) is among the model’s N highest-scoring classes, read before the confidence threshold. It is on by default, including on a station upgraded from a release that had no such rule and that sets neither key; 10 is BirdNET-Pi’s behaviour. A larger number drops more windows. It is a whole number, a count of classes and not a confidence: 0.02 is refused rather than cut to 0 (which would switch the rule off), and so are 10%, 1,000, a negative number and anything above 12000, with a message that names the range. Leave the field blank to fall back to the default. The same bounds apply to the config file (--doctor checks them) and to PUT /api/v2/settings. A flag or variable other than 10 (--privacy-rank, BIRDNET_PRIVACY_RANK) still beats the page.
  • The confidence rule, Privacy Threshold (PRIVACY_THRESHOLD, default 0 = off, typically 0.01–0.03), fires when the model’s confidence for a human class reaches the value. It shares its name with a BirdNET-Pi key that is on a different scale, so a BirdNET-Pi value does not carry across; Same audio, same detections has the conversion.
• Species-frequency filter — uses your location and the week of the year to down-weight birds that shouldn’t be present, with a configurable SF_THRESH. To see what it admits, and why a particular bird is held back, open Why isn’t a bird heard here? on the Species page.
• Noise filter (NOISE_THRESHOLD, NOISE_CLASSES) — optionally discards a window in which a watched non-bird class (by default Dog) scores at or above the threshold. Off by default; see Tuning §7. There is no filter that drops rainy or windy audio before it reaches the model.
• Analysis overlap (0–2.9 s) — how far consecutive analysis windows (3 s for V2.4, 4.5 s for the V3.0 preview) overlap. Higher catches calls that straddle a window boundary, and costs CPU in proportion: 2.0 triples the inference work per recording.
• Repeat confirmation — record a species only when enough of the windows within six seconds heard the same thing. A real bird sings across several windows; a car door or a squeak of the mount usually fires in exactly one. It needs the overlap above — with none, there is only one other window to agree with, and each option in the dropdown prints the overlap it needs. Off by default. See Tuning.

Species & quarantine

Rare-bird quarantine rules decide which detections are held for manual review instead of being logged automatically — see the review queue. You can also maintain per-species allow/exclude lists and image overrides here.

Allow and exclude lists

The lists under Settings → Capture → Species (/station/capture#species; the old /admin/species redirects there) decide which birds the station records at all:

• Exclude — these species are never recorded. Nothing is written to the database, no notification is sent, and nothing is uploaded to BirdWeather. Use it for a persistent local false positive, or for a species you would rather not log.
• Allow — when non-empty, only these species are recorded.
• Always allowed (whitelist) — species the species-occurrence filter would hold back as unlikely for your location and week are recorded anyway. This is BirdNET-Pi’s whitelist_species_list.txt, with its meaning: it exempts a species from the occurrence threshold and from nothing else. A species on the exclude list stays excluded, one missing from a non-empty allow list stays out, and it does nothing on a station with no location set (nothing is held back there). It is for the one or two birds you know visit; lowering the occurrence threshold under Detection is the broader tool.

Enter either the common name or the scientific name; both work, and case and surrounding spaces don’t matter. Changes take effect within about half a minute — no restart. /admin/species/test previews the decision for every species your station has seen, using the same code the detection path runs, so what it shows is what will happen.

An allow list whose entries match no species this model knows is ignored, and a warning is logged, rather than being taken literally and suppressing everything.

Species storage

Settings → Capture → Species → Species storage (/admin/species/manage) is one row per species this station has ever recorded, with its detection count, how many still have audio on disk, how many you have locked, and when it was last heard. It exists for one recurring situation: a squeaky gate has produced four thousand Eurasian Wrens and you want them gone.

Three actions per row, each confirmed:

Locked detections are never touched by any of them. The row shows the locked count before you press anything, and the result tells you how many were kept — so a species you deleted that still has two detections is explained rather than looking like a bug. Unlock those first if you meant to include them.

Measure adds up the species’ clips on disk. It is a separate button rather than a column because it has to stat every file, and doing that for every species on every page load would make the page take many seconds to open on an SD card.

All three actions are written to the audit log.

Species photographs

Each species page shows a photograph, cached on disk so the station works offline after the first fetch. Three sources are available.

Wikipedia (the default) needs no key and covers most species. For a long tail it has no photograph at all, and for many others it has a museum skin, an egg, or a range map rather than a living bird.

AviCommons (IMAGE_PROVIDER=avicommons) needs no key. AviCommons is a library of cropped, oriented Creative Commons bird photographs made to be embedded. It is tried first and Wikipedia fills in behind it. The station downloads AviCommons’ one JSON index (1.6 MB, which its README asks to be fetched once and not on each page load) and keeps it in the image cache folder for 30 days, then each photograph once. Only the CC0, CC BY and CC BY-SA images are used, the same rule as Flickr below: of the index’s 10,185 images (checked 2026-10-21) 2,620 qualify, the rest are NonCommercial. Against the 6,522 species of the BirdNET V2.4 labels that is 1,628 species (25 %) with an AviCommons photograph, and the rest keep Wikipedia’s. Each photograph is shown with its photographer, its licence and a link to AviCommons. The project’s repository declares no licence of its own; the terms are per image, in the index.

Flickr searches Flickr first and falls back to Wikipedia when Flickr has nothing, so turning it on can only add coverage — it never leaves a species blank that Wikipedia could have filled. It needs a free API key from Flickr’s app page:

IMAGE_PROVIDER=flickr
FLICKR_API_KEY=your-key-here

Showing your own photographs

Set FLICKR_FILTER_EMAIL to the email address on your Flickr account and the search is restricted to your own photostream — your pictures of the birds your own station heard. Wikipedia still fills in the species you have not photographed, which is the whole point of the fallback: a filtered stream has a few dozen species in it, not nine thousand.

IMAGE_PROVIDER=flickr
FLICKR_API_KEY=your-key-here
FLICKR_FILTER_EMAIL=you@example.com

Licensing

Only the Creative Commons licences that permit commercial use are requested — CC BY, CC BY-SA, CC BY-ND, CC0, Public Domain Mark, Flickr Commons, and US Government works. Your station’s page may end up published; the station cannot know whether that counts as commercial, so it asks only for photographs where the answer does not matter.

Attribution is not optional under CC BY and CC BY-SA, so every photograph is shown with its photographer’s name and a link to the Flickr page carrying the licence terms. A photograph Flickr returns with no photographer named is skipped rather than shown uncredited.

Notes

• Switching provider does not re-download anything: the cache is keyed on the species name alone, so images already on disk are kept.
• A wrong or revoked API key is reported in the log and the station falls back to Wikipedia rather than showing nothing.
• FLICKR_API_KEY is masked in support bundles, and so is the local part of FLICKR_FILTER_EMAIL (you@example.com becomes ***@example.com) — the domain stays because it is the diagnostic half.
• Neither source is used at all in offline mode, or when the image cache is disabled with an empty IMAGE_CACHE_DIR.

Spectrograms

Two settings under System & Display change how every spectrogram is drawn, and a change shows on the next image, with no restart (the answer is revalidated rather than cached for an hour, so a browser that already has the old picture asks again):

• Spectrogram colours — Viridis (blue to yellow, what earlier versions drew and the default), Magma and Inferno (black to pale or bright yellow), Grey (quiet is black) and Grey, inverted (quiet is white, the look of a printed figure). Louder is always lighter, so the order survives a grey print; a unit test holds CIELAB lightness monotonic for every map. Magma and Inferno are matplotlib’s tables (CC0).
• Spectrogram dynamic range — 60, 80 (the default), 100 or 120 dB. Cells more than this far below the loudest in the clip are drawn as the floor. A smaller range gives more contrast and lets faint calls sink into the background. birdnet-go offers 80, 100 and 120 (dynamicrange); 60 is added here.

There is no gain setting, because the image is stretched between its own quietest and loudest cell, so a gain would change nothing. The live spectrogram on Recordings is drawn by the browser and keeps its own colours.

Your picture on the Today page

BirdNET-Pi’s CUSTOM_IMAGE and CUSTOM_IMAGE_TITLE. Set Today page picture (file) to the full path of a PNG, JPEG, GIF or WebP file and Picture title to its heading, and the Today page shows it between the day strip and the log. A webcam works the same way: something on the station keeps the file current (for example a cron job running ffmpeg -i rtsp://camera/stream -frames:v 1 -y /home/pi/camera/latest.jpg every minute) and the page checks it every ten seconds while the tab is visible, fetching it again only when the file’s size or time changed. BirdNET-Pi re-reads it every second and inlines it; this does one conditional request in ten seconds, which is easier on a Raspberry Pi.

The file is held to what a picture is: a regular file, at most 8 MiB, a PNG, JPEG, GIF or WebP by its first bytes whatever its name says (so a path typed with a slip, or /etc/passwd, shows nothing; SVG is refused because it can carry script). If the file cannot be read the block says so and keeps trying. It is a block like the others: hide or move it under Today Page Layout. Only a file path is supported, as upstream; a camera that only offers a URL needs the snapshot saved to a file first.

This is not custom_image_dir, which replaces one species’ photograph.

Other categories

The Settings sidebar also covers Location, Audio (see Audio & Microphones), Notifications & Email (see Notifications & Integrations), MQTT / Home Assistant, and System.

Data quality

The Quality dashboard (Settings → Data, /station/data#quality; the old /admin/quality redirects there) summarizes the health of your detection database — the confidence distribution, a 30-day confidence trend, an hourly quality profile, and a ranked list of low-confidence species that are good candidates for a stricter per-species threshold.

Species Names in Your Language

BirdNet-Behavior can show bird names in 35 languages besides English. Choose one under Settings → General → System & Display → Common-name language, or set DATABASE_LANG=de in birdnet.conf (--lang de, or BIRDNET_LANG, work too). It takes effect when the station next starts. A --lang given on the command line wins over the Settings page and birdnet.conf, as every flag does, so the page will show the stored choice while the station uses the flag’s.

The name of a language is its code: af, ar, ca, cs, da, de, en, es, et, fi, fr, hr, hu, id, is, it, ja, ko, lt, lv, nl, no, pl, pt, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh_CN and zh_TW. A regional spelling (de_AT, pt-BR) and any capitalisation work. Chinese has no plain zh: its two scripts are two sets of names, and the station will not guess which you meant.

Only what is shown changes

A detection is stored under the name the classifier gave it, in English, and that stays true whatever language you choose. The language decides what is drawn. That is different from BirdNET-Pi, which stores the translated name, and it is deliberate:

• Changing language loses nothing and splits nothing. Last spring’s Eurasian Blackbird and this spring’s Amsel are the same bird in every list, count and chart, and you can switch back tomorrow.
• Your exclusions keep working. A species list that says “Dog” still matches the dog after you switch to German, because the list is matched against the classifier’s names.
• Links, forms, the JSON API, the exports, MQTT and webhooks carry the stored name. A program that matches on Eurasian Blackbird keeps working; a link that said name=Amsel would open a page that has never heard of the bird.

Everything a person reads is translated: the Today feed and its top-species card, the species list, photos and life list, a species’ page, a detection’s page, the recordings and search results, the history and reports, the review queue and quarantine, the dashboard, the kiosk, the share page, the Patterns charts, the RSS and calendar feeds, notifications and the weekly report, and the live feed.

How much of your classifier it covers

The names come from BirdNET-Pi’s translation tables, which cover 7,058 species. The BirdNET V2.4 classifier reports 6,522 and the BirdNET+ V3.0 preview 11,560, and a language does not have a name for every one of them: Swedish names nearly all the species in the tables, Korean fewer than one in ten. A species with no name in your language keeps the classifier’s own, so a station set to Korean shows mostly English.

The language list on the Settings page shows, for your classifier, the share of its species each language names, and birdnet-behavior --doctor prints the same count for the language you have chosen. GET /api/v2/languages returns both.

These names are upstream’s, not reviewed here; a wrong one is upstream’s error. If you want a name different from the one shown, or a language that is not in the list, put a file named de_labels.txt (or fr_labels.txt, and so on) in a directory and point --labels-dir (LABELS_DIR) at it. Each line is Scientific name_Common name, and its names replace the built-in ones for that language.

Searching and typing names

You can type a name in your language into the species search, the command palette (⌘K), the companion-species lookup, and the Today, Recordings and Search boxes. You can also add one to an exclusion or allow list: it is saved as the scientific name, which means the same thing in every language and survives a change of language.

Three things still go by the classifier’s name, because it is the stored name:

• Sort order. “Species A–Z” sorts the classifier’s names, so a German list will not be alphabetical in German.
• An alert rule’s webhook body. {{species}} is the stored name, and {{sci_name}} is the scientific name in every language. (A rule’s pattern matches either: Elster* and Eurasian* both select the magpie on a German station. A notification’s $comname is drawn in your language; its links carry the stored name.)
• Entries typed before this existed. A name typed into a species list used to be saved as typed. A German name saved that way matches nothing, because the classifier never reports it; remove it and add it again, and the scientific name is saved instead.

Fonts

The interface’s own typefaces cover Latin and Latin Extended. A name in another script (Japanese, Korean, Chinese, Thai, Arabic, Cyrillic) is drawn by the browser’s own fonts, which every phone and desktop has. A bare Raspberry Pi kiosk may not: if the wall display shows empty boxes where a name should be, install a font that covers the script (fonts-noto-cjk for Chinese, Japanese and Korean).

Where the names come from

crates/birdnet-core/data/l18n/README.md says whose work they are, under what licence, how many names each language has, and how to rebuild the table. The short version: BirdNET-Pi’s model/l18n/ files at a pinned commit, reduced to the names that are genuine translations, credited to @patlevin and Wikipedia by BirdNET-Pi itself.

Running More Than One Classifier

Your station always runs one classifier — BirdNET, the thing that makes it a BirdNET station. This page is about running a second one beside it, and what the station does with two opinions about the same three seconds of audio.

You do not need this. One classifier is the supported, tested, default configuration, and most stations should stay there. Read on if you are in the tropics, where Google Perch v2 is materially better than BirdNET, or if you want a second opinion recorded on every detection. The first section is about the one classifier every station has: which one a new station gets, and what changing it involves.

Choosing and changing the primary classifier

A new install runs BirdNET V2.4 with its range (occurrence) filter v2, the network BirdNET-Pi and birdnet-go run; BirdNET+ V3.0 preview (a different network, with its own geomodel as the occurrence filter) is an explicit choice. The two are never mixed: the V2.4 range filter is indexed like the V2.4 labels and means nothing to another network, and the geomodel is matched by name through its own label file.

On bare metal the rule, first match: an existing config keeps the classifier it names (only a config whose MODEL_PATH is the V2.4 file the installer manages counts as V2.4; every other existing config is treated as V3.0, because that is what every earlier install fetched); otherwise --classifier, then BIRDNET_CLASSIFIER; otherwise, if the V3.0 model file is already in the model folder (a station restored from a backup of its data without its config), V3.0; otherwise V2.4. One Classifier: line in the install output says which was chosen and why. Installation and Running with Docker have the details and say where the files come from.

Changing a running station is deliberate, never automatic. No install, update, repair or reinstall does it, because the history would then hold rows two different networks scored. Rows already stored keep their old scores and names, and a species the two label files name differently appears under both names. If you do want to change:

1. Install the other classifier’s files (see Installing one below).

2. Point the station at them in its configuration, then restart and run birdnet-behavior --doctor. Moving to V2.4:

   MODEL_PATH=<model dir>/birdnet-v24.onnx
   LABELS_PATH=<model dir>/birdnet-v24_labels.txt
   METADATA_MODEL_PATH=<model dir>/birdnet-v24-range-v2.onnx
   # no METADATA_LABELS_PATH: the range filter needs none, so remove a geomodel's label file from here
   

   with CONFIDENCE, SENSITIVITY and PRIVACY_RANK as Same audio, same detections describes. In Docker, set BIRDNET_CLASSIFIER=birdnet-v24 instead and recreate the container.

3. Moving the other way (V2.4 to V3.0) has no one-line recipe here: the V3.0 files and their pins are named in installer/lib/10-config.sh, and install.sh --classifier birdnet-v3 is only for a new station. In Docker, BIRDNET_CLASSIFIER=birdnet-v3 is enough.

These steps were read from the installer and the container entrypoint and their tests, not run end to end on a station.

What a second classifier buys, and what it costs

Every classifier routed to a recording runs on every chunk of it. Two classifiers mean two inferences per chunk, which on a Raspberry Pi is the expensive part of the whole pipeline. In exchange:

• A species only one of the two models knows is now heard. The results are a union, not an intersection.
• Each detection records which classifier produced it, and how many classifiers reported that species in that chunk.
• Nothing is lost. A model that reports a species alone still produces a detection.

The cost is real and worth measuring before you commit to it: check the daemon’s CPU use for a day with one classifier, then compare.

Installing one

The station carries a small catalogue of classifiers it knows how to fetch and verify. The default one (BirdNET V2.4 and its local species filter) can be installed from the browser: Settings → Capture → Bird-identifying model → Install, or step 2 of the setup wizard. The others below are installed from the command line. To see the catalogue:

birdnet-behavior --install-model list

To install one:

# Docker: BIRDNET_MODEL_DIR is already /data/model in the container
docker compose exec birdnet birdnet-behavior --install-model perch-v2

# Bare metal: the installer's model folder is <data dir>/models, but --install-model
# writes to /data/model unless BIRDNET_MODEL_DIR (or MODEL_DIR in birdnet.conf) says
# otherwise. Name the folder, and run as the service user, who owns it:
SVC=$(systemctl show -p User --value birdnet-behavior)
sudo -u "$SVC" env BIRDNET_MODEL_DIR="$(getent passwd "$SVC" | cut -d: -f6)/BirdNet-Behavior/models" \
    birdnet-behavior --install-model perch-v2

There is no birdnet user on a bare-metal station: the installer runs the service as the account that ran sudo, and systemctl show -p User --value birdnet-behavior prints it.

What it can install:

The installers do this for you on a new station (V2.4 and its range filter). To make an older station report what BirdNET-Pi would, install birdnet-v24 and birdnet-v24-range-v2 and follow Same audio, same detections.

This runs in the foreground and exits — deliberately. It is a several-hundred-megabyte download that takes hours on the uplink a field station has, and you should be able to watch it, interrupt it, and see it fail. There is no button in the web interface for the same reason: a multi-hour download inside a request handler has nowhere to report progress, and a retry would start a second download beside the first.

Three things it does before and while it downloads:

• Checks free space first, with a 512 MiB margin on top of the file. Filling the card stops the station recording, which is worse than not having the classifier. A filesystem that will not say how much space it has counts as no space rather than plenty.
• Verifies as the bytes arrive. The sha256 of each file is compiled into the binary — not fetched alongside it — so the checksum is a promise this project makes rather than one the download site makes. The digest is computed while streaming, so a 541 MB model never has to fit in a 1 GB board’s memory at once.
• Never leaves a half-file the station would load. Unverified bytes carry a .part name; the file is renamed into place only after its digest matches.

Running it again is cheap: a file already in place whose sha256 matches is not fetched again (the command says so, and skips the free-space check for it), while a truncated or substituted file under the right name is fetched afresh. A download that is interrupted starts over; it does not resume.

Files land in the folder named by BIRDNET_MODEL_DIR, else MODEL_DIR in the config file, else /data/model. The same catalogue is readable over the API at GET /api/v2/models/catalog.

Where the files come from. birdnet-v3 and the Perch model are fetched from the URLs in the catalogue; birdnet-v24 is the model from birdnet-go’s published ONNX build on Hugging Face at a pinned revision, and birdnet-v24-range-v2 the range filter from the tphakala/birdnet-go repository at a pinned commit. The V2.4 labels are not downloaded: the binary writes birdnet-v24_labels.txt itself, verified against a digest, with BirdNET-Pi’s English names on V2.4’s class order. birdnet-go’s own label file, which the model is published with, names 460 of the 6 522 classes differently from BirdNET-Pi (Pica pica is “Eurasian Magpie” in one and “Common Magpie” in the other), and a station that imported a BirdNET-Pi history would otherwise hold one species under two names. A station that already has the older label file keeps it, because the installers skip a file that is present; run birdnet-behavior --install-model birdnet-v24 yourself to replace it (the labels are always rewritten from the binary, the model that already verifies is not fetched again), then restart. The three files a V2.4 station has are birdnet-v24.onnx, birdnet-v24_labels.txt and birdnet-v24-range-v2.onnx.

Perch v2 ships without a labels file. You must supply one with 14 795 rows. Labels are positional against a model’s output, so the wrong file reports species under other species’ names at full confidence — a failure with no symptom at all.

Configuring it

Up to three classifiers total. The primary is always loaded and is whatever BIRDNET_MODEL / BIRDNET_LABELS already point at.

# Name the primary, if you want it called something other than `birdnet`
# in routes and on detections.
MODEL_ID=birdnet
MODEL_THRESHOLD=
MODEL_SAMPLE_RATE=

# The second classifier. Each needs its OWN labels file. (<model dir> is
# /data/model in Docker and <data dir>/models on bare metal.)
MODEL_2_PATH=<model dir>/perch-v2.onnx
MODEL_2_LABELS=<model dir>/perch_labels.csv
MODEL_2_ID=perch
MODEL_2_THRESHOLD=0.35
MODEL_2_SAMPLE_RATE=32000

# A third, if you have one.
MODEL_3_PATH=
MODEL_3_LABELS=
MODEL_3_ID=
MODEL_3_THRESHOLD=
MODEL_3_SAMPLE_RATE=

Every key also exists as BIRDNET_MODEL_2_PATH and so on in the environment; see .env.example.

MODEL_n_SAMPLE_RATE is not optional for Perch. Its tensor declares [-1, 160000], which is 5 s at 32 kHz and equally 3⅓ s at 48 kHz — nothing in the shape distinguishes them, so it has to be told. BirdNET’s own shapes are unambiguous, and the station derives those for itself.

MODEL_n_THRESHOLD (and MODEL_THRESHOLD for the primary) holds that classifier’s detections to its own confidence bar, whether it is below the station’s or above it. Leave it unset to use the station’s. A per-species threshold still overrides either.

Routing sources to classifiers

A second classifier runs only where a route sends it: every audio source is judged by the primary alone unless MODEL_ROUTES names it. That is deliberate — adding a classifier should not quietly double the inference cost of every microphone on a board that was keeping up. To send particular microphones to particular classifiers:

MODEL_ROUTES=pond:perch,garden:birdnet+perch

The source is its audio_sources row id — the same label GET /api/v2/system/capture lists, and the one each source’s recordings carry in their file names, which is how the detection loop knows where a recording came from. To run both classifiers on your only microphone, name that microphone’s id: MODEL_ROUTES=<id>:birdnet+perch. That needs the microphone to be listed on the Audio page, which is what gives it an id; a single microphone set only in birdnet.conf records without one, and gets the primary alone. Use + for more than one classifier on one source, and commas between sources.

Two rules here exist because a station runs unattended for months:

• A source you do not name gets the primary classifier, never nothing. Silence must not be reachable by forgetting to write a line.
• A route naming a classifier you have not configured stops the station at startup, where the journal and --doctor will show it. Accepting pond:pecrh and discovering at runtime that the pond routes to nothing would cost months of recordings from that microphone, and the station would look identical to one having a quiet season.

What the station does with two opinions

Each classifier is judged against its own threshold, and the results are combined per chunk:

• Union by species. Anything any classifier reported above its threshold becomes a detection.
• The highest confidence wins, and the detection records which classifier gave it (model_id).
• model_agreement counts how many distinct classifiers reported that species in that chunk.

Agreement is never folded into the confidence. An averaged or bonused number would have no calibration behind it while sitting in the same column as a real one, quietly changing the meaning of every threshold you have set and every historical comparison you make. The confidence you see is the winning classifier’s own output, unchanged.

model_agreement is NULL on rows written before this feature existed — a third state, and not the same as 1 (“one classifier asked, one answered”).

Both columns are stored on every detection today, and nothing in the web interface or the API reads them back yet. They are there so that a station running two classifiers now is not analysing a season of data later with the corroboration missing.

Windows: what “the same chunk” means

Classifiers do not agree on how much audio a judgement covers. BirdNET+ V3.0 wants 4.5 s; Perch v2 wants 5.0 s.

The station cuts each chunk to the longest window any loaded classifier wants, and advances by the shortest. Each classifier reads its own window from the start of the shared chunk.

The reason it is not simply “cut and step by the longest” is a gap you would never see. Cut at 5.0 s and step 5.0 s, and BirdNET hears the first 4.5 s of every chunk and never the last half-second — audio no classifier is ever given, recurring on every chunk for as long as the station runs, producing no error and no missing-data indicator. The detections that would have been there simply are not there.

Stepping by the shortest window removes it. The shortest-window classifier gets exactly the chunks it would have had running alone, and longer-window classifiers get overlapping chunks instead of gaps.

What this costs, so you can decide: a classifier whose window is longer than the shortest runs longest ÷ shortest more inferences — 5.0 ÷ 4.5 ≈ 1.11, about 11 % more for Perch beside BirdNET. The daemon logs it at startup as extra_inference_ratio alongside both window lengths, so you do not have to work it out:

classifiers want different windows: chunking to the longest and stepping by the
shortest ... longest_window_secs=5.0 shortest_window_secs=4.5
extra_inference_ratio=1.1111112

One consequence worth knowing when you read detection times: a detection carries the chunk’s span, not its own classifier’s. A shorter-window classifier’s detection can therefore show an end time up to half a second later than the audio it actually read. The recorded span always contains that audio, so a clip cut from it contains the detection. With one classifier the two are identical.

What the station refuses, and why

A different sample rate. Every classifier must want audio at the same rate. A recording is decoded and resampled once; resampling it twice would double the most expensive step in the pipeline on the boards this runs on, and there is no rate that is correct for both. The station says so at startup and names both rates rather than starting and feeding one of them audio prepared for the other. Differing window lengths are fine — that is what the chunking above is for.

More classifiers than the machine can hold. All classifiers together may use at most half the machine’s effective memory ceiling — the cgroup limit if there is one, otherwise physical memory — counting each model’s file size plus a 256 MiB working-set allowance. On a 1 GB board that budget is 512 MiB, which one BirdNET model already fills, so a second is skipped and the arithmetic goes in the journal. A machine that will not report its memory gets one classifier, because “unknown” must not be read as “plenty”.

Nothing at all. A station with no classifier is not a degraded station; it is a station that has stopped being what it is for. Startup refuses it.

Not yet supported

Bat classification. BattyBirdNET is not a peer classifier — it is a chained second stage that consumes BirdNET v2.4 embeddings and needs 256 kHz audio fed through without resampling. That needs a capture path, a deliberate no-resample route, BirdNET v2.4’s 1024-wide embedding output (the birdnet-v24 classifier here emits species scores, not embeddings), and the ultrasonic validation filter, none of which ship yet.

See also

• Settings & Detection — thresholds, sensitivity and the rest of the detection knobs
• Tuning Detection Accuracy — what to change before reaching for a second model
• Audio & Microphones — the sources MODEL_ROUTES names

Audio & Microphones

Microphone setup is the single most common support topic, so it gets its own tab (Settings → Capture, /station/capture; the old /admin/audio redirects there) designed to be bulletproof.

Your sources at a glance

Every input the station listens on appears in the source list — USB sound cards and RTSP cameras alike. Each row shows a live level meter with SNR, uptime, the last detection, and a 24-hour count, so you can tell at a glance whether a mic is healthy.

You can run several sources at once — one or more USB/ALSA mics, a PipeWire source, and any number of RTSP streams, in any combination (this is the headline gap in the original BirdNET-Pi). Each source captures into its own subprocess, tags its recordings with its own stream label, and gets its own health gauge, so detections stay attributable to the source that heard them.

Independent supervision (built for the field)

Every source is supervised on its own, which is what makes a multi-camera station survivable when nobody is on site:

• One source failing never disturbs the others. A dead capture process — a camera that rebooted, a mic that was unplugged, a network blip — is restarted on its own with capped exponential backoff (2 s → 4 s → … → 60 s, then every 60 s forever; a source down for an hour is still recording when it comes back on hour two). The other sources keep recording and detection never pauses.
• Silent stalls are caught too. A source whose process is still alive but has stopped delivering audio — a wedged RTSP session, a mic hung after a USB re-enumeration — is detected by watching its segment output: no fresh recording for several segment-durations and it is restarted exactly like a crash. A plain “is the process running?” check can’t see this; it’s the failure mode that quietly loses a whole night otherwise. (It fails open while the system clock is unsynced, so a wrong boot-time clock never triggers a false restart.)
• A source that keeps dying and coming back is caught as well. A marginal USB connection or an under-powered hub gives a source that dies every few minutes and restarts in seconds: it is live at every glance, its backoff never grows, and its uptime strip stays green, but every restart loses the audio around it. Restarts are counted over the last hour, and five or more make the source flapping: a line on its Station Health card, an issue in the banner, a warning in the log, and the flapping station-health condition for the notifier.
• You can see it. The per-source birdnet_audio_source_up{source="…"} Prometheus gauge reflects real liveness, and a source that has been down a couple of minutes logs a loud, rate-limited warning to the journal.
• You can say which source Listen plays. Each row carries Make listen default; the source you pick is what /stream serves — and so what the Listen button plays — when the listener has not chosen one of their own. A two-microphone station (feeder and nest box) has one that people actually want to hear, and this is where it says so. If that source is later disabled or removed, Listen falls back to the first working source rather than going silent.
• You can restart one source by hand. Each row carries a Restart button that stops and starts that source alone, within a couple of seconds; every other source keeps recording, and nothing in flight elsewhere is lost. It is the right remedy for one camera that has wedged in a way the supervisor has not yet called stalled. Restarts you ask for are deliberately not counted towards the flapping verdict — that number is there to spot a source failing on its own. The same action is POST /api/v2/control/restart-source for automation, and GET /api/v2/system/capture reads the state back; both are in the API reference. Note that a per-source restart re-launches the source with the settings the service started with — it does not pick up an edit, which still needs a service restart.

Tuning the watchdog (expert)

The supervisor’s own timings are settable, and the defaults are what the station has always used — leave them alone unless a specific site misbehaves. The knobs are BIRDNET_WATCHDOG_CHECK_SECS (how often every source is reconciled), …_STALL_SEGMENTS and …_STALL_FLOOR_SECS (how much missing output makes a live process stalled), …_BACKOFF_BASE_SECS and …_BACKOFF_CAP_SECS (the restart delay and its ceiling), and …_DOWN_WARN_AFTER_SECS and …_DOWN_WARN_EVERY_SECS (how long down before the loud journal warning, and how often to repeat it). Each is documented with its range in .env.example; a value outside it is clamped and the adjustment is logged, so a station never runs on timings its config file does not describe.

Two things that are deliberately not knobs:

• There is no maximum retry count. A field sensor unreachable for six hours must still be reachable on hour seven, and a supervisor that has given up is a station that is silently not recording. Upstream BirdNET-Go has one; this is a considered divergence, not an omission.
• None of these is “how long may the station go without a detection”. That is BIRDNET_DEADMAN_HOURS. A microphone writes segments through hours of silence, so no amount of quiet trips the stall threshold — the threshold is about segments arriving, not about birds calling.

Tuning a source

Open a source’s edit panel to change:

• Label and device,
• Quiet window — an optional per-source pause in the station’s local time, each end a clock time (22:00) or a solar anchor (sunset, sunset+30, sunrise-15), e.g. to silence a noisy road-facing mic during rush hour without touching the others. (Earlier releases evaluated it in UTC; if you set the hours to compensate for that, set them back to the local hours you actually want. The source row shows the window with a local suffix so you can tell which convention a station is on.)
• Pipeline toggles — high-pass filter, DC-offset removal, auto-gain control, and (network streams only) a 10-second read timeout that ends a stream which stops sending, so it is restarted.
• Equaliser — a filter chain of your own, when the toggles are not the right shape. See below.
• Camera stream (RTSP sources only) — the transport (auto / TCP / UDP — auto is TCP, the NAT-robust choice; force UDP only for a camera that needs it) and the tracks requested (see Audio-only cameras).

Sample rate (48 or 44.1 kHz) is chosen when the source is added. Per-source gain, the channel pick (mono / left / right / stereo — see Stereo microphones below) and bit depth are stored with the source and shown in its detail line, but are not yet editable from the UI; capture honours whatever the audio_sources row holds.

Per-source settings (device, gain, sample rate, transport, quiet window) are read when the capture subsystem starts, so restart the service after changing them for the change to take effect.

Aim for peaks near −6 dB. Gain set too high clips the loudest calls and hurts identification more than a quiet signal does.

The equaliser

The high-pass and DC offset toggles are two fixed filters: a corner at 120 Hz and one at 5 Hz. That is a reasonable compromise for a garden and the wrong answer at plenty of sites. A station beside a motorway wants a steeper cut than one filter section gives. A station with mains hum wants a notch at 50 or 60 Hz — a high-pass cannot remove hum without also removing everything below it, including the low end of a grouse, a bittern or an owl.

The Equaliser field takes a chain of filter stages. Type one and the response curve under the box redraws as you type, computed from the same coefficients that will filter your audio — so the picture cannot disagree with what you will hear.

Writing a chain

One stage per ;. Each stage is:

kind : frequency [ : q [ : gain [ : passes ] ] ]

• frequency is in hertz, and must be below half your source’s sample rate. A 48 kHz source can filter up to 24 kHz; a 16 kHz source only to 8 kHz. The form refuses a chain the source cannot carry rather than accepting it and silently ignoring it later.
• q is the width. 0.707 (the default) is the gentlest useful shape. Higher is narrower: 20 is a hum notch, 1 is a broad tone control.
• gain is in decibels, positive to boost, negative to cut. Ignored by the kinds that do not use it.
• passes repeats the stage, doubling its slope each time. highpass:120:0.707:0:2 is twice as steep as highpass:120.

Worked examples

What a chain replaces

A non-empty chain replaces the high-pass and DC-offset toggles. It does not stack on top of them, so a chain with your own 120 Hz corner gives you one filter, not two. Automatic gain control is unaffected either way: it is a dynamic-range process, not a filter.

Clear the field to go back to the toggles.

One thing worth knowing about the toggles

The two backends do not implement the high-pass toggle identically. A local microphone gets a one-pole filter (6 dB/octave); an RTSP camera gets ffmpeg’s two-pole one (12 dB/octave). From the same tick-box, a microphone therefore keeps considerably more low-frequency energy:

This is left as it is because changing either filter would change what every existing station of that kind records. Writing an explicit chain is how you get the two to agree — a chain is rendered for both backends from the one specification, so a microphone and a camera given the same chain are filtered the same way.

Like the other per-source settings, the chain is read when capture starts — restart the service after changing it.

Stereo microphones and the Channels setting

The BirdNET model takes one channel, so a stereo microphone’s two channels have to become one before inference. On mono — the default — that reduction is a plain average of the two.

For two capsules in the same spot that is harmless. For two capsules a few centimetres apart it is a comb filter: the same wavefront reaches them at slightly different times, and averaging then cancels every frequency where the two arrive out of phase. Measured through this project’s own decode path, a half period of delay costs about 66 dB — the signal essentially disappears — while a quarter period costs 3 dB and a full period costs nothing. Which case a given station sits in depends on the capsule spacing and on where the bird is, so it cannot be answered from a datasheet.

There is a command that answers it on your hardware, in your acoustics:

sudo systemctl stop birdnet-behavior     # an ALSA capture device is exclusive
birdnet-behavior --channel-report        # add --channel-report-secs 15 for a steadier read
sudo systemctl start birdnet-behavior

It records a few seconds, then prints each channel’s level, the inter-channel delay and the capsule spacing that implies, and what Mono / Left / Right would each hand the model. Run it while birds are actually singing: the cancellation is direction-dependent, so ambient noise alone can look benign on a microphone that loses badly on real song.

Act on the answer by setting the source’s channel pick — left or right takes one capsule intact instead of averaging two. There is not yet a UI control for it: set the channels column of the source’s audio_sources row (mono / left / right / stereo) directly and restart the service.

This matters most for exactly the deployments that can least afford it: a sealed enclosure nobody opens for a season. A station losing 66 dB to its own downmix looks completely healthy from every gauge, dashboard and alert this project has.

Adding a camera or stream

Under Cameras and streams, Add stream opens a short form: the stream’s URL, a friendly label, and — for an RTSP camera — its transport and the tracks to request. Saving adds the row; restart for capture to pick it up.

The URL decides the protocol:

Credentials go where the protocol puts them — user:pass@host in the address, an SRT passphrase=, a token= in a signed URL. The station hides all three in its logs and support bundle. A URL that starts any other way is refused when you save it, with the list above, rather than saved and left to fail at every restart.

Where the credentials are visible. ffmpeg 6.1 takes its input address as an argument (-i), and RTSP takes its user and password only from that address, so the station passes the whole address, credentials included. Anyone who can list processes on the host sees rtsp://user:pass@camera/… in ps or /proc/<pid>/cmdline while the stream runs. On a station where you are the only user that is nothing; on a shared host, give the station a camera account that can only read the stream, or mount /proc with hidepid=2 so users see only their own processes. The Docker image shows it only inside the container.

There is a way round it that the station does not use yet. ffmpeg’s concat demuxer reads its list from a file, and opens each file in it as an input of its own, RTSP included, with the options on the lines after it. Checked on ffmpeg 6.1.1 against a small RTSP server that answers 401 until it gets the right Basic credentials (tools/rtsp-probe/rtsp_auth_server.py): the camera accepted the credentials, the audio was byte for byte what the direct command captured (32,320 bytes both ways), and /proc/<pid>/cmdline held the path of the list file and no password. What stops it being the default is the work around it: the file has to be written mode 0600 in a private directory for every start and removed after it, the stall and transport options move into option lines, the same change has to reach the live view, the HLS stream and the source probe, which each open the address themselves, and none of it has run against a real camera. See docs/TECH_DEBT.md, TD-5.

rtp:// is not on the list. A bare RTP stream does not say what it carries: ffmpeg reads one carrying G.711, but not one carrying AAC, which needs a description file it has no way to be given. Send MPEG-TS over udp:// instead.

Every protocol was checked end to end against a MediaMTX 1.21.2 server and ffmpeg 6.1 — each recorded its own test tone — and against a stalled server: a source whose server stops answering is restarted on its own, and resumes when the server does. Two things differ from a camera:

• A UDP stream has no live audio. A UDP stream reaches one reader, and the station’s capture is it, so the Live view lists it as spectrogram only, and /stream answers 503 with that reason.
• An HLS stream is slow to notice a stall. Its player retries the playlist before giving up, so a server that stops answering was noticed after 52 seconds, where the others took 5 to 20.

Stream capture needs ffmpeg on the host. The bare-metal installer installs it automatically when your config has an RTSP_URL (re-run sudo bash install.sh repair if you add a stream later), and the Docker image already bundles it. Without ffmpeg, these sources record nothing.

Audio-only cameras

A camera serves only a few video viewers at once. By default the station asks for every track the camera offers and throws the video away, which takes one of those slots for as long as it listens, and another whenever someone listens live from the dashboard. On a camera with few slots that can leave its own app unable to show the picture.

Set Tracks requested to audio track only and the station sets up the audio track alone (ffmpeg’s -allowed_media_types audio), for capture and for listening live. Checked against MediaMTX 1.21.2: the station’s session took one track instead of two.

The default stays audio and video, because a camera that sends no audio then fails visibly: the source shows as down, and the log names the camera’s refusal (for example method PLAY failed: 501 Not Implemented). If that happens after switching to audio-only, switch back.

Finding a USB mic

arecord -l
# card 1: PRO [Comica_Traxshot PRO], device 0: USB Audio [USB Audio]
#      ^ index                ^ id
arecord -D plughw:CARD=PRO,DEV=0 -d 3 /tmp/test.wav && aplay /tmp/test.wav

Set the device in .env (BIRDNET_ALSA_DEVICE=…) or via the CLI flag — see Configuration.

Name the card, don’t number it

A card index (the 1 in plughw:1,0) is assigned in detection order and is not stable. It changes when USB devices are re-enumerated, and a reboot is free to do that.

This is not hypothetical. During an on-device acceptance run, the same microphone on the same Raspberry Pi 4 was card 1: PRO before a cold reboot and card 3: PRO afterwards. The station came back up, served a perfectly healthy dashboard, and recorded nothing — the capture supervisor retried a device that no longer existed, indefinitely. Nothing was broken except a number.

The id (PRO above) does not move. Address the card by it:

ALSA_CARD=plughw:CARD=PRO,DEV=0

CARD is a first-class ALSA argument, not a trick: alsa-lib’s own alsa.conf declares pcm.plughw { @args [ CARD DEV SUBDEV ] } with @args.CARD { type string }. A fresh install now writes this form automatically when it can, and falls back to the index only when the id would be ambiguous — two identical microphones report the same id, and then only the index can tell them apart.

After editing the config, apply it with sudo bash install.sh repair.

A station still addressing its card by index is told so twice. --doctor grades a resolving index as an advisory naming the exact CARD= form for the card it resolved to (an absent index was already a warning). And at every start the station writes the id it finds behind each index-form device into its boot journal and compares it with the last start: if plughw:1,0 was PRO then and is something else now, that is the audio_card_moved boot anomaly, which reaches /api/v2/health, the station-health notification, and the log as an error, because the station is recording from a different device than it was set up with.

Pinning your own names (recommended for multi-mic stations)

The id comes from the device’s own firmware, so two identical microphones give you two cards called PRO. usb-audio-mapper solves this properly: it writes a udev rule keyed on vendor/product and USB port path, setting ATTR{id} to a name you choose.

sudo ./usb-audio-mapper.sh          # interactive; reboot when it asks
arecord -l                          # now shows your chosen name as the id

Then set ALSA_CARD=plughw:CARD=<your-name>,DEV=0. The name survives reboots, re-plugging, and swapping identical devices between ports — which is the only way to keep several microphones straight on one station.

--doctor validates either form and, if the configured card is missing, names the card that is present and prints the exact line to set.

Listening live

The Recordings → Live view (/recordings?view=live; the old /listen redirects there) plays whatever the station is recording right now. It does not open the microphone itself — an ALSA capture device only allows one opener, so anything that tried would be refused with Device or resource busy for as long as recording was in progress, which on a working station is always. Instead, capture publishes the audio it is already writing to disk, and the live stream is a second reader of that.

Two things follow from this that are worth knowing:

• Live audio is exactly what the detector hears, including any per-source gain you have set. If the live stream sounds clipped, so does the audio being classified.
• Live audio follows capture. If a source is paused — outside the recording schedule, or inside its quiet window — or is down, the Live tab reports that the source is not recording rather than playing silence. Station Health will say why.

The source picker on the Live view chooses what you hear. What everyone else hears when they arrive without choosing — and what /stream serves with no ?source_id= — is the station’s listen default, set with the Make listen default button on a source’s row on this page. Unset, the first working source serves, which is the whole story on a one-microphone station. If the chosen source is later disabled or removed, the stream falls back to the first working source rather than going silent; the journal says so when it does.

Live audio still needs ffmpeg installed: the station uses it to encode the stream for the browser. --doctor warns if it is missing.

On a phone, Live uses HLS. The MP3 stream is one long download, and a phone that moves from Wi-Fi to mobile data ends it for good: the tab goes silent and stays so. Where the browser plays HLS itself — Safari, iOS and Android Chrome — the Live view asks the station for an HLS stream instead: a short playlist of two-second AAC segments that the player keeps refetching, so it rides out a handover. It starts a few seconds slower than MP3, because the station waits for two segments before answering. Desktop browsers without native HLS keep the MP3 stream, and so does any browser whose HLS start the station refuses.

Everyone listening to one source at one pitch shares one encoder, and HLS streams count against the same four live-stream slots as MP3. A stream stops when its last listener leaves, or a minute after nothing has fetched it, and its segments — kept in the service’s private temporary directory — are deleted with it. The API is in the REST API reference.

If you cannot hear the high notes

Age-related hearing loss takes the top of the range first, and a great deal of warbler, kinglet and treecreeper song lives above 8 kHz — where a station can hear it perfectly well and its owner cannot.

The pitch control beside the Listen button on /recordings shifts the live audio down, into a band that still works. Choose one of the downward presets, and your choice is remembered in that browser: hearing is a property of a person, so two people listening to the same station at the same time each get their own setting. (There is also one upward option, which is what you want for bat calls rather than for hearing loss.)

Changing the pitch reconnects the stream — the shift is applied by the encoder on the station, not in your browser — so expect about a second of silence.

For saved clips the equivalent is --freq-shift-hz (BIRDNET_FREQ_SHIFT_HZ, config key FREQ_SHIFT), applied when the clip is written. The same rule applies: negative shifts down and is the direction that helps; a typical value is -3000.

It is a shift in hertz, not a ratio. Every frequency moves by the number you give: with -3000, an 8 kHz song is heard at 5 kHz, and the clip’s length is unchanged. Both the live stream and saved clips do this with ffmpeg’s afreqshift filter, which needs ffmpeg 4.3 or newer. If the ffmpeg on the station lacks it, a saved clip is kept unshifted and a warning says so; there is no other tool to fall back on (sox cannot shift by an amount of hertz). A shifted clip still carries its species, confidence and date tags. (Releases up to v0.17.1 scaled frequencies by a ratio instead, so -3000 turned 8 kHz into 7.5 kHz and slowed the clip by 6.7 %, measured with ffmpeg 6.1.1 on an 8 kHz tone, while this page said otherwise.)

Releases before this one documented that setting backwards, saying a positive value helped high-frequency hearing loss. It does the opposite. If you set a positive value on that advice, negate it.

Evening out the level of saved clips

Clips are written at whatever level the microphone delivered, and a gallery of them recorded across a season is not level: the listener rides the volume control between every one, and a quiet clip at the end of a playlist gets missed. Settings → Capture → Audio Capture → Even out clip volume fixes that. It measures each saved clip’s integrated loudness (ITU-R BS.1770, the measurement behind EBU R128) and applies a single gain.

Off by default, because a clip is an archival record as well as something to listen to and changing what is in it should be your decision. The choices are −14 LUFS (loud, the streaming convention), −18 LUFS (recommended) and −23 LUFS (the EBU R128 broadcast reference, noticeably quiet on a phone). BIRDNET_CLIP_TARGET_LUFS sets the same thing from the environment, and wins over the settings page when both are set.

Four things worth knowing:

• It never touches the audio the classifier hears. The gain is applied when the clip is written, long after the analysis window has been scored. A gain applied before inference would move every confidence score and make two stations’ thresholds mean different things.
• A quiet, peaky clip will not reach the target. One loud wing-beat over a distant song cannot be brought up by a single gain without a sample clipping, so the clip is turned up only as far as the ceiling allows and no further — BIRDNET_CLIP_PEAK_CEILING_DBFS, −1 dBFS by default.
• That ceiling is a sample peak, not an ITU true peak. The station does not oversample to find inter-sample peaks; the default leaves about a decibel of headroom for them, which is the usual allowance for ordinary material.
• The clip says what was done to it. A normalised WAV’s RIFF INFO comment carries Normalised to -18.0 LUFS from -31.4, so the change is visible from the file rather than only from the setting. Re-normalising is a no-op: measuring an already-normalised clip returns the target.

Common pitfalls

• USB hubs can drop audio under load — prefer a direct port on the Pi.
• RTSP over UDP drops packets on busy Wi-Fi — leave the per-source transport on auto (TCP) for stability; only force udp for a camera that requires it.

Recording & Retention

How audio is captured, segmented, and eventually purged.

Capture & segmentation

Incoming audio is split into fixed-length segments before inference. Two settings shape this:

Recording schedule

By default the station listens all day. To record only during chosen windows, set a schedule:

BIRDNET_RECORDING_SCHEDULE=all-day      # default

The same choice is on Settings → Capture → Location & Recording Schedule. Set the variable only to pin it: an environment variable wins over the settings page, which then shows your choice while the station runs this one.

The schedule is all-day, solar (sunrise to sunset, from your location) or fixed:HH:MM-HH:MM (UTC). The Settings page and PUT /api/v2/settings refuse anything else, and a fixed window that does not end after it starts: the scheduler cannot express one that crosses midnight, so it would be ignored and the station would record all day. A RECORDING_SCHEDULE like that in birdnet.conf is a --doctor warning, not a refusal. The clip format (wav, mp3, flac, ogg) and the species-info site (ebird, allaboutbirds, none) are held to the same lists --doctor uses for the config file.

Why there is no Opus or AAC clip format (birdnet-go has both). Measured on 2026-10-21 with the project’s own decoder on a 3 s clip encoded four ways: WAV and Ogg Vorbis decode; Opus fails with “unsupported audio codec” and AAC in an .m4a with “no suitable format reader found”. The spectrogram decodes the stored clip with that decoder, and the recording-file parser accepts only wav, flac and mp3 names, so an Opus or AAC clip would have no spectrogram until the decoder gained an ffmpeg fallback (symphonia has no Opus decoder at all). The encoders are there (ffmpeg 6.1.1 on Ubuntu lists libopus and aac; the Docker image installs that ffmpeg; Fedora’s ffmpeg-free was not checked), but a lossy clip format that the rest of the station cannot read is worse than the three it has. Ogg Vorbis already gives a small lossy clip.

The scheduler computes sunrise and sunset from your latitude/longitude, so schedules can be anchored to solar events (e.g. the dawn-chorus window) rather than fixed clock times. This is also what powers the day/night cues in the dashboard and the kiosk night mode.

Set your location accurately — sunrise/sunset, the species-frequency filter, and any solar-anchored schedule all depend on it.

Privacy threshold

BIRDNET_PRIVACY_THRESHOLD (default 0.0, disabled) discards every analysis window in which the model’s confidence for a human class (speech, whistling, other human sounds) reaches the value, and the windows either side of it, so casual conversation near the mic isn’t written to disk. The confidence is read from the model’s output before the detection threshold applies, so the setting binds on its own: changing the detection threshold does not change what the privacy filter does. Lower values suppress more. 0.02 is a usual starting point; lower it (towards 0.01) if the microphone is near a patio or path, and raise it if birdsong is being suppressed.

A saved clip is longer than the window it was detected in (see EXTRACTION_LENGTH and PRE_CAPTURE_SECS), so the filter also drops any detection whose clip would reach a window where it heard a voice, however many windows away that is. And while the filter is on, a clip is cut from its own recording segment only, never extended into the segment before or after: the filter judges each segment on its own, so it cannot vouch for a neighbour’s audio. A detection within a second or two of a segment’s start or end therefore gets a shorter clip.

Retention — how clips are purged

Retention is disk-based by default, with an optional age limit on top:

• Keep Clip Audio (days) (BIRDNET_CLIP_RETENTION_DAYS, --clip-retention-days, default 0 = keep for ever) reclaims the audio of detections older than N days.
• The disk manager purges the oldest recordings once the disk crosses DISK_PURGE_THRESHOLD (default 95%, in birdnet.conf).
• At most BIRDNET_MAX_FILES_PER_SPECIES (--max-files-per-species, default 0 = unlimited) clips are kept per species.
• Locked clips are never purged — lock anything you want to keep permanently from the Today page or a species’ recordings.

The detection rows in the database are kept regardless; purging only removes the audio files, not the history. Once a day the station also reconciles the database with the recordings folder: a detection whose clip is no longer on disk, whatever removed it, is marked as pruned so its play button goes away, and any half-written .part file older than an hour is removed. The count reaches the log and the birdnet_orphaned_clips metric. The storage breakdown on the Backups page shows how much space recordings are using.

Notifications & Integrations

BirdNet-Behavior can tell the rest of your world when a bird shows up — from a Telegram ping to a Home Assistant entity.

Notification center

The Notifications page (/notifications) shows your channels and a log of recent events, with per-channel send counts, delivery status, and the last-sent time.

Channels

• Direct push — paste one or more notification URLs under Settings → Alerts → Notifications (“Notification URLs”), or set BIRDNET_NOTIFY_URLS. The syntax is Apprise’s, so anything you already have written down works, but the station sends it itself: no Python, no apprise binary, no subprocess per detection. Handled natively: discord://, slack://, tgram://, ntfy:///ntfys://, gotify:///gotifys://, pover://, and json:///jsons:// for a plain webhook.
• Apprise — for the other ~70 services. Point BIRDNET_APPRISE_URL at an Apprise API server, or BIRDNET_APPRISE_CONFIG at an apprise config file. If every URL in that file is one of the schemes above, the apprise CLI is never invoked and you do not need it installed.
• Email — direct SMTP/STARTTLS with a per-species cooldown, configured under Settings → Alerts → Email Alerts.
• BirdWeather — upload detections to your BirdWeather station. Set the token under Settings → Alerts → Notifications, or with BIRDNET_BIRDWEATHER_TOKEN.

Either surface works for all three: the environment variable wins if you set it, otherwise the value you save under Settings → Alerts → Notifications is the one that sends. The same applies to the minimum notification confidence (BIRDNET_NOTIFY_CONFIDENCE, default 0.8), the trigger mode, the cooldown, the species allow/exclude lists, and the message templates. Changes take effect on the next restart.

When to notify

The Notification Trigger is one of: every detection; the first of each species, each day; a species seen five times or fewer in a week; both of those (not every detection); or never. These are BirdNET-Pi’s three switches (APPRISE_NOTIFY_EACH_DETECTION, _NEW_SPECIES_EACH_DAY and _NEW_SPECIES) in every combination that behaves differently: “every detection” already announces everything the other two would. In birdnet.conf it is APPRISE_TRIGGER, which takes a word or a comma-separated list (each, new-species, new-species-daily, off).

When more than one rule matches a detection, one message is sent and $reason names each of them (first time today, only seen 3 times in last 7d); BirdNET-Pi sends one message per rule. A station moved from BirdNET-Pi with all three switches at 0 has the trigger never, as it did there. Moving a birdnet.conf is covered by Migrating from BirdNET-Pi.

The Send Test Push Notification button under Settings → Alerts (/station/alerts) uses the values saved on the Settings page, so a successful test means live detections will notify too.

Message templates

The title and body of a push notification are templates, set under Settings → Alerts → Notifications (or APPRISE_TITLE_TEMPLATE / APPRISE_BODY_TEMPLATE in the config file). They use BirdNET-Pi’s $variable names, so a template moved over from a BirdNET-Pi station keeps working:

A value the station does not have renders as nothing, never as a placeholder such as 0.000000.

The three link variables need the station’s address as the phone sees it. BNB_PUBLIC_URL is read first, then BNB_BASE_URL, then the machine’s name on the local network (http://<hostname>.local:8502, the same address the installer prints). If none of these can be worked out the links are left empty rather than pointing at localhost, which would be the phone itself. A station that is only reachable through a reverse proxy or a VPN name should set BNB_PUBLIC_URL.

Keeping the credential out of the environment

A notification URL carries its bot token inside the URL, and an environment variable is readable by docker inspect, by anything with the process’s /proc/<pid>/environ, and by anything that logs its own environment. Docker and Kubernetes both solve this by mounting the secret as a file; this station accepts that convention:

services:
  birdnet:
    environment:
      BIRDNET_NOTIFY_URLS_FILE: /run/secrets/birdnet_notify_urls
    secrets:
      - birdnet_notify_urls
secrets:
  birdnet_notify_urls:
    file: ./secrets/notify_urls.txt

Four things worth knowing, each reported in the journal at startup:

• The direct value wins. Set both and the file is not read; the station says so at warning level rather than silently choosing one.
• A file that cannot be read, or that is empty, leaves the feature off — and says so at error level. A station that sends no notifications because a mount path had a typo looks exactly like one that was told to be quiet, so this is the one case worth an error line.
• Surrounding whitespace is trimmed, so the trailing newline every secret file has is harmless; inner newlines are kept, so a NOTIFY_URLS file may list one URL per line.
• A value read from a file is not copied into the settings table, so it stays out of the database and out of every backup, restore bundle and support archive taken from it. It will not appear on the Settings page either — which is the point.

BIRDNET_APPRISE_CONFIG has no _FILE form, because APPRISE_CONFIG_FILE already exists and means something different: the path of an apprise configuration file, which apprise itself reads. The SMTP password has none either — it lives only in the settings table, set from the admin UI.

MQTT & Home Assistant

A pure-Rust MQTT 3.1.1 client publishes detections to any broker (Mosquitto, Node-RED, EMQX, …) — no external broker library required.

BIRDNET_MQTT_HOST=192.168.1.10
BIRDNET_MQTT_HA_DISCOVERY=1     # publish Home Assistant auto-discovery config

A broker the station cannot reach is reported, not just retried: after ten minutes without a session the station-health alerts carry an mqtt condition with the last error, /api/v2/health says "mqtt": "disconnected", and Home Assistant shows the station offline in the meantime. Test all channels on the notifications test page publishes a real message to <prefix>/test (never retained) and sends a test email through the configured notifier, beside push and BirdWeather; a run in which no channel is configured says that nothing was tested rather than that everything passed.

Three more integrations have a button of their own on that page, each showing the real answer rather than a reassurance: MQTT broker (publishes one message and reports the broker’s refusal, the TLS error or the connect error as it came), eBird (asks eBird for the recent observations around the station with the configured key, so a refused key reads “eBird refused the API key (403)”, not “unreachable”) and Weather (fetches from the configured provider). A button is disabled, with the setting to change beside it, until that integration is configured; one that is configured but cannot start (an eBird key with no station coordinates, an unknown weather provider) is enabled and answers with that reason. They test what the running station was started with, so a value saved a moment ago shows up after a restart.

TLS

BIRDNET_MQTT_TLS=1              # port defaults to 8883 when this is on
BIRDNET_MQTT_CA_FILE=/etc/birdnet/mqtt-ca.pem
BIRDNET_MQTT_TLS_SERVER_NAME=broker.lan   # when connecting by IP

The certificate is always verified, against the system trust store plus anything in BIRDNET_MQTT_CA_FILE. There is no option to skip verification: that is the setting that gets switched on during setup and never switched off, and an unverified TLS connection carrying the broker password is worse than a plaintext one because it looks safe. Setting BIRDNET_MQTT_CA_FILE turns TLS on by itself — configuring a trust anchor and then connecting in plaintext is never what was meant.

Which certificate goes in that file depends on your broker:

• Behind a private CA — the CA’s certificate. Pointing it at the broker’s own certificate fails with UnknownIssuer.
• Self-signed, no CA — the broker’s own certificate.

Either way the broker’s certificate must carry CA:FALSE. A plain openssl req -x509 — what most “make a self-signed certificate” recipes give — defaults to CA:TRUE, and the connection then fails with CaUsedAsEndEntity. Add -addext basicConstraints=critical,CA:FALSE when generating it.

A broker that asks for a client certificate

Brokers set to require mutual TLS (Mosquitto require_certificate true, AWS IoT, EMQX with verify_peer) want the station to present a certificate of its own:

BIRDNET_MQTT_CLIENT_CERT=/etc/birdnet/mqtt-client.pem
BIRDNET_MQTT_CLIENT_KEY=/etc/birdnet/mqtt-client-key.pem

Both are PEM files and both are needed; naming one without the other is refused before any connection is made, and so is a key that does not belong to the certificate. Setting a client certificate turns TLS on by itself. The same two fields are under Settings → Alerts → Home Assistant & MQTT. Paths are to files on the station, which is how birdnet-go’s “managed” certificates are stored too; this station does not take an uploaded private key through the browser.

birdnet-behavior --doctor has an MQTT TLS line that opens each file and checks the pair without connecting, so a typo in a path is found before the first detection rather than as one warning per detection. It does not report when a certificate expires: reading a certificate’s validity dates needs an X.509 parser the station does not carry.

With --mqtt-ha-discovery, the station registers itself in Home Assistant automatically, so the latest detection, species count and confidence appear as entities you can put on a dashboard or trigger automations from.

Alerts on the station itself

The rules below watch detections. A second kind, on the same page (Settings → Alerts), watches the station: a measurement it already takes, compared against a threshold you choose.

The station alerts on a fixed set of conditions already — disk over 85 %, a source flapping, the clock adrift, the analytics copy falling behind, a classifier failing every window it is given. Those are good defaults and they are not everyone’s. The rule that catches a dying microphone at a particular station is “tell me when the hourly detection count drops below what it normally is here”, and no number chosen in this project can be that.

Seven measurements are available: disk in use (%), memory in use (%), CPU temperature (°C), detections in the last hour, seconds since the last detection, capture restarts in the last hour (the worst source), and uploads waiting to be sent. Each rule is a measurement, a direction (above or below), and a threshold.

Two things follow from where these live:

• A rule that trips has to stay tripped for three polls — fifteen minutes — before it alerts, and you get a notice when it recovers. That is the same debounce and the same episode handling the built-in conditions use, so a momentary spike does not wake anybody and a long fault is not announced every five minutes. There is no per-rule cooldown to set, because that is what the episode is.
• A firing rule appears on /api/v2/health/conditions alongside the built-in ones, and is delivered through the same notifier, logged in the same notification log, and parked in the same store-and-forward outbox if the destination is unreachable.

A measurement the station cannot read right now — CPU temperature on a board with no sensor, capture restarts with no capture supervisor — produces no alert. “Cannot tell” is not “fine”, but it is not a fault to wake somebody for either, and treating a missing reading as zero would make every below rule fire for ever.

A rule that could never stop firing is refused when you create it: a percentage is never below zero or above 100, so “disk above −1” is a notification, not an alert.

Alert rules

The Rules engine (Settings → Alerts, /station/alerts#rules; the old /admin/rules redirects there) fires conditional actions on detections — for example, a webhook only when an owl is heard at night above 0.7 confidence, or a rule that suppresses a noisy false-positive species. Each rule matches on species pattern, confidence range, hour-of-day and day-of-week.

A webhook rule can authenticate, so it can target endpoints that need a key rather than only ones that authenticate by URL alone:

Leaving the scheme on None keeps the request exactly as it was — which is what every rule created before this existed does. The credential is stored in the station’s own database, is never rendered back into the page, and is redacted from logs and from an exported rule set.

Cooldown. A calling owl is detected in every three-second window, so a webhook rule on Strix* would post once per window for as long as it called. A webhook rule therefore has a cooldown: after it posts about a species it stays quiet about that species for the number of minutes you set, and the same rule still posts at once for a different bird. The create form asks in whole minutes and starts at 5. 0 posts for every matching detection, the behaviour of a rule made before the cooldown existed, and those rules keep it (the list says no cooldown). The longest is 10080 minutes, seven days; anything that is not a whole number of minutes in that range (a negative, a fraction such as 1.5, text, a blank field, a number past the limit) is refused with the range named and the rule is not created, never shortened to fit. Only webhook rules have a cooldown, so the field is part of the webhook section of the form: a Log rule writes its entry for every match and a Suppress rule must suppress every match, because one that stopped after its first would let the later notifications through. The list shows each webhook rule’s cooldown (cooldown 5 min, cooldown 1 h, or no cooldown) and an exported rule set carries it, so a rule moved to another station keeps it; a rule with no cooldown writes no cooldown_secs at all, and a file written before the cooldown existed imports with none. The cooldown runs on the detection’s time and not the clock on the wall, so a backlog replayed after a power cut posts once per window of the recording, not once for the whole night.

Test on a rule fires its action once, immediately, with an unmistakably synthetic detection (Test Detection (not a real bird)) and reports the HTTP status. Finding out an endpoint is wrong is worth doing when the rule is written rather than the first time an owl calls at 3 a.m.

Export downloads the whole rule set as JSON with every credential replaced by ***REDACTED***, so it is safe to paste into a forum thread when asking for help. Export with credentials is the backup-and-restore form and that file is a secret. Import adds the rules in a pasted set — it never replaces what is already there — and names any rule whose credential arrived redacted, since those will fire unauthenticated until one is entered. One unusable entry is reported and skipped rather than discarding the rest of the paste.

The file carries both kinds of rule: the detection rules above and the station alerts that watch disk, memory, temperature and the rest. They are different mechanisms — one matches a detection as it arrives, the other compares a measurement every five minutes — but an operator moving a station or asking for help wants one file, not two. Metric rules have no credential, so the redaction question does not apply to them.

The file records a format version. A rule set written before metric rules existed still imports, as a set with none; a set from a newer station is refused with a message naming both versions rather than being read as a set of rules with fields missing. A metric this station does not implement is named and skipped, not silently dropped — otherwise a file from a newer station would import looking complete while missing the rules that mattered. Import applies the same validation the form does, so a rule that could never stop firing (“disk above −1”) is refused either way.

Remote Access & Security

By default BirdNet-Behavior binds to 0.0.0.0:8502 — reachable from any device on your LAN. Viewing the dashboard is open (no login); signing in is required for the /admin* panel, the Settings management tabs and every action that changes something — with a password a fresh install sets for you. For a station reachable from beyond the LAN, private mode puts the dashboard itself behind that sign-in. This page covers reaching the station from your network and from elsewhere, safely.

On your local network

Out of the box the dashboard is already reachable from other devices. Browse to http://<pi-ip>:8502 from any device on the network — find the Pi’s address with hostname -I.

The 0.0.0.0 default exposes the dashboard to everyone on your network. That’s usually fine at home: the read-only views are open, and the /admin panel is protected by the auto-generated password (see below). On an untrusted network (a shared flat, public Wi-Fi), confirm CADDY_PWD is set and consider restricting the bind.

Restrict to this device only

To make the dashboard reachable only from the machine itself, bind to loopback:

BIRDNET_LISTEN=127.0.0.1:8502

(Or answer “restrict to this device” in the interactive installer.) Then reach it remotely with an SSH tunnel (ssh -L 8502:localhost:8502 pi@host) or a VPN — see the private-tunnel section below.

Built-in HTTPS

The server terminates TLS itself. It is off by default — a station on a trusted LAN behind a reverse proxy has no need of it, and turning it on for everyone would break every existing bookmark.

The one-command version

birdnet-behavior --tls-mode self-signed

HTTPS comes up on 8503 (plain HTTP keeps answering on 8502) and the log prints one path:

self-signed HTTPS: import this CA file once to stop the browser warning
  ca=/home/pi/BirdNet-Behavior/tls/local-ca.crt

(The folder is tls beside the database, or --tls-dir: ~/BirdNet-Behavior/tls for the account the bare-metal service runs as — pi here — and /data/BirdNet-Behavior/tls in Docker.)

That file is a small certificate authority the station generated for itself, and the server certificate is signed by it. Import the CA once — into your browser, your OS trust store, or curl --cacert — and the warning stops. It keeps working when the server certificate rotates (the CA is good for ten years; the certificate it signs for 397 days and is replaced a month before it expires — checked once a day while the station runs, and swapped in without a restart), so you do this once per station, not once per year. On a Pi whose clock has not been set yet (no battery-backed clock, NTP not yet reached) no certificate is minted: the station serves plain HTTP on the same address, says so in the journal and in --doctor, and restarts itself to mint one as soon as the clock is set.

The CA is limited to this station’s own names: localhost, .local names, the loopback, private and link-local address ranges, and any extra name you gave with --tls-hostnames. Anything that can read the CA’s private key (it is local-ca.key, mode 0600, owned by the service user) can therefore not mint a certificate for a public website that your devices would trust. A phone joining the network, a new DHCP lease or a new .local name needs nothing from you. A new public name added to --tls-hostnames does: the station makes a new CA for it, logs a warning saying so, and you import the new local-ca.crt on the devices that trusted the old one. The same happens once, when you upgrade from a release before CAs were limited this way.

To serve only HTTPS on the usual port, point both at the same address:

birdnet-behavior --listen 0.0.0.0:8502 --tls-mode self-signed --tls-listen 0.0.0.0:8502

Or keep 8502 open and have it redirect:

birdnet-behavior --tls-mode self-signed --tls-redirect

With a real certificate

If you already have one — from your own ACME client, an internal CA, or a purchase:

birdnet-behavior --tls-mode manual \
  --tls-cert /etc/letsencrypt/live/birds.example.com/fullchain.pem \
  --tls-key  /etc/letsencrypt/live/birds.example.com/privkey.pem

Both files are re-checked once a minute and re-read when they change on disk, so a certbot renew in the small hours is serving within a minute, from the next handshake — no restart, no cron hook.

What the browser shows

Settings → Access → Secure connection says which of the three modes the station is in. In self-signed mode it shows when the certificate runs to (read from the certificate’s own record, not the configured length) and offers the station’s local CA certificate for download, so you can add it to a phone or computer once instead of clicking through the browser warning every time. The CA’s private key is never served. The page has no upload or generate button, on purpose: the page used to fix a plain-HTTP station is itself plain HTTP, so a form for a private key would send the key across the network in the clear; the certificate and key are files on the station, and self-signed already generates and renews its own.

Checking it before you rely on it

--doctor does exactly what startup does, early enough to be useful:

$ birdnet-behavior --doctor
[ PASS ] HTTPS — self-signed on 0.0.0.0:8503, covering localhost, pi, pi.local, 127.0.0.1 (valid 397 days)
[ PASS ] HTTPS — import /home/pi/BirdNet-Behavior/tls/local-ca.crt to stop the browser warning

A mistyped path or a key that does not match its certificate is a [ FAIL ] here rather than a service that restart-loops after you have gone inside.

Every setting has a BIRDNET_TLS_* environment variable and a config-file key; see .env.example.

Do NOT expose it directly to the internet

Built-in HTTPS encrypts the traffic; it does not make the station safe to port-forward. There is no rate-limited login lockout, no WAF, and the self-signed mode carries no publicly-trusted name. Never port-forward 8502/8503 straight to the internet. Use a VPN or a private tunnel, or put it behind a reverse proxy that terminates HTTPS with a real certificate and adds authentication.

Reverse proxy with HTTPS

Caddy (simplest — automatic HTTPS)

Caddy fetches and renews a Let’s Encrypt certificate for you. A whole Caddyfile can be:

birds.example.com {
    reverse_proxy 127.0.0.1:8502
    basic_auth {
        # generate the hash with: caddy hash-password
        birder $2a$14$....hashed-password....
    }
}

nginx

server {
    listen 443 ssl;
    server_name birds.example.com;
    # ssl_certificate / ssl_certificate_key from certbot or your CA

    location / {
        proxy_pass http://127.0.0.1:8502;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;          # WebSocket (live feed,
        proxy_set_header Connection "upgrade";           # spectrogram, kiosk)
    }
    auth_basic "BirdNet-Behavior";
    auth_basic_user_file /etc/nginx/.htpasswd;            # htpasswd -c … birder
}

Keep the X-Forwarded-For line. It is how the station tells visitors apart for its rate limit, its sign-in throttle and the audit log. A proxy that sets only X-Real-IP passes the visitor’s own X-Forwarded-For through, and a visitor could then claim any address. When the two headers name different visitors the station believes neither and counts the request as the proxy’s own — safe, but every visitor then shares one rate-limit bucket. The log says so once: “a trusted proxy sent X-Forwarded-For and X-Real-IP naming different clients”. For the same reason, if your proxy does not set X-Real-IP itself, have it clear one a visitor sends (nginx: proxy_set_header X-Real-IP "";), so nobody can spend the proxy’s own sign-in throttle by forging it.

Keep the X-Forwarded-Proto line too. The station marks its sign-in cookie Secure when the request reached it over HTTPS: on its own TLS listener, when a trusted proxy says so with X-Forwarded-Proto (or Forwarded: proto=), or when BNB_PUBLIC_URL is an https:// address and the request was addressed to that host. A proxy that sends none of these, with no BNB_PUBLIC_URL set, gets a cookie without Secure, which a browser will also send over plain HTTP.

WebSocket matters here. The live dashboard feed, the spectrogram, and kiosk mode all use WebSockets (/api/v2/ws/detections and /api/v2/ws/spectrogram). Make sure your proxy forwards the Upgrade/Connection headers (shown above) or those features will silently stall.

Sharing one hostname: serving under a path

The setup above gives the station its own hostname. If you already run other services behind one hostname and want the station at https://home.example/birdnet, set a base path:

BIRDNET_BASE_PATH=/birdnet

The station then serves everything — pages, API, static assets, WebSockets — from under that prefix, and every link, form, redirect and cookie it emits carries it. A visitor who reaches the bare host root is redirected to the prefix, so a mistyped bookmark still lands somewhere useful.

Your proxy must pass the full path through unchanged. The station expects to see /birdnet/today, not /today. This is the opposite of the usual “strip the prefix” recipe, and it is the one thing that goes wrong:

home.example {
    handle /birdnet/* {
        reverse_proxy 127.0.0.1:8502    # NOT handle_path — that strips /birdnet
    }
}

location /birdnet/ {
    proxy_pass http://127.0.0.1:8502;   # no trailing path: adding one makes
    proxy_set_header Host $host;        # nginx strip the prefix
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Home Assistant ingress works the same way.

A prefix that cannot be used — one containing .., whitespace, or a query string — is refused and logged, and the station serves from the root. It is not quietly corrected: a corrected prefix would not match what your proxy sends, and every request would 404 with nothing to explain why.

Home Assistant, Nextcloud and the rest each need their own location block. Nothing about the base path changes the TLS or authentication advice above.

Built-in admin sign-in

The binary gates the /admin panel itself — no proxy required — using the BirdNET-Pi CADDY_PWD convention for the password. Viewing the dashboard and the read-only /api/v2/* endpoints stay open. Signing in is required for the /admin* panel, the Settings management tabs (/station/capture, /station/alerts, /station/data, /station/settings, /station/access) and every action that changes something — deleting, relabelling, reviewing or locking a detection, approving or deleting a quarantined record, bulk review from Search, and saving the onboarding wizard.

Requesting /admin* without a session redirects (303) to a sign-in form at /login, which issues a session cookie. It is not HTTP Basic Auth, so curl -u user:pass will not work — post the form, or sign in through the browser.

A fresh install auto-generates a strong password, prints it once in the post-install summary, and stores it as CADDY_PWD in birdnet.conf. Sign in with the username admin — the account the dashboard seeds, and the only one that exists until you add more in the admin panel.

CADDY_PWD=a-long-random-password

CADDY_USER is read from the process environment only. Under Docker, where compose passes it through, it renames the sign-in; on a bare-metal install the systemd unit sets no EnvironmentFile, so a CADDY_USER line in birdnet.conf has no effect and the sign-in name stays admin.

After editing the config, restart the service (sudo systemctl restart birdnet-behavior). This is still plain HTTP — only rely on it behind TLS, or on a trusted LAN. Clearing CADDY_PWD leaves /admin open to anyone who can reach the dashboard; if the server binds to a non-loopback address (e.g. the default 0.0.0.0) with no CADDY_PWD set, it logs a prominent warning at startup. The live-detection WebSocket and /api/v2/health are exempt from this auth (they sit outside the gated router, and a browser cannot attach a session to a WebSocket handshake anyway), and are read-only in any case — restrict those at the network layer if you need to.

Admins and viewers

Each account on Settings → Access is an admin or a viewer.

• An admin can do everything the sign-in protects.
• A viewer can open every page behind the sign-in, the settings forms included, but can change nothing: every save, delete, lock, review or other change is refused (403). The settings forms show a viewer every stored password, token and key masked.
• A viewer is also refused the few pages that would hand over credentials or the whole database: the full backup and the backup files, the support bundle, the alert-rules export (webhook URLs carry their tokens), an audio source’s own settings (an RTSP URL carries its password), the birdnet.conf lines the BirdNET-Pi import offers to download, and Diagnostics (/admin/doctor, which prints the MQTT broker and the certificate and model paths). The source’s status pill stays visible, and the model panel on the Capture tab shows a viewer what is wrong without the file path.

Cross-origin requests (CORS)

By default the API allows no cross-origin reads — a website you happen to visit can’t read your station’s data over the LAN. If you serve a separate dashboard from a different origin, allow it explicitly:

BIRDNET_CORS_ALLOWED_ORIGINS=https://dashboard.example.com

List origins by name; * is not supported. The station logs an error, ignores that entry and keeps the others, because a wildcard would let any website read the API. State-changing requests are protected by a CSRF guard regardless of this setting.

Embedding the station in another page

By default no other website can show the station inside a frame: every page carries Content-Security-Policy: frame-ancestors 'self' and X-Frame-Options: SAMEORIGIN. With sites listed (below), only the dashboard (/), the wall display (/kiosk) and the live view (/recordings) change; the sign-in, /admin, /station, the setup wizard and every other page keep that policy whatever you list. That is the right default for a page with an admin sign-in behind it, because a site that can frame the station can lay invisible controls over it to trick a visitor into clicking (clickjacking). It also means a Home Assistant card or a Grafana panel cannot show the live view.

To allow it, name the places that may, in birdnet.conf or under Settings → General → Online services:

EMBED_ORIGINS=http://homeassistant.local:8123, https://abcd1234.ui.nabu.casa

• Each entry is a full origin, http or https, host and optional port, no path. https://*.example.com covers every subdomain of a domain you own. Name your own host under a shared service rather than the service: a wildcard over ui.nabu.casa, github.io, pages.dev, co.uk and the like would let everyone who registers a name there show the station, so those are refused (from a short built-in list of such suffixes, not the full Public Suffix List: a suffix that is not on it is not protected).
• There is no way to allow every site. A bare *, a scheme alone and a wildcard over a whole top-level domain (https://*.com) are refused. tphakala/birdnet-go’s allowembedding is a switch for all sites at once; here you list the sites, because everyone who asks for this knows where they are embedding from.
• One entry the station cannot read refuses the whole list, and then no site may embed; the journal and --doctor say which entry. Dropping just the bad one would silently narrow what you typed.
• With a list set, X-Frame-Options is left off (it cannot name a third party) and frame-ancestors alone decides: 'self' plus your origins. Nothing else in the policy changes.
• Applies after a restart.

For a page on another site, what you get in the frame is the station as an anonymous visitor sees it: the sign-in cookie is SameSite=Lax, which a browser does not send from inside a frame on another site, so signing in does not carry into the frame. A site is the registrable domain, not the origin, so this does not hold for the usual set-up: Home Assistant at http://192.168.1.10:8123 framing the station at http://192.168.1.10:8502 (another port), or a sibling subdomain, is the same site. There the cookie is sent, and if you are signed in to the station in that browser the framed dashboard shows its administrator controls, which the embedding page could click for you if it were compromised. List only places you trust with your browser, and sign out of the station on a shared screen.

A safer alternative: a private tunnel

For remote access without opening any ports, a mesh VPN like Tailscale or WireGuard is the easiest secure option: install it on the Pi and your phone/laptop, and reach http://<tailscale-ip>:8502 as if you were on the same LAN — encrypted, no public exposure, no certificates to manage.

Checklist

• Keep CADDY_PWD set so /admin stays protected (a fresh install generates one) — don’t clear it on a non-loopback bind.
• Restrict the bind to 127.0.0.1 (+ SSH/VPN) if you don’t need LAN access.
• Never port-forward 8502 directly — always terminate TLS at a proxy or use a VPN for off-LAN access.
• Forward WebSocket upgrade headers in the proxy.

Backups & Recovery

The Data tab (/station/data) is where you protect your records: snapshots, exports, storage and the controls you hope you never need.

Three kinds of backup

Snapshots copy the database only. They are small and quick, they run automatically every 7 days, and the station keeps the most recent 14. They live in backups/ beside birds.db — on the station itself. That makes them perfect for undoing a bad import or recovering from database corruption, and useless if the SD card dies.

Full backups bundle the database, your recordings and your config into one .tar.gz you download. This is the one to keep somewhere else. Nothing takes these automatically — download one after any big change, and periodically if your station matters to you.

Offsite copies send each weekly snapshot to an object store or an SSH server, encrypted before it leaves. Off by default; see Offsite backups below. This is what covers the failure the other two do not: the card wearing out, the enclosure flooding, the Pi being stolen.

The automatic schedule runs on elapsed wall-clock time, not uptime, so a station that reboots often still gets its backups: an overdue job runs shortly after the next boot rather than restarting its timer.

Restoring

Restore from file takes a full backup archive and puts its database and recordings in place of the current ones. The station first checks that the disk can hold the archive’s contents with headroom, refuses an archive whose database is not named as this station’s, stops recording detections, unpacks the archive beside the database and integrity-checks the copy there, and only then swaps the files in (the database by rename, so the running process is never left reading a half-written file; recordings merged clip by clip, so clips the archive lacks are kept). Under systemd the station restarts itself to load the result; elsewhere it tells you to.

Restoring is destructive and cannot be undone. It replaces what is on the station now, and the station does not snapshot the current state first. Download a full backup before you restore. Detections stay paused until the restart that follows.

The archive’s contents are not signed or verified — only restore an archive you produced yourself and trust.

Individual snapshots can be downloaded and deleted from the snapshot list, so you can recover a database by hand: stop the service, put the snapshot in place of birds.db, and start it again.

Export

Your detection data is yours, in formats other tools read:

• Detections (CSV or JSON) — every detection the station stands behind, with date, species and confidence. Rows a reviewer rejected, and imported rows on a station that excludes imports from its analytics, are left out; the same rule the charts use. Date and Time are the station’s local wall clock with no offset, exactly as BirdNET-Pi wrote them; beside them every row carries Event_Date (that wall clock with the offset that was in force, RFC 3339, so the two passes of a repeated autumn hour are told apart) and Detected_At_UTC (the instant), both blank on a row that names no point in time. Every row also says which model made it: the CSV ends in Run_Id,Model_Name,Model_SHA256 and the JSON carries run_id, model_name and model_sha256 per row — the model file’s name and the SHA-256 of its bytes, so a season that spans a model upgrade can be split by which model heard what. The runs themselves (when each started, the labels checksum, the settings in force) are at /api/v2/analysis-runs. The three columns are empty on a row this station did not analyse: imported history, or rows older than the run table.
• Species summary (CSV) — per-species totals and first-seen dates.
• eBird checklist — eBird Record Format, one record per species per hour with Number written as X (present, not counted) and the detection tally in the comment. Only detections at or above a confidence floor (0.75 by default, ?min_confidence=) that a reviewer has not rejected are included, and the coordinates are the station’s configured location — blank, never 0,0, if none is set. Protocol, observer count, region and completeness are query parameters (?protocol=Stationary&observers=1&state=&country=&complete=false), because they are facts about the submitter rather than the station.
• BirdNET-Pi BirdDB.txt — semicolon-separated, the twelve BirdNET-Pi columns and nothing more, for tools expecting the original format. Same rows as the CSV, without the three model columns: the format has no room for them and its consumers count fields.
• Raven selection table — one tab-separated table over every detection that has a clip, in the format BirdNET-Analyzer writes (Selection, View, Channel, Begin Time (s), End Time (s), Low Freq (Hz), High Freq (Hz), Common Name, Species Code, Confidence, Begin Path, File Offset (s)), so Raven Pro opens it against the recordings folder as a multi-file table. Each selection is placed where the detection sits inside its clip, from the lead-in the extractor recorded; a row written before that was recorded (schema 47) spans its whole clip, and a row with no clip, or no clip length, is left out rather than given a made-up window. The species code is the eBird code from the station’s label file, or the scientific name when it has none. Every clip also has its own table at /api/v2/recordings/<clip>/raven.txt and an Audacity label track (begin, end, label; File → Import → Labels) at /api/v2/recordings/<clip>/labels.txt; the detection page links to neither yet, so paste the clip’s filename in.

Storage & retention

The storage breakdown shows where space is going — the database (including its write-ahead log), your recordings, and the snapshots — measured live, not estimated.

Time-based retention is off by default, not absent: set Keep Clip Audio (days) (CLIP_RETENTION_DAYS, --clip-retention-days) for a rolling window — 0, the default, keeps audio for ever. Two disk-based limits apply alongside it:

• the disk manager purges the oldest recordings once the disk crosses DISK_PURGE_THRESHOLD (default 95%);
• MAX_FILES_SPECIES keeps at most N clips per species, pruned on the daily maintenance tick.

Recordings you have locked are never purged by either, and locking takes effect on the next cycle — no restart needed. When a clip is pruned its detection row survives: your counts, species lists and analytics are unaffected, only the audio is removed.

To lock a clip, open Recordings and use the 🔒 Lock action on a row — or select several and use the bulk Lock button above the grid. Locked rows show an unlock action in the same place.

Offsite backups

A snapshot on the same SD card as the database it came from protects you from a corrupt page and a bad import. It does not protect you from the card, and SD cards in a box on a fence post are a when, not an if.

Set OFFSITE_BACKUP and each weekly snapshot is encrypted on the station and uploaded. Nothing else changes: the local snapshots and their 14-file rotation stay exactly as they were, so this only ever adds a copy.

Encryption is not optional

Your database is a log of what is around your house and when you are there. “Server-side encryption” on a bucket means the provider holds the key; an SFTP host means its administrator does. So the station encrypts before it uploads — argon2id over your passphrase, then ChaCha20-Poly1305 — and there is no setting to turn that off.

OFFSITE_PASSPHRASE=a long passphrase you keep somewhere else

Write it down somewhere that is not this station. There is no recovery: the passphrase is not stored anywhere, not derivable from the backup, and not known to us. A backup you cannot decrypt is not a backup.

At least 12 characters, and the station refuses shorter ones — not as password policy, but because below that the argon2 parameters stop being what protects the file.

Secrets are config-file or environment keys only. There is deliberately no --offsite-passphrase flag: anything on a command line is visible in ps to every user on the machine, is copied into the journal by systemd’s ExecStart=, and lands in your shell history.

To an S3-compatible store

Works with AWS S3, Backblaze B2’s S3 API, Cloudflare R2, Wasabi, MinIO, Ceph RGW and Garage.

OFFSITE_BACKUP=s3
OFFSITE_S3_ENDPOINT=https://s3.eu-west-2.amazonaws.com
OFFSITE_S3_BUCKET=my-birdnet-backups
OFFSITE_S3_PREFIX=stations/garden          # optional
OFFSITE_S3_REGION=eu-west-2                # default us-east-1
OFFSITE_S3_ACCESS_KEY=AKIA...
OFFSITE_S3_SECRET_KEY=...
OFFSITE_S3_ADDRESSING=auto                 # auto | virtual | path
OFFSITE_PASSPHRASE=...
OFFSITE_KEEP=8                             # 0 keeps everything

OFFSITE_S3_ADDRESSING decides whether the bucket goes in the hostname (bucket.endpoint/key, which AWS requires for buckets made after September 2020) or the path (endpoint/bucket/key, which every self-hosted store speaks and some speak only). auto picks by endpoint and is right nearly always; set it explicitly if you get a 404 that mentions the bucket.

Give the station its own access key with permission to PutObject, ListBucket and DeleteObject on that prefix, and nothing else. It never reads a backup back — restoring is a thing you do from another machine, deliberately.

To an SSH server

Any host you can sftp into: a NAS, a VPS, a Pi in a different building.

OFFSITE_BACKUP=sftp
OFFSITE_SFTP_HOST=backup.example.net
OFFSITE_SFTP_PORT=22
OFFSITE_SFTP_USER=birdnet
OFFSITE_SFTP_DIR=/srv/backups/garden
OFFSITE_SFTP_IDENTITY=/home/pi/BirdNet-Behavior/ssh/id_ed25519
OFFSITE_SFTP_KNOWN_HOSTS=/home/pi/BirdNet-Behavior/ssh/known_hosts   # defaults beside the key
OFFSITE_SFTP_HOST_KEY_POLICY=yes                            # yes | accept-new
OFFSITE_PASSPHRASE=...

Key authentication only — passwords are disabled, because a batch upload cannot answer a prompt and would hang until something killed it. The key lives where you choose; the examples put it in an ssh folder inside the station’s data directory, which is the one place the service is allowed to read and write (/home/pi/BirdNet-Behavior here: the data directory of the account the bare-metal service runs as — substitute yours; in Docker it is /data). There is no birdnet user on a bare-metal station, so run the commands as the service’s account (the OFFSITE_SFTP_USER above is the user on the backup server). Generate a key for the station and authorise it on the server:

SVC=$(systemctl show -p User --value birdnet-behavior)       # bare metal: the account the service runs as
DATA=$(getent passwd "$SVC" | cut -d: -f6)/BirdNet-Behavior   # its data directory
sudo -u "$SVC" mkdir -p "$DATA/ssh"
sudo -u "$SVC" ssh-keygen -t ed25519 -f "$DATA/ssh/id_ed25519" -N ''
sudo -u "$SVC" ssh-copy-id -i "$DATA/ssh/id_ed25519.pub" birdnet@backup.example.net
# Docker: docker compose exec birdnet sh -c 'mkdir -p /data/ssh && ssh-keygen -t ed25519 -f /data/ssh/id_ed25519 -N ""'

Then record the server’s host key, after checking the fingerprint against the server itself:

ssh-keyscan -p 22 backup.example.net | sudo -u "$SVC" tee "$DATA/ssh/known_hosts"

OFFSITE_SFTP_HOST_KEY_POLICY has no “off”. Host key checking is what makes the upload go to your server rather than to whoever answers, and there is no setting that disables it. Use accept-new for the first connection on a network you control, then set it back to yes so a changed key is refused.

How often

BACKUP_SCHEDULE is weekly (the default) or daily. Daily means losing at most a day rather than a week; it also means seven times the offsite upload, which is why weekly stays the default rather than changing an existing station’s bandwidth underneath it.

It schedules the backup only. The space reclaim — checkpointing the write-ahead log and returning free pages to the filesystem — is a separate job and stays weekly whatever you set here. Asking for a daily backup is not asking to rewrite the database file every day, and on an SD card that is write endurance spent for space nobody needed back.

Both are listed at GET /api/v2/system/jobs, with when each last ran and whether it is due.

Over rsync, when the link is bad

OFFSITE_BACKUP=rsync sends the same backup to the same SSH server, with the same OFFSITE_SFTP_* settings above — only the program that moves the bytes changes. Switching is one word:

OFFSITE_BACKUP=rsync
OFFSITE_RSYNC_BWLIMIT=512   # KiB/s; 0 or unset for no limit

Use it if your uplink drops. rsync keeps what already arrived, so a transfer that dies at 90 % of a 1.3 GB backup continues from there next time. Over SFTP the same backup starts again from zero, and on a link bad enough to matter it may never finish at all. OFFSITE_RSYNC_BWLIMIT is the other reason: it stops a backup saturating a shared or metered connection for an hour.

It is not faster because it is “incremental”. rsync’s famous trick is sending only the blocks that changed, and that is worth nothing here. Your backups are encrypted before they leave, under a fresh random salt each time, so consecutive backups share no blocks at all — not even when the database has not changed. Measured on a 1 MiB file: 1496 of 1497 blocks reusable in plaintext, 0 of 1498 once encrypted. rsync sends the whole file every run, exactly as SFTP does. The resume and the speed limit are the reasons to use it.

It needs both rsync and sftp installed. rsync moves the bytes; sftp creates the directory, lists what is there and deletes what retention drops — rsync has no command that removes one named remote file, and its nearest equivalent deletes everything a filter does not mention, which is not a risk worth taking with your only offsite copies.

Retention

OFFSITE_KEEP is how many backups stay at the destination; the oldest go when a new one arrives. 0 keeps everything.

Retention only removes files named like the ones this station writes — birds.db.backup.<timestamp>.bnb — directly in its own prefix or directory. Anything else there is left alone, and so is anything in a folder below it, so you can share a bucket without losing the other things in it. Give every station its own prefix: two stations writing to the same prefix produce identical names, and each would prune the other’s backups as its own.

Checking it works

birdnet-behavior --doctor

reports the destination, how many backups it will keep, and — for SSH — whether the key exists, whether its permissions are ones OpenSSH will accept, and whether the host is known. It makes no connection: --doctor runs on every start, and a diagnostic that dials a remote host fails whenever the uplink is down.

Uploads are logged at info on success and warn on failure, with the destination named. A failed upload never affects the local backup or the space reclaim that follows it.

Restoring one

Download the .bnb file from your bucket or server, then:

birdnet-behavior --decrypt-backup downloaded.bnb --out birds.db

It will ask for the passphrase. The result is an ordinary SQLite database — put it in place of birds.db with the service stopped, as with any snapshot.

Danger zone

Two destructive actions live in a clearly marked danger zone, each gated behind an explicit confirmation:

• Clear all detections — empties the detections and notification tables; settings are kept.
• Clear extracted audio — deletes the saved WAV clips; the detection records stay.

There is no undo. Take a full backup first.

Station Health

The Settings Health tab (/station) is the station’s vital-signs monitor — the operator’s “is it working?” screen, and the public, login-free heir to the old /system page (which now permanently redirects here).

• Status banner — one line that stays green while nothing needs attention, and flips to amber naming the problem when storage runs low, the database integrity check fails, no audio sources are configured, or uploads are backed up.
• Audio sources — a per-source panel fed live by the capture supervisor: a state chip (Live · Stalled · Backing off · Paused), a rolling 24-hour uptime strip, how long since audio last arrived, today’s detections for the source and the current retry/backoff line. When the web server runs without the capture supervisor (--web-only, or tooling) it falls back to an activity view — how many detections each source produced today and how recently — and never fakes a live/stalled chip.
• Vitals — CPU, memory, temperature (with a graceful “no sensor” state where a probe isn’t available) and disk, each with a meter. The disk figure follows df’s “used of reachable space”, so reserved blocks or a container quota don’t understate it.
• Microphone health — the station’s own background noise floor per source over the last 7 days, and how far it has moved against that source’s own 30-day average. This is the one signal that separates a season going quiet from a microphone going deaf: a failing capsule keeps its process alive and its status green, and shows up only as fewer detections — exactly like autumn. Ambient background does not stop when the birds do, so a large, sustained drop here, with nothing else changed, points at the equipment. The panel is absent until the station has sampled something (if the history cannot be read, the page says it could not load it rather than staying absent), and says “building a baseline” rather than reporting a change it has nothing to compare against. No threshold is applied and no alert is sent: a noise floor moves for weather, season, a road and leaf-out, and a number picked without a season of real recordings behind it would fire on all of them. Same figures are exported as birdnet_noise_floor_dbfs and birdnet_noise_floor_drift_db for anyone who wants to draw their own line.
• Pipeline — the last detection (the plain-English answer to “is it actually working right now?” — every other gauge can read healthy while the station records silence, but a fresh detection proves the whole chain from microphone to database is alive), queued uploads (shown only when a network outage backs them up), the service uptime, total detections, and the species filter: whether the occurrence filter is running and how many species it currently admits. A filter admitting zero species means nothing the station hears can be recorded, and the status banner says so.
• Diagnostics — a short checklist (audio sources · disk headroom · database integrity) with a link to the station’s full doctor report at /admin/doctor: the same checks birdnet-behavior --doctor runs — audio device listing, model, clock, TLS, database, offsite, disk — run on request and read-only, with Download as JSON (/admin/doctor.json, what --doctor-json prints) and Download a support bundle (/admin/support-bundle, the same redacted archive --support-bundle writes) beside it. Both are behind the admin login, so a station in a field can be diagnosed from a phone without SSH.

The detection deadman

Behind the “Last Detection” row is a watchdog that turns silence into an alert. It measures the seconds since the most recent detection and, past a threshold you set with --deadman-hours (env BIRDNET_DEADMAN_HOURS, config key DEADMAN_HOURS; default 24 h, 0 disables the alert), logs a loud warning and sends one notification per quiet episode through Apprise — with a recovery notice when detections resume. It never cries wolf on a brand-new station that has not detected anything yet, and a silent night is well within the default. Raise the threshold for genuinely sparse habitats. The same freshness value is exported as the birdnet_detection_silence_seconds Prometheus gauge and as detection_silence_secs on /api/v2/health, so you can alert on it from Grafana or any uptime monitor. See the Field Deployment Runbook for the monitoring playbook.

The built-in doctor

For a deeper, scriptable check, run the diagnostic from the CLI. It prints a one-screen report covering CPU, configuration, audio reachability, the model file, database integrity, disk space, whether a container’s data would survive the container, tool dependencies and network — each problem with a concrete suggested fix.

sudo -u "$(systemctl show -p User --value birdnet-behavior)" birdnet-behavior --doctor   # bare metal
docker compose exec birdnet birdnet-behavior --doctor                                     # Docker

(On bare metal the service runs as the account that ran the installer; there is no birdnet user, and the systemctl show call prints that account.)

Exit code: 0 = all good, 1 = warnings only, 2 = at least one error.

For monitoring (Nagios / Zabbix / a Home Assistant command sensor / a Prometheus textfile collector) the same checks are available as one line of JSON:

birdnet-behavior --doctor-json | jq .

The support bundle

birdnet-behavior --support-bundle [PATH] (or Download a support bundle at /admin/support-bundle, behind the admin login) writes one .tar.gz holding the diagnostic report (doctor.json and doctor.txt), the station’s version, a redacted copy of the configuration (config.redacted), the last 2000 journal lines, the station’s own errors.jsonl (warnings and errors that survive a reboot), and uname -a and df -h; the download from the web UI also carries recent.log, the live log view’s buffer. That is what a maintainer asks for in the first three replies to a bug report. Passwords, tokens and URL credentials are masked. The station’s LATITUDE and LONGITUDE are shown to one decimal place (about 11 km) in the configuration section, and wherever the journal printed them (BirdWeather’s start-up line, a settings change) the exact values are replaced by the same coarse form; a value that is not a number is masked. One decimal says which hemisphere, which season’s daylight and which region’s species, which is all a diagnosis needs; four decimals are a house. The bundle is written to be pasted into a public issue, but read it before you post it all the same. (Earlier builds printed the coordinates exactly.)

Before an upgrade: --migration-report

Most database migrations only add columns and indexes. A few rewrite rows that are already on disk and cannot be undone from inside the database; migration 24, which folds each detection’s chunk offset into its timestamp, is the one that has done so. --migration-report says what the next start would do to your history, before it does it:

sudo -u "$(systemctl show -p User --value birdnet-behavior)" birdnet-behavior --migration-report   # bare metal
docker compose exec birdnet birdnet-behavior --migration-report                                     # Docker

For each pending migration that rewrites rows it prints what would move, by how much, how many rows are left alone and why, and the date range involved. It opens the database read-only and changes nothing, so it is safe on a live station. If there is no database yet it says so and stops; if no pending migration rewrites rows it says that, adding that schema-only migrations may still be pending.

The rewrite itself happens on the next normal start, and just before it the database is copied to <db>.pre-migration-<version>.backup, so undoing it is a file move. The copy needs about as much free space as the database. A backup that cannot be written stops the migration rather than proceeding without one; a station whose disk cannot hold the copy can set BIRDNET_SKIP_MIGRATION_BACKUP=1 and accept that the earlier timestamps cannot be recovered (see Configuration).

The species totals: --rebuild-species-summary

The species list and the per-species charts read a maintained table of totals (species_summary) rather than counting the whole history on every page load. It is derived data. --rebuild-species-summary recomputes it from the detections and exits:

sudo -u "$(systemctl show -p User --value birdnet-behavior)" birdnet-behavior --rebuild-species-summary   # bare metal
docker compose exec birdnet birdnet-behavior --rebuild-species-summary                                     # Docker

It prints how many species-per-hour buckets it rebuilt and how many had disagreed with the detections beforehand, and the detections themselves are not touched. If the summary still disagrees after a full rebuild it exits with an error rather than reporting success, which means something is writing to detections in a way the summary’s triggers cannot see.

You should rarely need it. --doctor reports a disagreement under “Species summary” and names this command, and the running station also checks for one once a day and, when it finds drift, rebuilds the summary itself.

How much memory the analytics engine gets

DuckDB treats its memory limit as permission to use that much, so on a small board a limit that is a large share of physical RAM is a standing invitation to be OOM-killed in the middle of a dashboard query — at three in the morning, when nobody is looking.

The station sizes the pool itself. Unset, BIRDNET_DUCKDB_MEMORY_LIMIT becomes a quarter of whatever this process may actually use: the smaller of physical RAM and any cgroup limit it is under (the systemd unit ships MemoryMax=1G; a container has its own). That is capped at 256 MiB and floored at 64 MiB.

• On the shipped unit that comes to exactly 256 MiB — the flat value the station used before, so nothing changes on the hardware it was written for.
• On a 512 MB board it comes to 128 MiB, instead of handing one subsystem half the machine.
• Below a 256 MiB ceiling the floor cannot be met, and analytics is refused at startup with a line in the journal saying so. The station still records, classifies and serves; it just has no behavioural dashboards. Refusing is the point: the alternative is starting something that will be killed mid-query.

Set the variable and it is used verbatim, on any machine — including one the sizing would have refused. Someone who has measured their own station knows more than this does.

Where the two numbers come from, since neither is a preference:

• A quarter is the proportion the shipped unit already implies — MemoryMax=1G with a 256 MB pool — so the default hardware is unchanged by construction. A const assertion in the source fails the build if either number moves without the other.
• 64 MiB was measured, not chosen. A sessionisation shaped like the behavioural queries — lag and a running sum over 1.5 million detections partitioned by species, then aggregated — ran out of memory at 8, 16 and 32 MiB and succeeded from 48 MiB up on DuckDB 1.5. 64 MiB is the next step above the smallest observed working value.

Threads. Unset, BIRDNET_DUCKDB_THREADS becomes the CPUs this process may run on less the two the bird classifier uses, and at least one — 2 on a Raspberry Pi 4. DuckDB’s own default is every core, whatever the process’s CPU affinity. Measured on a 4-core x86 host with two busy loops standing in for the classifier, two threads halved the slowest dashboard query against one and slowed the competing load no more than one thread did (84–104 % of its idle rate, against 85–100 %); four threads were about a fifth faster again but cut the competing load to 62–75 % and used more memory. Set the variable to override, for example on a station that only serves dashboards.

What is not measured is the rest of the process’s footprint on a Raspberry Pi, which would need a Pi. So this sizes a proportion, not a budget: it makes the analytics engine’s share scale with the machine, and does not claim to know the remainder is enough. --doctor reports which case applied under Analytics memory.

Metrics & logs

• Prometheus metrics are exposed at /api/v2/metrics.
• A live log viewer (/admin/system/logs/page) streams the service log over SSE with level filtering. A connecting client is replayed the last 200 lines first, so you see what led up to now rather than only what happens next. This is the whole picture in Docker, where there is no journalctl to fall back on.
• errors.jsonl, beside the database, keeps ERROR and WARN lines only, one JSON object per line, capped at 1 MB. It exists because a default Raspberry Pi OS has no /var/log/journal: the journal is volatile, so every watchdog bounce, power cut and update erases the evidence of what caused it — including the reboot you are trying to explain. --support-bundle carries this file.

If you ran an earlier version. The log viewer streamed nothing at all. Its backing channel existed and the page connected to it, but no tracing layer was ever installed, so it replayed an empty backlog and then emitted keep-alives for ever. The page now shows what the station logged.

CPU profiles

When the station is busier than it should be and nothing above says why, a CPU profile does: what every thread was doing, sampled 99 times a second. It is not in the release binaries — build with the profiling feature (cargo build --release --features profiling, or BUILD_FEATURES=analytics,profiling for the Docker image) — and an administrator then asks for one:

https://<station>/admin/debug/pprof/profile?seconds=30

The browser downloads cpu-<date>.pb.gz, which go tool pprof, pprof and Speedscope open. Add &format=folded for plain text, one line per stack (thread;outermost;…;innermost count), which Speedscope and flame-graph tools also read. seconds may be 1 to 120 (default 30).

Nothing samples until a profile is asked for, and one is taken at a time — a second request meanwhile is refused with 409. While one runs the station spends a little time in the sampler, so ask for a profile when there is a problem to look at rather than leaving a monitor polling it. Viewer accounts are refused. There is no heap profile: one would need a different memory allocator in every build.

Audit log

/admin/audit records who changed what. Rows are kept for 180 days and pruned by the maintenance loop.

Actions are dotted and hierarchical, so the page’s filter selects a family with a prefix — auth.% for every sign-in, species.% for every filter change:

The detection. rows are written for the same change whichever way it was made, and say which way: via=api for the write API, otherwise via= the page (today, recordings, search, review, detection). Search’s bulk bar records one row per detection it changed. A change that did not happen (a row already gone, a write the database refused) records nothing; a refused write is in the log at warn.

species.detections.delete and species.clips.delete are the bulk actions on Species storage. Each records how many rows it changed and how many locked detections it deliberately kept, so the log explains a count that would otherwise look wrong.

A failed sign-in records the submitted username and no actor — “someone tried to sign in as admin sixty times last night” is the thing worth knowing, and a username that does not exist is as interesting as one that does. login.throttled is an attempt the station refused without checking the password: after five failures from one address inside fifteen minutes, that address is answered 429 until its oldest failure is a quarter-hour old, and each refused attempt is recorded here too. A successful sign-in clears the address; a restart forgives everything.

Values are never recorded. A settings save lists the names of the keys that changed and nothing else. rtsp_url is why: an RTSP URL routinely carries user:pass@ in its authority, and this page renders its rows verbatim. A save that changed nothing writes no row at all, because the settings form posts every field on every submission and recording each one would turn the log into a click counter.

Destructive actions — clearing detections, restoring a database, restarting, applying an update — are recorded before the work starts, not after. If the process does not survive the operation there is no “after” to record from, and a station whose history vanished with nothing in the audit log is indistinguishable from one that was never used.

If you ran an earlier version. This page was permanently empty. The table, the store, the page and the 180-day pruner all existed, and the one function that writes a row had no callers outside its own tests — so on a shared station the page did not read as “the log is broken”, it read as “nothing happened”.

Tuning Detection Accuracy

Out of the box BirdNet-Behavior is tuned to be sensible. But every station is different — a noisy roadside, a quiet woodland, a single mimic that fools the model — and you can dial it in. This page explains what each knob does and which way to turn it.

The golden rule: change one thing at a time, then watch the Quality dashboard and your Today log for a day before changing the next.

The two failure modes

If you’re getting both at once, it’s almost always an audio problem (wind, clipping, a bad mic position) — fix that first on the Audio page before touching detection settings.

The knobs, in the order you should reach for them

1. Confidence threshold

The minimum score (0–1) a detection must clear to be logged. This is your main dial.

• Default 0.70, which is BirdNET-Pi’s own (it was 0.75 up to v0.17.1). Raise toward 0.8–0.85 to aggressively cut false positives (you’ll lose some faint genuine calls).
• Lower toward 0.5–0.6 only if you’re confident your audio is clean and you want maximum recall.
• Set it at /admin/settings → Detection.

2. Per-species thresholds

One noisy species shouldn’t force you to raise the global bar for everyone. Override the threshold for individual species instead:

• A local mockingbird or starling logging junk? Give just that species a high threshold (e.g. 0.9).
• A rare bird you don’t want to miss? You can lower its threshold — but pair that with the quarantine queue (below) so each one still gets a human glance.

The Quality dashboard lists your lowest-confidence species — those are the best candidates for a per-species override.

3. Sensitivity

The BirdNET sensitivity parameter (0.5–1.5; also SENSITIVITY in birdnet.conf), with BirdNET-Pi’s meaning. It reshapes the confidence curve of a V2.4 model, whose raw scores are passed through a sigmoid with slope clamp(2 − sensitivity, 0.5, 1.5):

• Higher (→1.5) is a flatter curve. Every score moves toward 0.5, so at any confidence threshold above 0.5 fewer calls clear the bar, and the confidence you see for a strong call is lower.
• Lower (→0.5) is a steeper curve: strong calls score higher and more of them clear the bar.
• The default, 1.25, is a slope of 0.75: the same figure BirdNET-Pi gives a station with its defaults. A magpie whose raw score is 3.12 reads 91.2 % here and there.
• Most stations leave this at the default and tune the confidence threshold instead. Reach for sensitivity only when the threshold alone can’t find a good balance.
• It only affects BirdNET V2.4 models; the BirdNET+ V3.0 preview reports calibrated probabilities and ignores it.
• birdnet-go’s setting of the same name is the slope itself (its default, 1.0, is a plain sigmoid). To carry a birdnet-go value across, enter 2 − value.

4. Species-frequency (SF) filter

Uses your location and the week of the year to drop birds that shouldn’t plausibly be present (no penguins in your back garden in July). The SF_THRESH (default 0.03) sets how aggressive that prior is.

It needs your coordinates and an occurrence model that matches the classifier:

• BirdNET V2.4 (the default for a new install) pairs with the range filter v2, birdnet-v24-range-v2.onnx (about 30 MB). It is indexed like the V2.4 labels, so it needs no label file of its own.
• BirdNET+ V3.0 pairs with the BirdNET geomodel and that model’s own label file (about 14 MB together).

The two pairs are never mixed. The installer and the Docker entrypoint fetch the right one and wire it up, so on a current install the only thing you supply is the location. The rest of this section is mostly about the geomodel pair, because that is the one with a second label file to align.

Check it is actually on — SF_THRESH does nothing by itself:

$ birdnet-behavior --doctor | grep occurrence
[ PASS ] Species occurrence filter - active - .../BirdNET+_Geomodel_V3.0.2_Global_12K_FP32.onnx ...

(That line is a V3.0 station’s; a V2.4 station’s names the range filter and says it is indexed against the classifier’s labels.) A WARN there names whichever of the missing pieces it needs: the model, or the coordinates. The geomodel download is deliberately non-fatal: a station without it still detects, it just stops filtering by location, and re-running install.sh repair picks it up later.

The model takes (latitude, longitude, week) and returns one occurrence probability per species. It does not score the same species list as the classifier — the geomodel covers 12 012 species across birds, mammals, insects, amphibians and reptiles, where the V3.0 Global 11K classifier emits 11 560 — so the label file is what maps one list onto the other.

Omit the label file only for a metadata model indexed identically to the classifier (a matched BirdNET pair, e.g. a V2.4 MData model beside V2.4 labels). The station checks that at startup and refuses a mismatched model rather than reading one list’s index into the other, which would report birds under other birds’ names with full confidence.

When the two files disagree about a name

The two label files were frozen at different points in a moving taxonomy, so they do not always spell a species the same way. On the pinned pair, 1 679 of the geomodel’s 12 012 rows have no exact scientific-name counterpart in the classifier — and 62 of those are the same bird under a reclassified genus. The geomodel says Leuconotopicus villosus where the classifier says Dryobates villosus; both mean Hairy Woodpecker.

Matching on the scientific name alone, those 62 species are permanently undetectable while the occurrence filter is on: the geomodel’s opinion about them never reaches the passing set under a name a detection can carry. Forty-one of them are birds, among them Hairy Woodpecker, Red-cockaded Woodpecker, White-headed Woodpecker and Evening Grosbeak.

So a name that does not match exactly is tried a second way: the common name, compared on its letters alone so Fruit-Dove and Fruit Dove are one name, together with the specific epithet, which must agree exactly or differ only by its Latin gender ending (gymnocerca / gymnocercus). A common name that names two species in either file identifies neither and is not used, and a species the scientific-name pass already matched is never re-matched by the looser rule.

The epithet is what makes that rule safe rather than merely generous. The classifier’s own label file calls Lama glama — the llama — “Guanaco”, and calls Scapteriscus borellii “Southern Mole Cricket”, which the geomodel uses for a different genus entirely. Both would match on the common name alone; neither matches once the epithet has to agree.

--doctor reports the result, in both directions:

$ birdnet-behavior --doctor | grep occurrence
[ PASS ] Species occurrence filter - active - ... ; 10395 of the metadata model's
12012 species map onto the classifier (62 by common name + epithet, 0 by an operator
alias, e.g. Drymomantis fallax = Litoria fallax), 1617 do not, and 1165 of the
classifier's 11560 species are reached by no metadata row and so cannot pass
while it runs

Read those two residues differently. A metadata species with no classifier counterpart is almost always right — the geomodel simply knows more species than the classifier can emit. A classifier species that no metadata row resolves to is one this station cannot report at all while the filter is on, because the geomodel has no opinion to offer about it.

Your own aliases

For a pair the automatic rules cannot connect — different genus and different common name — point SPECIES_ALIASES_PATH (BIRDNET_SPECIES_ALIASES, --species-aliases) at a tab-separated file:

# legacy name (as the geomodel spells it)	the classifier's name
Streptopelia senegalensis	Spilopelia senegalensis

Blank lines and # comments are skipped, and a malformed line is skipped rather than taken as fatal: a typo here must not take the occurrence filter off a running station. The count loaded and the number of lines skipped are logged at startup.

No alias table ships with the station. The obvious candidate, OpenFauna’s aliases.json, is CC BY-SA 4.0 where this project is CC BY-NC-SA 4.0, and ShareAlike does not permit adding the NonCommercial restriction. It would also not help: applied to the pinned model pair, all 237 of its entries recover none of the 1 679 unmatched rows, because the reclassifications it records are ones both of our label files already agree on. If you want it anyway, it is yours to install under its own licence.

Once it is running:

• Make sure your latitude/longitude are correct first — the filter is only as good as your coordinates.
• Raise SF_THRESH to be stricter about out-of-range species; lower it (or 0) to let everything through (useful if you want to catch vagrants).

5. Rain, wind and other broadband noise

Nothing in the station drops rainy or windy audio before it reaches the model. Weather shows up as false positives, and the levers are the ones above: a modestly higher confidence threshold, a per-species threshold for the species it keeps producing, and the noise filter in §7 for a recurring non-bird sound. The cheapest fix is at the microphone: a windshield and shelter from direct rain do more than any setting. The Quality dashboard lists the species whose confidence is lowest, which is where weather-driven false positives collect.

6. Rare-bird quarantine

Rather than choosing between “log everything” and “miss the rarities,” send borderline rare birds to the quarantine queue for a quick human approve/reject. This lets you run a lower threshold for rare species without polluting your life list.

7. Barking dogs and other non-birds

BirdNET’s label set is not birds only — it carries Dog, Siren, Engine, Fireworks, Power tools, Gun, Environmental and Noise, because the training data contains them. A dog barking near the microphone is broadband enough that the classifier does not answer Dog and stop: it also produces confident-looking scores for whatever species the bark most resembles. Because the barking is regular — same dog, same garden, every evening — the phantom accumulates until it looks like a resident.

BIRDNET_NOISE_THRESHOLD=0.6      # 0 = off; typical 0.5–0.8
BIRDNET_NOISE_CLASSES=Dog        # unset = Dog; empty = watch nothing

When a watched class scores at or above the threshold, every detection in that three-second chunk is discarded. Only that chunk — a bark is a few hundred milliseconds, and the chunks overlap, so a bark on a boundary is caught in both. Beside a road or a fire station, add Siren and Engine. Do not add Noise or Environmental: they score highly on ordinary quiet recordings and will suppress most of the night.

That handles the barks. It does not handle the gaps between them, and for a dog that barks for a minute the gaps are where the damage is: no Dog above threshold, nothing for the filter to fire on, and the classifier — still hearing the tail of the bark and the room — producing the same phantom species it produced during it. The filter silences the barks and lets the gaps through.

NOISE_REMEMBER_SECS=45           # 0 = off, the default

After a chunk is suppressed, the species that were in that chunk stay suppressed for this many seconds. Only those species: a blanket window would be a mute button, and a dog barking through the dawn chorus would erase the chorus. A blackbird singing in the same gap is still recorded.

It is off by default because it does remove real detections whenever a real bird happens to be the species a dog resembles. Reach for it when a regular dog is filling your log with one particular phantom; 30–60 seconds is a sensible starting point.

It reaches to the end of the recording being analysed and no further. Carrying it across segments would mean state on a filter that every audio source shares, and a bark on the garden microphone must not silence a species on the pond one.

8. One song, one detection

A 15-second recording is five 3-second chunks, so a bird singing throughout is recorded five times. Every count in the application is a row count — daily totals, the activity heat map, the dawn-chorus curve — so a species that sings in long phrases outscores one that calls in short bursts for no reason but phrasing.

BIRDNET_DUPLICATE_INTERVAL_SECS=30   # 0 = off

Each species is then admitted at most once per interval on each source (the microphone, or each RTSP camera); the first chunk wins, because that is when the bird started singing. Two cameras that hear a bird 20 seconds apart each record it: they are two places. A station with one source behaves as if the interval were per species. Off by default, since turning it on changes how many rows your station records and puts a visible step in every chart on the day you do it.

One species louder than the rest. A tawny owl calling all night will drown the log long before a blackbird does. Settings → Capture → Which birds count → Per-Species Minimum Interval gives a single species its own interval in seconds (1 to 86400), which replaces the station-wide one for that species and applies even when the station-wide one is off — the same behaviour as birdnet-go’s per-species interval. A repeat inside it is dropped like any other duplicate: no row, no clip, no notification, not counted. The window runs from the last recorded detection, a detection quarantined by a threshold does not start one, and the setting is picked up within about thirty seconds, no restart. It is separate from the notification cooldowns, which only ever limit messages and never rows.

9. Day birds at night

A blue tit “detected” at 02:30 is almost always the model hearing something else. A blanket night filter would be worse than the problem — owls, nightjars, rails and bitterns call at night on purpose and are the detections most worth having — so the filter asks who, not just when.

BIRDNET_NIGHT_FILTER=1
BIRDNET_NIGHT_MARGIN_MINS=60
BIRDNET_NIGHT_EXTRA_NOCTURNAL=Catharus,Vireo

Species in a genus known to call at night are exempt; everything else detected between sunset + margin and sunrise − margin is sent to quarantine, never dropped, because the taxonomy is genus-level and cannot be complete. It needs your station coordinates, and it fails open: no coordinates, an unreadable timestamp or a polar summer all mean “keep everything”.

If you record nocturnal flight calls, leave this off — migrating thrushes and warblers calling overhead are exactly what it would quarantine — or name those genera in BIRDNET_NIGHT_EXTRA_NOCTURNAL.

10. Asking for a second opinion

A real bird sings across more than one analysis window. A classifier artefact — a car door, a squeak of the mount, a fragment of speech — usually fires in exactly one. The repeat-confirmation filter uses that: a species is recorded only if enough of the windows around it heard the same thing.

BIRDNET_OVERLAP=2.0                 # required — see below
BIRDNET_CONFIRMATION_LEVEL=lenient  # off | lenient | moderate | balanced | strict

Each level names the fraction of the windows within six seconds that must carry the species — 20%, 30%, 50%, 70% — rounded up, and never fewer than the detection itself.

It does nothing without BIRDNET_OVERLAP. With no overlap, six seconds is two 3-second windows, and 20% of two rounds up to one — which every detection already satisfies. How much overlap each level needs:

--doctor reports which of these you are in, and the daemon logs a warning at startup when the level you set cannot reject anything at your overlap — so a setting that does nothing tells you, rather than looking like the filter working.

Overlap is not free: OVERLAP=2.0 triples the number of windows and therefore the inference work per recording. On a Pi 4 or smaller, watch birdnet_files_analysed_total against the segment rate (about 5 760 a day per source at 15 s) after turning it on — a rate that falls behind means the board is not keeping up.

Start at lenient. strict on a station recording distant or intermittent singers will lose real detections — a bird that calls once and moves on is indistinguishable, to this filter, from an artefact.

Letting the station tune itself

Two places on the web UI turn your own review history into advice. Both only ever suggest; nothing changes until you press the button.

Suggested thresholds (Settings → Capture → Species). For each species you have both confirmed and rejected detections of, the station works out the threshold that best separates the two, and shows what it would have cost (confirmations lost) and caught (rejections stopped) against the reviews it came from. Suggestions that separate nothing are not shown — if your reviews and the model’s confidence disagree at random, there is no threshold worth applying.

The more detections you review, the better this gets. Reviewing a mix of good and bad detections for one species is worth far more than reviewing many of either alone: with only confirmations the best answer is “admit everything”, which is not a threshold.

Species that may not be birds (Settings → Data). Flags species by the shape of their detections rather than by name: every review rejected, never detected confidently, confidence that never varies, many detections on very few days. Two of those signals have to agree before a species is listed, and it needs at least 10 detections first, so a genuine scarce visitor is not flagged on the day it arrives. The Exclude button adds it to the ordinary species exclusion list, where you can undo it.

If you have configured eBird, a flagged species that somebody else reported near you recently is marked as such, and the Exclude confirmation says so — somebody standing near your microphone wrote that bird down, which is about the strongest argument there is against excluding it. The reverse does not hold and the station never pretends it does: eBird saying nothing about a species means nobody nearby submitted a checklist with it, which is the normal state of affairs anywhere without many birdwatchers. An unmarked row is not a row eBird disagrees with.

A recommended starting recipe

1. Set your location accurately.
2. Get mic levels right (peaks near −6 dB).
3. Run the defaults for a few days and read the Quality dashboard.
4. If false positives dominate: nudge the confidence threshold up by 0.05, and use the noise filter if a particular non-bird sound (a dog, a siren) is the cause.
5. Add per-species overrides for the one or two species generating the most noise.
6. Turn on quarantine for rare birds so you can keep recall high without losing trust in the log.
7. Review a mixture of good and bad detections for a week, then check the suggested thresholds on the Species page and the suspect species list under Settings → Data — by then both have something to say.

Everything here is reversible and stored in the database, so experiment freely — and remember to change just one knob at a time.

Same audio, same detections

If you ran BirdNET-Pi for years and trust what it told you, you should be able to move here and see the same birds for the same sounds. This page says what that takes, what was measured, and where the three projects differ whatever you do. BirdNET-Pi here means Nachtzuster’s fork at 88985a3; birdnet-go means tphakala/birdnet-go at f4f019a.

Same model does not mean same detections, even between BirdNET-Pi and birdnet-go. They run the same BirdNET V2.4 network and differ in how a score becomes a stored row (the table below). This project is held to BirdNET-Pi, because that is where its users and its settings file come from.

What you get out of the box

A new install runs BirdNET V2.4 with its range (occurrence) filter v2, and the three settings that decide what becomes a stored row default to BirdNET-Pi’s own values:

BirdNET+ V3.0 preview, which releases up to v0.17.1 installed for everyone, is a different network: it listens to 4.5 s windows (V2.4: 3 s), reports calibrated probabilities (V2.4: raw scores that SENSITIVITY reshapes), and names about 11 500 species (V2.4: 6 522). Its detections are not BirdNET-Pi’s and are not meant to be. Choose it with --classifier birdnet-v3 (see Installation) if you want the newer model. Two defaults here are tuned to V2.4 and say less on V3.0: SENSITIVITY is ignored (V3.0 reports calibrated probabilities), and the human-sound rule hardly fires (measured below: 0 of 31 windows of read speech).

Two things to know if you are upgrading rather than installing:

• The classifier is not changed. A station that has a configuration keeps the classifier that configuration names, and a Docker volume that holds the V3.0 model keeps V3.0.
• Two defaults move with the binary. A station that never set CONFIDENCE (not in birdnet.conf, not saved on the Settings page or in the onboarding wizard) now records at 0.70, not 0.75. A station that sets neither PRIVACY_RANK nor PRIVACY_THRESHOLD now has the human-sound rule on, where before nothing was suppressed: a window in which a human class ranks in the model’s top 10 classes, and the windows either side, are not recorded. Set PRIVACY_RANK=0 to switch it off.

Moving an existing station to BirdNET-Pi’s results

Install the two files (Docker: docker compose exec birdnet birdnet-behavior --install-model …; on bare metal name the model folder, as Installing one shows):

birdnet-behavior --install-model birdnet-v24            # classifier + labels
birdnet-behavior --install-model birdnet-v24-range-v2   # species-occurrence filter

Then, in birdnet.conf (or the BIRDNET_* variables), and restart. <model dir> is /data/model in Docker and <data dir>/models on bare metal:

MODEL_PATH=<model dir>/birdnet-v24.onnx
LABELS_PATH=<model dir>/birdnet-v24_labels.txt
METADATA_MODEL_PATH=<model dir>/birdnet-v24-range-v2.onnx
LATITUDE=…            # needed by the range filter, as in BirdNET-Pi
LONGITUDE=…
CONFIDENCE=0.70       # BirdNET-Pi's default; this project's from the first release after v0.17.1
SENSITIVITY=1.25      # the same number, with the same meaning, as BirdNET-Pi's
SF_THRESH=0.03        # the same
OVERLAP=0.0           # the same
PRIVACY_RANK=10       # the same rule; see below

With those, a V2.4 station stores BirdNET-Pi’s species at BirdNET-Pi’s confidences for the same audio, to the tolerances below. The last four lines are the defaults; they are written out so that a value you changed earlier is visibly put back. The one setting that does not carry across unchanged is BirdNET-Pi’s PRIVACY_THRESHOLD.

Migrating a PRIVACY_THRESHOLD. BirdNET-Pi reads the key as a percentage of the species list: a window is human if a human class ranks within the top max(10, 60 × value) classes. Here PRIVACY_THRESHOLD is the model’s own confidence for a human sound, and the rank rule has a key of its own. For a BirdNET-Pi value p, set PRIVACY_RANK=max(10, 60 × p) and PRIVACY_THRESHOLD=0 (so p=0 gives 10, p=1 gives 60 and p=10 gives 600). A BirdNET-Pi 1 left in PRIVACY_THRESHOLD is in range here, validates clean, and then masks nothing short of certainty; --doctor warns about any value above 0.5 and says this. PRIVACY_RANK accepts 0 (off) to 12 000, as --privacy-rank and BIRDNET_PRIVACY_RANK as well as the config key. It is the Privacy Rank field in the Detection section of the Settings page (/admin/settings; blank = the default, 10), and it can still be set in the file, the environment or on the command line. Either rule suppresses a window: PRIVACY_THRESHOLD (0 = off, typically 0.01–0.03 when used) is a second, independent rule on top of the rank rule.

The commit that added PRIVACY_RANK (6888399) reports its decision agreeing window for window with BirdNET-Pi’s own masks on 13 of the 14 parity clips with the real V2.4 model, including all four speech windows; the fourteenth is the synthetic clip’s digital-silence tail, which is already listed below as disagreeing between every pair of model builds. That comparison is tools/parity/compare_rust.py (its privacy column); it was re-run for this page and gives the same 13 of 14 clips (52 of 54 windows).

What was measured

Everything below was produced by a command in tools/parity and re-run for this page; tools/parity/README.md lists the commands. The reference is BirdNET-Pi’s own, unmodified code (88985a3) running its V2.4 FP16 TFLite model. Two sets of recordings went through it and through this project:

• The first set, 14 clips (54 analysis windows): a magpie, a binaural dawn chorus in several formats and lengths, a tawny owl, a crow, a spoken-word recording, synthetic silence and noise.
• The second set, 106 clips (900 windows, 30 s each except 20 five-second clips): 49 geotagged field recordings picked from the archive.org radio aporee collection by title keyword only (dawn chorus, rain, wind, night, frogs and insects, crowds and speech, traffic, water, waterbirds, quiet), 29 more picked the same way by bird name, 20 sound-effect classes from ESC-50 (birds, other animals, weather, machines, human sounds), 4 LibriVox speech excerpts and 4 generated clips (pink noise, a 1 kHz tone, a clipped square wave, digital silence). 40 of the 106 are 44.1 kHz and had to be resampled. BirdNET-Pi stores 79 rows on them, on 18 clips.

Nothing in either set was chosen for what BirdNET hears in it; the selection is in search_extended.py. The audio is not in the repository; fetch_fixtures.py rebuilds every clip and checks its sha256.

What a station stores: the real service, end to end

A fresh-install configuration (the file installer/lib/62-config-file.sh writes, with the station’s coordinates, and the two model files --install-model fetched and verified) in an empty directory, the real binary started the way the systemd unit starts it, each clip dropped into the watch directory under a YYYY-MM-DD-birdnet-HH:MM:SS.wav name, and the rows read back from SQLite:

The one extra row is a robin in a 44.1 kHz recording: BirdNET-Pi’s score for that window is 0.6931 (below 0.7), this project’s 0.7025. Running BirdNET-Pi’s FP16 model on this project’s own input gives 0.6926 and this project’s FP32 model on BirdNET-Pi’s input gives 0.7024: it is the FP16 weights, not the pipeline, and a window that close to the bar can go either way. On the 91 rows both stored, the confidences differ by at most 0.0067 (the 22.05 kHz clip; 0.0040 otherwise), mean 0.0007. The species name, the common name, the date and time (file time plus the window’s start) and the clip’s file name come out the same. With OVERLAP=1.0 and 2.0 the magpie recording stores 5 and 11 rows, the same windows as BirdNET-Pi (confidences within 0.0007); overlapping windows are not merged here, as they are not there.

Before the resampler fix described below, the first set stored 11 of those 12: a borderline great tit in the 44.1 kHz clip (BirdNET-Pi 0.7113, here 0.6564) was missing.

What is stored differently, whatever the audio. The Confidence column holds the score as computed (0.9122954607); BirdNET-Pi rounds to four places (0.912, in its own test). The Week column holds this project’s 48-week-year week (7 where BirdNET-Pi writes the ISO week 8, 18 where it writes 20, 12 where it writes 13), because that is the week the range filter is asked about; it is not an ISO week, so a query that groups imported and native rows by week mixes two calendars.

Stage by stage

Every remaining difference, with its cause

The decomposition below runs BirdNET-Pi’s FP16 TFLite model and this project’s FP32 ONNX model on the same chunk, then on each side’s own chunk (tools/parity scratch script; the numbers are logits).

• Digital silence and zero-padded tails: inherent to the two builds of the model. On a recording’s zero-padded last window the two get identical input (difference 0.0) and still differ by 0.79 and 0.62 in raw score (the 7.5 s and 7.6 s clips); on the all-zero window of the synthetic clip by 0.37, and the human class ranks 3 here and 591 there. The V2.4 graph rescales every window by its own range, so a constant window becomes rounding noise and the two builds’ rounding differs. Real recordings contain neither, but a microphone that drops out does: a digital-silence window is masked here (its human class ranks 3rd) and so are its neighbours, and BirdNET-Pi’s is not (rank 591), so a bird next to a dropout can be lost here and kept there. 10 windows in the second set, one clip (the other 4 digital-silence windows, ESC-50’s padding, agree).
• Atypical non-bird sounds: inherent. The largest gaps in ordinary windows (1.34 on a cough, 1.16 on every window of a pure 1 kHz tone, label Siren) are the same on identical input: the two builds differ by that much on content a bird model never sees. None is near a threshold.
• Weights: inherent. On identical input the FP32 and FP16 builds differ by a median 0.009 and, at the 99th percentile, 0.37 in raw score. That is what moves the robin from 0.6931 to 0.7025.
• A quiet, band-limited recording that had to be resampled: inherent sensitivity, triggered by the resampler. The 22.05 kHz version of the first set’s dawn-chorus clip has one window (3 to 6 s) whose raw score for one label differs by 1.55. Its resampled input differs from BirdNET-Pi’s by 0.96 % RMS (at most 1.8 least-significant bits of 16); on identical input the two models differ by 0.006, and feeding either model the other resampler’s input moves it by 1.54. BirdNET-Pi’s own model moves that much for an input change that small on a very quiet window. No stored row changes.
• The resampler (fixed). The earlier version of this page called the 28 % input difference on the 44.1 kHz clip “the model’s sensitivity to a nearly silent input, not a fault in either resampler”. It was a fault in this project’s: the resampling library delays its output by 128 x ratio - 1 samples, the code removed only the whole-sample part, and every recording whose rate is not 48 kHz arrived early by 0.69 sample at 44.1 kHz (0.38 at 22.05 kHz, 0.67 at 48 to 32 kHz, 1.0 at 32 to 48 kHz). Shifting this project’s chunk by the measured 0.689 sample moved the raw score from 0.863 back to 1.201 (BirdNET-Pi: 1.202). The delay is now made a whole number and removed; the remaining 0.005 to 0.017 sample is the library’s own interpolation grid. BirdNET-Pi’s recorders write 48 kHz, so most stations never resample; RTSP streams, uploaded files and 32 kHz (V3.0) analysis do.
• Fractional OVERLAP (not fixed, tiny). BirdNET-Pi computes the step as int((3 - overlap) x 48000) in 64-bit floats; this project as 3 x 48000 - int(overlap x 48000) in 32-bit. For 14 of 59 overlaps in steps of 0.05 the step differs by one or two samples (0.7: 110 399 against 110 400), which cannot matter, except that when the last window would hold exactly the 1.5 s minimum the extra sample decides whether it exists: 48 of 9 145 combinations, never at OVERLAP=0, and for a 15 s segment only at 2.10.

The default V3.0 path, against an independent reference

There is no BirdNET-Pi to compare V3.0 with, so tools/parity/v3_reference.py is a reference that shares no code with the pipeline: soundfile, a plain-mean mono mix, soxr (not rubato) for the resample to 32 kHz, slicing into 4.5 s windows, onnxruntime. It was run on all 120 recordings of both sets and compared with tests/parity_dump.rs on the V3.0 model: 119 recordings give a comparison (the digital-silence clip makes the model output NaN in the reference; this project treats a non-finite score as 0), 655 windows, the same window count on every recording. The top species is the same in 650 of 655 windows; the five that are not are every window of the pure 1 kHz tone, where two species tie at 0.026. On the 650 windows with the same top species the probabilities differ by a median 0.00003, a 99th percentile 0.0003 and at most 0.0040; the 200 of them that score 0.7 or more differ by at most 0.0040. This checks the front end (decode, resample, window) and the confidence mapping of the default model; it does not say V3.0 identifies birds better or worse than V2.4.

What the human-sound rule does on V3.0

The rule is BirdNET-Pi’s, written for V2.4, where a window of speech puts a human class among the model’s ten best. On the same 91 clips the rule masks 246 of 665 windows (37.0 %) on V2.4 and 18 of 459 (3.9 %) on V3.0. On the five LibriVox speech clips it masks 26 of 44 windows on V2.4 and 0 of 31 on V3.0, on three ESC-50 laughing, coughing and crying clips 6 of 6 and 0 of 3, on five crowd recordings 41 of 50 and 7 of 35. On one of those speech clips V3.0 gives its human classes a probability of 0.002 or less in all seven windows (rank 12 to 55 of 11 560 classes), so a confidence threshold would not catch it either (PRIVACY_THRESHOLD 0.01 to 0.03 is below that). On a V3.0 station the default does not keep conversation out of the table, and a station that opted into V3.0 should not rely on it for privacy. Nothing in this project measured a setting that does.

What is not the same, whatever you do

With the defaults above, a default station still differs from BirdNET-Pi’s in the ways below. Each was measured this session; tools/parity/defaults_audit.py prints the full table of defaults with the file and line of every cell (a copy is in tools/parity/golden/defaults_table.md) (it refuses to run if a cited line no longer holds the cited text).

birdnet-go was not run. Applying its rules (score sigmoid(logit), strictly above 0.8 or 0.7, one row per species per 15 s, human classes dropped, no range filter, no adaptive threshold) to this project’s model outputs on the 77 recordings of the second set that both sides cut would store 18 rows (threshold 0.8) or 24 rows (0.7) where BirdNET-Pi stores 27 (tools/parity/birdnet_go_estimate.py). It is an estimate of what the rules do to the same scores, not a measurement of birdnet-go, and the two are not interchangeable in either direction.

The range filter: lists differ on almost every day. Three things differ at once between BirdNET-Pi as installed and a new install here: the model (MData v1, v2), the week it is asked about (ISO, 48-week), and nothing else. Measured on eight stations (London, Ithaca, Helsinki, Sydney, São Paulo, Nairobi, Hokkaido, Austin) for every day of 2024, 2026 and 2028 with BirdNET-Pi’s own range models (tools/parity/golden/range_calendar.json, SF_THRESH 0.03):

• The calendar alone (BirdNET-Pi with v2 and its ISO week against this project): the lists differ on 219 to 341 days of the year depending on the station and the year (2026 has an ISO week 53), by a mean of 5 species (Sydney) to 33 (Ithaca), at most 185 species on one day. This is not only a December effect: an ISO week number between 1 and 48 is read by the model as the same-numbered week of a 48-week year, which is up to four calendar weeks away. Weeks 49 to 53 give the model no season, and it answers with one year-round list about twice as long as any real week’s.
• The model alone (v1 against v2, same ISO week): different on every day, by a mean of 17 species (Helsinki) to 141 (São Paulo), because v2 admits many more species in the tropics.
• Both together, BirdNET-Pi as installed against a new install here, symmetric difference a mean of 29 (Helsinki) to 142 (São Paulo) species; admitted by BirdNET-Pi only, a mean of 1.5 (Sydney) to 35 (Hokkaido) species; by this project only, 10 (Helsinki) to 132 (São Paulo). The ranges cover all three years.

What that does to stored rows was not separable in the recordings tested: BirdNET-Pi’s rows are the same under v1/ISO, v2/ISO and v2/48-week on all 120 clips (79 rows on the second set, 12 on the first), because the birds in those recordings are common ones all three lists admit. The 120 clips do not contain a species that falls between the lists, so the effect on a station’s rows for a rare or out-of-season bird is unmeasured; the Species, Why isn’t a bird heard here? page shows it for any bird.

No location set. BirdNET-Pi’s installer asks ip-api.com for a location and falls back to 0.0, 0.0 when that fails (tools/parity/README.md). At 0.0, 0.0 with the v1 filter and SF_THRESH 0.03 the filter admitted 468 species at ISO week 8, and BirdNET-Pi’s own Pica pica test recording produced no detections (tools/parity/golden/matrix/a0_shipped_literal.json: detections: [], mdata.count: 468). Here a station with no coordinates stores all three magpie rows and a station with 0.0, 0.0 typed in stores none (run for this page on the real binary). No installer, quick-start script or default here writes 0.0, 0.0.

Species lists. birdnet-go’s species.include is a different thing from BirdNET-Pi’s include list: it means “always include these despite the range filter”, which is BirdNET-Pi’s whitelist. A list carried over by name from one to the other flips meaning. Here the three lists mean what they mean in BirdNET-Pi. (27 scenarios through BirdNET-Pi’s own run_analysis, same files read by the importer): include and exclude by scientific name, the Scientific_Common lines the species picker writes, CRLF and padded lines, a whitelist that rescues a species the occurrence list rejects, the whitelist that loses to an exclude or an include list, an exclude that beats an include, and SF_THRESH 0 and 0.5 all agree (21 scenarios). They differ where BirdNET-Pi’s include list is a wall that a bad entry turns into “record nothing”: an include list holding only a typo, only a common name, only a lower-case name, or only a blank line makes BirdNET-Pi record nothing at all, and makes this station ignore the list and record everything (4 scenarios); and SF_THRESH 1.0, where the model admits no species at all, which BirdNET-Pi reads as “filter off” and this project as an empty allow-list (2 scenarios).

File names. Of 33 names put to BirdNET-Pi’s ParseFileName and to this project’s parser, the date, time and RTSP id agree on every name both read. BirdNET-Pi also reads 2026-2-16-birdnet-…, a time without a leading zero, no or differently-cased birdnet, and no extension (this project refuses them). And this project reads six names that BirdNET-Pi rejects with an error and skips: a date or time that is not real (2026-02-30, 2025-02-29, month 13, 25:00:00, minute 60, second 60). It then stores their rows under the name’s date and time as written (2026-02-30 as 2026-03-02, 25:00:00 as the time 25:00:00); only a hand-named file can have such a name. At the year boundary BirdNET-Pi calls 31 December 2026 and 1 January 2027 both ISO week 53 and this project calls them weeks 48 and 1 of its 48-week year.

Other things that can keep a row out of the table here: a recording dated before 2024 or after 2063 is quarantined rather than stored; when more than 40 segments are waiting, the CPU passes 80 °C, or a Pi reports throttling, every other segment is skipped and counted; and a file that is not named YYYY-MM-DD-birdnet[-ID]-HH:MM:SS.wav is refused. BirdNET-Pi does none of these.

Not measured

BirdNET-Pi’s FP16 model on a real Raspberry Pi; birdnet-go itself (only its source and an estimate above); any model other than V2.4 against a reference except V3.0’s front end; Perch and a second classifier; the effect on a station’s rows of the three range filters on a rare bird; recordings longer than 30 s; any rate other than 44.1 and 48 kHz on real recordings (22.05 kHz only on one clip); the numpy 1.x comparison (np.float32(0.7) >= 0.7 is false there, true under numpy 2, and no window sat on it).

Seeing what the range filter does

BirdNET-Pi has no page that says why a bird is missing; this station does. Species → Why isn’t a bird heard here? (/species/occurrence, and GET /api/v2/species/occurrence for scripts) asks the same range filter the detection loop uses, for the station’s location and any week of the model’s 48-week year, and says for each species whether it is admitted and why. It is the quickest way to see the December effect above: ask about the same bird in week 47 and in week 48. See Why isn’t a bird heard here?.

Checking it yourself

# the reference side: BirdNET-Pi's code and model, goldens in tools/parity/golden
tools/parity/regenerate.sh
# the first set, Rust side, against the first set's golden
PARITY_MODEL=… PARITY_LABELS=… PARITY_WAVS=a.wav:b.wav PARITY_OUT=out \
  cargo test --all-features --test parity_dump -- --nocapture
python3 tools/parity/compare_rust.py out/ours.json tools/parity/golden/matrix/a1_station.json
# the second set (106 clips): fetch, run BirdNET-Pi on it, run this project on it, compare with intervals
python3 -I tools/parity/fetch_fixtures.py DIR --manifest tools/parity/fixtures_extended.json --strict
python3 -I tools/parity/run_extended.py --pi-root PI --fixtures DIR --out OUT --as-year 2026
python3 tools/parity/compare_ext.py out/ours.json OUT/x0_pi_default.json
# every default, with its file and line, in all three projects
python3 tools/parity/defaults_audit.py --pi PI --go BIRDNET_GO --repo .

CI fetches the V2.4 model and range filter, checks their sha256, and runs the V2.4 tests on every change to the inference path: v24_matches_birdnet_pi, v24_range_filter_matches_birdnet_pi, v24_range_filter_every_week_matches_birdnet_pi, species_lists_match_birdnet_pi, chunking_matches_birdnet_pi, file_names_match_birdnet_pi and resampler_matches_resampy_parity.

Common Tasks

Short, copy-pasteable answers to “how do I…?” Each links to the page with the full story.

Get a phone alert when a rare bird shows up

1. Create an Apprise URL for your service (Telegram, Pushover, ntfy, Discord…).
2. Set it: BIRDNET_NOTIFY_URLS=tgram://bottoken/chatid (or via /admin/settings → Notifications). The station sends to Telegram directly — BIRDNET_APPRISE_URL is the base URL of an Apprise server, not a destination.
3. Set BIRDNET_NOTIFY_CONFIDENCE=0.85 so only solid detections ping you.
4. Use the rare-bird rules so you’re alerted on new or unusual species, not every robin.

See Notifications & Integrations.

Get one alert per species per day instead of per-detection pings

Choose the First of each species, daily trigger (--notify-trigger new-species-daily, in the onboarding wizard or /admin/settings → Notifications) to get one alert per species per day instead of one per detection. The trigger modes are each, new-species and new-species-daily; there is no evening-digest mode — the weekly report e-mail is the closest thing to one.

Keep a recording forever

Retention is disk-based — old clips are purged once the disk fills. Open the Today page (or a species’ recordings), and use the lock action on the detection. Locked clips are never purged. See Recording & Retention.

Fix a misidentified detection

On the Today page, use re-label on the row to correct the species, or delete it if it’s pure noise.

Cut down on false positives

Nudge the confidence threshold up — see the full Tuning guide. For a single noisy species, add a per-species threshold instead of raising the global bar.

Listen to last night’s owl

Go to Recordings, filter the Clips list to Rare (or search the owl’s name), pick the clip, and play it inline. The History calendar is the fastest way to jump to a specific night.

Add a second microphone or an RTSP camera

Use Cameras and streams on the Capture tab, or set BIRDNET_RTSP_URLS= with comma-separated URLs. You can run several sources at once.

Expose the dashboard to the internet (safely)

The dashboard is LAN-reachable by default (0.0.0.0:8502) — fine at home, where viewing is open and /admin is protected by the auto-generated password. For anyone else on the network, --tls-mode self-signed brings HTTPS up on 8503 with a certificate the station generates itself. But never port-forward either port straight to a public IP: encryption is not exposure-proofing, and a self-signed certificate carries no publicly-trusted name. Put it behind a reverse proxy with a real certificate and a password, or use a VPN — see Remote Access & Security. To restrict it to the local machine instead, set BIRDNET_LISTEN=127.0.0.1:8502.

Send detections to Home Assistant

Set BIRDNET_MQTT_HOST and BIRDNET_MQTT_HA_DISCOVERY=1. The station registers itself automatically and the latest detection appears as Home Assistant entities. See Integrations Reference.

Back up everything before an upgrade

Download a full backup from the Data tab and keep it off the station — the automatic snapshots run weekly and live on the station’s own card, so they will not help you if the upgrade takes the card with it. Take one manually right before you update.

Move my data to a new Pi

Download a full backup from the Data tab on the old Pi, install on the new one, and restore the archive there. Your detections, settings and recordings come across. Restoring overwrites whatever is on the new station, so do it before you start collecting on it.

Import my old BirdNET-Pi history

See Migrating from BirdNET-Pi — it’s a safe, read-only import at /station/data#import (the old /admin/migrate redirects there).

Migrating from BirdNET-Pi

You can move a BirdNET-Pi station here and keep what it had: its settings, its detection history and the recordings that go with it. Each is a step on the Settings → Data page (/station/data#import), each can be done on its own, and each has a command-line twin. Nothing is written until you have seen what it would do and confirmed it, and BirdNET-Pi’s files are never changed.

Three things are different from BirdNET-Pi on the first day, whatever you import. Read What changes whether you like it or not once.

Before you start

1. The sign-in is admin, not birdnet. BirdNET-Pi asks for the user birdnet and the password in CADDY_PWD. This station’s administrator is admin. The import does not copy your password (an import never writes one); set the password under Access, or, if you put your BirdNET-Pi birdnet.conf in place as this station’s own file, its CADDY_PWD becomes the password of admin the next time the station starts.

2. Stop BirdNET-Pi if it is on the same machine, so it is not writing while you copy:

   sudo systemctl stop birdnet_*
   

3. Find the files. In BirdNET-Pi’s folder, ~/BirdNET-Pi:

   File	Holds
   birdnet.conf	the settings (/etc/birdnet/birdnet.conf is a link to it)
   apprise.txt	where notifications go
   body.txt	the notification message
   include_species_list.txt, exclude_species_list.txt, whitelist_species_list.txt	the three species lists
   scripts/birds.db (or scripts/BirdDB.txt)	the detections

   and the recordings in ~/BirdSongs/Extracted/By_Date. If BirdNET-Pi is on another machine, copy these to a place this station can reach, or upload them from your browser.

Step 1 — your settings

On Settings → Data, under Bring your BirdNET-Pi settings, choose birdnet.conf and any of the other files (select several at once; they are recognised by their names), or paste the contents of birdnet.conf, or give the folder on this device. Press Show me what would change.

You get a table with a row for every key in your file: what it is called there, your value, what it becomes here, and what happens to it. Credentials are shown only as their length. The rows are:

Press Apply these settings and the same checks the Settings page runs are run over the whole set; if any value would be refused, none is written. Then restart the station if it says some settings need it.

The species lists are added to the lists this station already has, never replacing them, and apprise.txt is copied into the data folder (as apprise-from-birdnet-pi.txt, readable by the station only) and used as the Apprise configuration. That copy is not part of the full backup, which holds the database, birdnet.conf and the recordings: the setting that points at it is in the database, so a station restored from a backup onto another machine needs apprise.txt copied in again, or its notifications stop. The file is written (to a temporary name, then renamed into place) only after every setting has passed the Settings page’s checks, and just before they are saved. A second import applied after you have changed something by hand sets the BirdNET-Pi values again; the preview shows what each row replaces.

From a terminal, the same, looking only:

birdnet-behavior --import-birdnet-pi-conf ~/BirdNET-Pi

and with --apply-import it writes. It prints the same table, exits 0 when it showed a plan or finished, 1 when the settings would be refused (nothing written), 2 for a path it cannot use.

If you run --doctor on a birdnet.conf copied over as it is, every key BirdNET-Pi writes now draws an answer: the key to rename it to, the setting to use instead, or why there is nothing.

Step 2 — your detection history

BirdNet-Behavior imports an existing BirdNET-Pi history safely and non-destructively — the source database is opened read-only and no row of it is ever changed. (If it is in WAL mode, SQLite may create -shm and -wal bookkeeping files beside it while it is read; that is the other reason to stop BirdNET-Pi first. An uploaded file is held in migration-staging, next to this station’s own database, and removed together with those files once it is imported or replaced.) It can import your own station’s history, which is the common case and needs almost no thought, or another station’s, which needs two answers from you before it will be right.

The common case: your own station’s history

1. Open Settings → Data → Import, or go straight to /station/data#import.
2. Give it the file — either Upload it, or switch to Server Path and type the absolute path to ~/BirdNET-Pi/BirdDB.txt (or birds.db).
3. Review the preview — schema, total detections, unique species, date range, duplicate count, and a checklist with ✔ / ⚠ / ✘ against each validation.
4. Click Start Import.
5. Verify the per-species count comparison when it finishes.

Leave the two “Where did this recording come from?” fields blank. Blank means “this is this station, on this clock”, which is what makes the import a no-op reconciliation.

Duplicate rows are skipped, so re-running the import is safe — if it is interrupted, run it again.

Importing another station’s history

This is a different operation and the form treats it as one. Two facts drive everything below:

• BirdNET-Pi stores local wall-clock time with no time zone. A history recorded at UTC−5 and read by a UTC+1 station is six hours out, and nothing in the file says so. Every hour-of-day analytic — the dawn chorus, the heat map, sessionisation, peak windows — would average the two clocks together.
• A different place is a different set of birds. Sunrise, habitat and species pool all differ, so “first of year” and species richness stop meaning one thing.

Tell it where the file came from

Fill in both fields before importing:

Each timestamp is then converted individually — source local → the real UTC instant → this station’s local time for that instant — so the destination half of the conversion is exactly right on both sides of every daylight-saving change this station observes.

What a single offset cannot do. If the source station observed daylight saving, roughly half its history carries a different real offset than one number can describe, and those rows land an hour out. Recovering that needs the source’s IANA time zone, which BirdNET-Pi does not record. The number you enter is stored with the batch, and the whole import can be removed, so this is recoverable — but it is not automatic.

What the validator will tell you

The preview compares the file’s coordinates against this station’s and reports:

• a ⚠ warning when the source is far enough away to be a different site — the batch is then tagged NNN km away in the provenance list;
• a ✘ failure, which refuses the import, when the file itself contains detections from several different coordinates. Such a file is already a merge of several sites and cannot be attributed to one place.

The distance check is a warning, not a block: merging two sites is a legitimate thing to want, and only you can say whether two coordinates are one station whose GPS fix moved or two sites a county apart.

Decide whether imported rows count

Under Imported histories there is one checkbox:

Keep imported detections out of the analytics

• Off (the default) — imported detections count as this station’s own everywhere: life list, first-of-year, species richness, phenology, the heat map, co-occurrence, the dawn chorus.
• On — they stay in the database and in the Recordings browser, but stop contributing to any of those.

Turn it on when you have imported another site and want your station’s own numbers back. It applies to both the detection database and the DuckDB analytics copy, so the two cannot disagree.

Undoing an import

Every imported detection is tagged with the batch that brought it in. Each batch in the Imported histories list has a Remove action that deletes exactly those rows — nothing this station heard itself is touched. Merging another site’s history is a decision you can take back.

After the history import

The import writes back-dated history straight to SQLite, so the DuckDB analytics copy is rebuilt afterwards — otherwise the incremental startup sync would skip every imported row as “older than the latest already synced”. The progress card shows this as a second stage; on a large history it takes a while, and the behavioural and time-series pages are thin until it finishes.

Step 3 — your recordings

The history import copies rows. Each row keeps its File_Name, but the recording it names is still in BirdNET-Pi’s folder, so an imported detection would have nothing to play and no spectrogram. The third step, Your recordings, brings them across.

BirdNET-Pi lays its clips out as ~/BirdSongs/Extracted/By_Date/<date>/<Common_Name>/<File_Name>, with a picture <File_Name>.png beside each and a By_Date/shifted/ folder of pitch-shifted copies. This station keeps clips in one folder under the same File_Name, and draws a spectrogram from the audio when you look at one. So the step takes the audio of the detections you imported (never a clip no detection names, never the pictures, never the shifted copies) and puts it where this station serves clips from.

Give it BirdNET-Pi’s folder (~/BirdSongs, or the Extracted or By_Date folder inside it) and choose what to do with each file:

Check first runs the same code with the writing switched off and tells you how many recordings it found, how much space they take, how many are already here and how many it could not find. It also refuses a copy that would take the disk past the point at which this station starts deleting its oldest clips (DISK_PURGE_THRESHOLD, 95 % unless you changed it): copying past that would begin a purge of the history you just brought, and of the station’s own recordings. It warns when some of the clips are older than the Keep clip audio setting, which would delete them at the next cleanup.

It is careful with your files:

• A name already here with the same size is “already there”; with another size it is a conflict and is left alone. It never overwrites.
• A copy is written under a temporary name and renamed into place, so a run that stops leaves either a whole clip or a leftover the next run removes. Run it again to carry on.
• A file name from the database is used only if it is a plain file name; one with a separator, a .., a leading dot or no audio extension is skipped. A link in BirdNET-Pi’s folder that points out of it is not followed.
• A clip that is not where its row says (a species folder renamed since) is found by name in the tree.

From a terminal:

birdnet-behavior --import-birdnet-pi-clips ~/BirdSongs                      # look
birdnet-behavior --import-birdnet-pi-clips ~/BirdSongs --apply-import        # copy
birdnet-behavior --import-birdnet-pi-clips ~/BirdSongs --clips-mode hardlink --apply-import

Protected clips are locked. BirdNET-Pi’s protected clips (disk_check_exclude.txt, in ~/BirdNET-Pi/scripts/) become locked detections here when you bring the recordings across, and a locked clip is never purged or removed by the species cap. The list is looked for beside the recordings (~/BirdNET-Pi/scripts/ next to ~/BirdSongs); if BirdNET-Pi is elsewhere, name its folder in Where BirdNET-Pi is installed (the command line looks only beside the recordings). The check says how many will be locked, and the result how many were. Only detections an import brought in are locked, matched by clip file name; a name on the list that matches none yet (the history is not imported) is counted as such, and running the step again after the history is in locks it.

What changes whether you like it or not

These are not options the import can hide. The mapping table below says it key by key; this is the short list.

• The sign-in is admin, as above.
• Clip links. BirdNET-Pi serves its clips from a public, predictable address, /By_Date/<date>/<species>/<file>, which anyone on the network can browse without signing in. This station serves a clip at /api/v2/recordings/<file> and shares one as a signed link, /r/<token>, that expires. A bookmark or a link from another page to an old /By_Date/... address no longer works. Notifications sent from here carry the new links.
• Clip format. BirdNET-Pi saves mp3 by default; a new install here saves wav. The import sets the format you had (AUDIOFMT). mp3, flac and ogg need ffmpeg or sox on the station, and a clip falls back to WAV with a log line without one.
• Notifications. BirdNET-Pi’s three switches — every detection, a species seen five times or fewer in a week, the first of a species each day — are one list of rules here. When more than one matches a detection, one message is sent that names every reason ($reason); BirdNET-Pi sends one per reason. All three switched off is no notifications, as there. A birdnet.conf that was never edited has all three at 0 (that is how BirdNET-Pi installs it), so importing it turns notifications off here; the preview says so in a row of its own at the top, and a notification rule is switched on under Settings, Notifications. BirdNET-Pi has no minimum confidence for notifications and notifies for every detection it stores; this station has one (0.80 unless set), so the import sets it to 0 and the same detections notify. BirdNET-Pi counts “the last 7 days” as 8 calendar days; this counts 7. $confidence prints two decimals here, BirdNET-Pi’s raw number there. The weekly report is a weekday here, not Monday at 01:00. APPRISE_ONLY_NOTIFY_SPECIES_NAMES is, despite its name, the exclusion list and the _2 key the inclusion list; the importer knows.
• The occurrence filter is version 2 here; BirdNET-Pi’s default is version 1, which is not available as ONNX. The week it is asked about is also counted differently (this station uses a 48-week year, BirdNET-Pi the ISO week), and not only in December. Measured with BirdNET-Pi’s own range models, the lists differ on most days of the year: the calendar alone on 219 to 341 days a year, by a mean of 5 to 33 species; version 1 against version 2 on every day, by a mean of 17 to 141. Over the 120 clips tested, BirdNET-Pi’s own stored rows were the same under all three combinations, but those clips held no bird that falls between the lists, so a rare or out-of-season bird may differ. Same audio, same detections has what was measured, and Species, Why isn’t a bird heard here? shows it for any bird.
• The species cap (MAX_FILES_SPECIES) keeps the N newest clips of a species here and never a locked one; BirdNET-Pi keeps the N most confident (plus everything from the last 8 days and every protected clip). If you use it, read the row.
• When the disk is full, FULL_DISK=purge removes the oldest clips of the most-recorded species first, never below five clips of a species and never a locked one (BirdNET-Pi removed about a day’s worth of the oldest files at a time). FULL_DISK=keep stops recording and deletes nothing, as in BirdNET-Pi, and records again by itself once usage is 2 percentage points below the purge threshold (the margin stops a disk sitting at the threshold from stopping and starting every cycle; a raised threshold applies after a restart). While it is stopped the station logs an error, sends an alert if notifications are set up, and lists it at /api/v2/health/conditions (birdnet_recording_held is 1 in the metrics).
• Privacy. BirdNET-Pi’s PRIVACY_THRESHOLD is a percentage of the species list; here it is a confidence, and the rule BirdNET-Pi applies is PRIVACY_RANK. The import converts it (max(10, 60 × value)) and sets the confidence rule to 0.
• Position. BirdWeather uploads carry this station’s position, as before. A position of exactly 0, 0 (what BirdNET-Pi writes when it cannot find one) is not copied.
• The network name. The station advertises itself on the local network as a web service named <name> on <host> while avahi-daemon runs; its address is http://<this machine's name>.local. BirdNET-Pi’s avahi-alias published a second name, birdnet.local; this does not.

The mapping table

Every key BirdNET-Pi writes into birdnet.conf, what it does there (from its own code), and what becomes of it. This table is generated from the importer’s table in the source (birdnet_migrate::conf::RULES); a test fails when this page and the importer differ, so what is written here is what the importer does. Keys marked as secrets are never shown or logged by the importer.

What carries over, and what does not

Carries over: every detection row — date, time, scientific and common name, confidence, coordinates, and the BirdNET parameters (cutoff, week, sensitivity, overlap) — with the history import; the settings, species lists and notification files with the settings import; the recordings of the imported detections with the third step.

Two columns are not the same kind of number afterwards. An imported row keeps the Week BirdNET-Pi wrote, the ISO week (8 for 16 February 2026, 53 for 31 December 2026). A detection this station records stores the week of its own 48-week year (7 and 48 for those two days). The import does not convert them, so that an export of the imported rows matches your old install’s. A query that groups or filters by Week across imported and new rows therefore mixes two calendars. Imported rows are the ones with an import_batch_id (new ones have none), so either leave them out, or work the week out from Date instead. Likewise Confidence: BirdNET-Pi stores four decimals, and this station stores the score unrounded.

Does not carry over: BirdNET-Pi’s own spectrogram pictures (this station draws its own), the pitch-shifted copies, the confirmed_species_list.txt list, the protected-clip list, the Streamlit, Icecast, web terminal, file manager and Adminer tools it ships, and its sign-in. Its installation is left untouched and safe to restart.

FAQ

Is it accurate? Which model does it use?

A new install uses BirdNET V2.4 with its v2 occurrence filter — the network BirdNET-Pi and birdnet-go run — and BirdNET-Pi’s own defaults (CONFIDENCE 0.70, SENSITIVITY 1.25, and the human-sound rule on). Same audio, same detections says what was measured against BirdNET-Pi’s own code and where the two still differ. The BirdNET+ V3.0 preview is a different model, an explicit choice (--classifier birdnet-v3): it hears 4.5-second windows rather than 3, reports calibrated probabilities rather than raw scores, and covers about 11 500 species rather than 6 500, so its detections are not BirdNET-Pi’s and are not meant to be. Up to v0.17.1 V3.0 was installed for everyone, and a station that already runs it keeps it: no install or update changes a running station’s model.

The V2.4 files (about 85 MB) are installed on the first run, each checked against a SHA-256 compiled into the binary; see Installation for where they come from. The V3.0 files (541 MB, plus a 14 MB occurrence model) come from this project’s model release, with Zenodo as the fallback.

Do I need a Raspberry Pi?

No. It runs on any x86_64 Linux machine too. The Pi 5 is recommended and the Pi 4B and 400 are supported; older boards such as the 3B+ and Zero 2 W are not supported targets (see Hardware). There’s no Python interpreter or virtualenv overhead around the model, so it’s happy on modest hardware.

Does it work offline / without internet?

Yes, once set up. The only things that need the network are the one-time model install, optional Wikipedia photo caching, and any notification/upload channels you enable. The UI itself is fully self-contained — all fonts are embedded in the binary and it never calls out to a CDN.

Does it need a camera, or just a microphone?

Either. Point it at a USB microphone, or at an RTSP stream from an IP camera (many bird-box and feeder cams expose one). You can run several RTSP sources at once. See Audio & Microphones.

Where are my recordings and database stored?

Under /data in Docker (a named volume) or under the data directory on bare metal (~/BirdNet-Behavior for the service user): the SQLite birds.db, the recordings/ clips, the model (models/ on bare metal, /data/model in Docker) and the species-image cache (image_cache/ on bare metal, /data/cache in Docker).

How do I keep a recording I love from being deleted?

Retention is disk-based by default — the oldest clips are purged once the disk fills past the threshold — with an optional age limit (Keep Clip Audio (days) / CLIP_RETENTION_DAYS) that is off unless you set it. Lock any detection (on the Today page) to pin its recording permanently; locked clips are exempt from both. See Backups & Recovery.

Is the dashboard exposed on my network? Do I need a login?

By default the dashboard binds to all interfaces (0.0.0.0:8502), so it’s reachable from any device on your LAN. Viewing needs no login; the /admin* panel, the Settings management tabs and every action that changes something are password-protected. A fresh bare-metal install auto-generates that password for you. To restrict the dashboard to the local machine, set BIRDNET_LISTEN=127.0.0.1:8502 and reach it via SSH tunnel or VPN. For encryption on the LAN, --tls-mode self-signed serves HTTPS on 8503 without a second daemon. Still don’t port-forward it to the internet — put a reverse proxy with a publicly-trusted certificate, or a VPN, in front. See Remote Access & Security.

How do I find or reset the admin password?

The bare-metal installer auto-generates a strong admin password (username admin) and prints it once in the post-install summary, storing it as CADDY_PWD in /etc/birdnet/birdnet.conf. To set your own, edit that file (or the CADDY_PWD environment variable / .env under Docker) and restart:

sudo nano /etc/birdnet/birdnet.conf   # set CADDY_PWD=your-new-password
sudo systemctl restart birdnet-behavior

Editing CADDY_PWD to a new value replaces the admin password at the next restart. A password changed on the Accounts page is kept across restarts instead: the station records which CADDY_PWD it last applied (as a hash, in admin-password.applied beside the database) and does not put an unchanged one back over it. The log says so at warning level on every start while CADDY_PWD is still set. A station upgraded from a release that did not keep that record applies CADDY_PWD once, at its first start, and keeps the record from then on. Remove CADDY_PWD once you have signed in. Sign in as admin — that is the account the dashboard seeds. CADDY_USER is read from the process environment only, so setting it in birdnet.conf does not rename it (it does work under Docker). Clearing CADDY_PWD leaves /admin open to anyone who can reach the dashboard.

What happens to my records if the SD card dies?

Without offsite backups, they go with it. The weekly snapshot the station takes automatically lives in backups/ beside the database, on the same card — it protects against a corrupt page or a bad import, not against the card itself, which in a box on a fence post is a when.

Set OFFSITE_BACKUP=s3 or OFFSITE_BACKUP=sftp (plus OFFSITE_PASSPHRASE) and each weekly snapshot is encrypted on the station and uploaded to an object store or an SSH host. Encryption is not optional and not configurable: your database is a log of what is around your house and when you are there, and neither a bucket provider nor an SFTP host should hold the key.

The passphrase is the only thing that opens those files. It is not stored anywhere, not derivable from the backup, and not known to anyone else — write it down somewhere that is not this station. Restoring is birdnet-behavior --decrypt-backup <file> --out <path>.

See Backups & Recovery.

Why did turning on repeat confirmation change nothing?

Almost certainly because the analysis windows do not overlap. The filter asks how many of the windows within six seconds heard the same species — and with no overlap, six seconds is two 3-second windows, so “20% of them” rounds up to one, which every detection already satisfies.

Set BIRDNET_OVERLAP as well. birdnet-behavior --doctor reports which side of that line your station is on, the dropdown on the settings page prints the overlap each level needs, and the daemon logs a warning at startup when the level it was given cannot reject anything. See Tuning.

Do I need anything special for behavioral analytics?

No. The DuckDB engine behind the deeper behavioral views — activity sessions, species retention, next-species prediction, year-on-year trends — is built into every release and on by default. The installer runs the service with --analytics-db and Docker compose sets BIRDNET_ANALYTICS_DB, so there is no separate build, flag, or image to pick. (From source it is a default Cargo feature — --no-default-features leaves it out. On a very low-RAM board you can turn it off by passing an empty path, --analytics-db "" in the unit or BIRDNET_ANALYTICS_DB: "" in a compose override — removing the flag only falls back to <database>.duckdb; see Troubleshooting.)

Can I use it commercially?

No. BirdNet-Behavior is licensed CC BY-NC-SA 4.0, matching upstream BirdNET and BirdNET-Pi — non-commercial use only. See Credits & License.

How do I update?

• Docker: docker compose pull && docker compose up -d.
• Bare metal: sudo bash install.sh update (or re-run the installer). The Check for Updates button on /admin/system — and GET /admin/update/check — only tells you whether a newer release exists; nothing in the UI applies it.
• Your database, recordings and cached model are preserved across updates.

It’s not detecting anything — what now?

Almost always an audio-source problem. Run birdnet-behavior --doctor (as the account the service runs as; or open /admin/doctor behind the admin login), confirm a source is set and reachable, and check the level meter on Audio & Microphones. The Troubleshooting guide has step-by-step recipes.

Glossary

Plain-English definitions for the terms you’ll meet around the dashboard.

Analysis window — the three seconds of audio the model looks at in one go. A 15-second recording is five windows, or more if they overlap.

Banding code — the four-letter shorthand ornithologists use for a species (e.g. NOCA = Northern Cardinal, AMRO = American Robin). BirdNet-Behavior shows it in each species’ colored avatar.

BirdNET / BirdNET+ — the neural network that identifies birds from sound, developed by the Cornell Lab of Ornithology. This app runs BirdNET V2.4 by default (the network BirdNET-Pi runs) and can run the “BirdNET+ V3.0” preview instead; see Installation.

Co-occurrence — how often two species are heard in the same five-minute block of the same day, as a share of the blocks in which either was heard (their overlap, from 0 to 1). Two birds that are merely common are not a strong pair; two that are nearly always heard together are. It is association, not a test against chance. See Behavioral Analytics.

Confidence — the model’s certainty in an identification, from 0 to 1 (shown as a percentage). A detection is only logged if its confidence clears the threshold.

Dawn chorus — the burst of bird song around sunrise. The circadian polar plot shows when each species is most vocal across the day.

Detection — one identification event: a species, a time, a confidence, and (usually) a short audio clip.

Life list — a birder’s running list of every species they’ve ever recorded, each counted once. See Species & the Life List.

Mel spectrogram — the visual “fingerprint” of a sound (frequency over time) that the model actually looks at. The live spectrogram shows it in real time.

Offsite backup — a copy of the database somewhere that is not the station’s own SD card, encrypted before it leaves. The weekly snapshot in backups/ protects against a corrupt page; only an offsite copy protects against the card. See Backups & Recovery.

Phenology — the timing of seasonal events. Migration phenology is when migratory species arrive and depart through the year — the ridgeline chart on the Migration tab of Patterns.

Quarantine — a holding queue for borderline rare-bird detections, so a human can approve or reject them before they join your life list. See the review queue.

Repeat confirmation — a filter that records a species only when enough of the analysis windows around it heard the same thing. A real bird sings across several; an artefact usually fires once. Needs overlapping windows to mean anything. See Tuning.

RTSP — a streaming protocol many IP cameras use. BirdNet-Behavior can listen to an RTSP stream’s audio as if it were a microphone.

Sensitivity — a BirdNET parameter (0.5–1.5) that makes the model more eager or more conservative. See Tuning.

SF threshold (species-frequency) — a filter that uses your location and the week of the year to down-weight species that shouldn’t plausibly be present. See Tuning.

SNR (signal-to-noise ratio) — how loud the bird is relative to background noise, in decibels (dB). Higher is cleaner. Shown on the Audio level meters.

Streamgraph — a flowing, stacked area chart (used for activity over time) drawn from a centered baseline so each band’s thickness shows that species’ share.

Resident vs. migrant — a resident species is present year-round; a migrant only passes through seasonally. Behavioral analytics classifies which is which from your data.

Troubleshooting

The one troubleshooting guide, organised by symptom rather than by cause: find the section that matches what you saw, then work its checks top to bottom. Read it before opening an issue; if nothing here helps, open a bug report with the doctor’s output (below).

Two things the commands on this page assume

Bare metal. The service runs as the account that ran sudo bash install.sh — there is no birdnet user — and keeps its data in ~/BirdNet-Behavior of that account. Set two shell variables once and the commands below work for any account:

SVC=$(systemctl show -p User --value birdnet-behavior)        # the account the service runs as
DATA=$(getent passwd "$SVC" | cut -d: -f6)/BirdNet-Behavior    # the installer's data directory

Docker. Run docker compose … from the folder holding your docker-compose.yml. The data directory inside the container is /data.

install.sh below means the installer script. If you installed with the one-liner you do not have a copy; fetch one first:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/tomtom215/BirdNet-Behavior/releases/latest/download/install.sh -o install.sh

Start here: run the doctor

sudo -u "$SVC" birdnet-behavior --doctor                  # bare metal
docker compose exec birdnet birdnet-behavior --doctor     # Docker

It prints a one-screen report covering CPU, configuration, audio reachability, the model file, database integrity, disk space, tool dependencies and network — and every problem comes with a concrete suggested fix. Exit code: 0 = all good, 1 = at least one warning (the station runs, with features degraded), 2 = at least one error (it will not work until fixed).

• For monitoring scripts, the same checks as one line of JSON: birdnet-behavior --doctor-json.
• With a browser and no shell, sign in and open /admin/doctor: the same report, the JSON at /admin/doctor.json, and a support bundle to download (/admin/support-bundle).
• birdnet-behavior --doctor --fix first recreates any configured directory that is missing (the recordings folder, the image cache) — the commonest cause of “the service runs but nothing is recorded”, for example after a tmpfs reset — and then runs the report.
• birdnet-behavior --support-bundle [PATH] writes the same bundle from the command line: the report (JSON and text), the version, a redacted copy of the configuration and the last 2000 journal lines in one .tar.gz. Passwords, tokens and URL credentials are masked, and the station’s LATITUDE and LONGITUDE are shown to one decimal place (about 11 km), both in the configuration section and wherever the journal printed them. Read the archive before posting it publicly all the same.

Service won’t start

sudo journalctl -u birdnet-behavior -n 100 --no-pager
sudo systemctl status birdnet-behavior

For most “won’t start” cases — a stale unit, wrong permissions, a missing directory — the installer’s repair fixes ownership and permissions, rewrites the unit and restarts, without touching your data:

sudo bash install.sh repair

Docker: the container exits immediately.

docker compose logs --tail=200 birdnet
docker compose run --rm birdnet birdnet-behavior --doctor   # the doctor in a one-shot container

When a model download fails, the entrypoint lists the common causes: no internet in the container, the model’s host unreachable, or the volume out of disk. See Model not found.

Web UI not reachable

The dashboard binds to all interfaces by default, so it is reachable from other devices on your LAN at http://<pi-ip>:8502 (find the address with hostname -I). If it is not:

sudo systemctl status birdnet-behavior
ss -tlnp | grep 8502
sudo ufw allow 8502/tcp        # Ubuntu / Debian firewall; use firewall-cmd on RHEL / Fedora
ip -4 addr show | awk '/inet / && !/127\.0\.0\.1/ {print $2}'    # the address to browse to
curl -sf -o /dev/null -w "%{http_code}\n" http://<host>:8502/api/v2/health   # from another machine; expect 200

No row from ss means the daemon never finished starting — see Service won’t start. If you deliberately restricted access, BIRDNET_LISTEN will be 127.0.0.1:8502 (reachable only from the station itself); set it back to 0.0.0.0:8502 for LAN access. Viewing needs no login; /admin*, the Settings management tabs and every action that changes something do — use the auto-generated password from the install summary (the admin password FAQ).

No detections appearing

First rule out the audio source.

Bare metal (ALSA).

arecord -l                                                     # list capture devices
# Use the card *id* — the word after "card N:" — not the index:
arecord -D plughw:CARD=PRO,DEV=0 -d 3 /tmp/test.wav && aplay /tmp/test.wav
grep -E '^(ALSA_CARD|RTSP_URL|PIPEWIRE_DEVICE)' /etc/birdnet/birdnet.conf   # what the station was told to use
sudo cp /etc/birdnet/birdnet.conf /tmp/birdnet.conf && sudo nano /tmp/birdnet.conf   # ALSA_CARD=plughw:CARD=<id>,DEV=0
sudo birdnet-behavior --apply-config /tmp/birdnet.conf         # validates, backs up, installs, restarts

Other sources: pactl list short sources and parec --device=<source-name> /tmp/test.raw (Ctrl-C after a few seconds) for PulseAudio / PipeWire; nc -zv <camera-host> 554 for an RTSP camera (the doctor does the same probe). If PipeWire and ALSA are both set, PipeWire takes precedence; a local microphone runs alongside any number of RTSP streams, and the doctor lists every source the daemon will start.

Docker.

docker compose logs birdnet | grep -i 'audio source'      # which source was picked up?
grep -E '^BIRDNET_(ALSA|PIPEWIRE|RTSP)' .env              # is exactly one set?
docker compose restart birdnet

Docker: no audio at all.

ls -la /dev/snd/                                          # is the device visible on the host?
docker compose -f docker-compose.yml -f docker-compose.alsa.yml up -d   # use the ALSA overlay
docker compose logs -f birdnet

Recordings exist but the database stays empty.

ls -la "$(grep ^RECS_DIR /etc/birdnet/birdnet.conf | cut -d= -f2- | tr -d '"')"
sudo journalctl -u birdnet-behavior --since "1 hour ago" | grep -iE "inference|detection|model"

Look for model failed to load or mel spectrogram errors. The common causes:

• The model file is truncated. The doctor flags a file under 1 MB as suspicious; reinstall it (see Model not found).
• --watch-dir does not match where recordings are written.
• Not enough memory for the model on a small board — see Memory and CPU pressure.
• On a new station, no location is set. That does not stop detection, but without coordinates the occurrence filter is off and every species the model knows stays a candidate, so expect birds that do not belong in your area; set LATITUDE and LONGITUDE.

Detections exist but confidence is always low. Audio quality is almost always the cause. Check the microphone placement (out of the wind, with a foam windscreen), the ALSA gain (alsamixer -c 1, F4 for Capture), and a recording in a spectrogram viewer such as Audacity — bird calls should be clearly visible in the 1–8 kHz band. Then see Tuning Detection Accuracy.

Birds are heard but a conversation near the microphone leaves a gap. That is the human-sound rule, on by default: a window in which a human class ranks in the model’s top 10 classes, and the windows either side, are not recorded. Set Privacy Rank to 0 in the Detection section of the Settings page (or PRIVACY_RANK=0) to switch it off; see Same audio, same detections.

Model not found

sudo -u "$SVC" ls "$DATA/models/"              # bare metal
docker compose exec birdnet ls /data/model/    # Docker

A BirdNET V2.4 station (the default for a new install) has three files there: birdnet-v24.onnx, birdnet-v24_labels.txt and birdnet-v24-range-v2.onnx. A BirdNET+ V3.0 station has the V3.0 model and labels CSV, and the geomodel pair. If they are missing, restore them:

• Bare metal: sudo bash install.sh repair installs whatever the configured classifier is missing (it re-checks V3.0’s files against their SHA-256; V2.4’s are trusted if present and not empty). Or install the V2.4 files yourself: sudo -u "$SVC" env BIRDNET_MODEL_DIR="$DATA/models" birdnet-behavior --install-model birdnet-v24 and the same with birdnet-v24-range-v2. Running it again is cheap: a file that already matches its SHA-256 is not fetched again.
• Docker: restart the container; the entrypoint installs what is missing and says what it is doing. The next start resumes a BirdNET+ V3.0 download from the partial file; a V2.4 install starts the file again.

If a download fails, the message names the cause: no internet (the V2.4 files come from huggingface.co and raw.githubusercontent.com, the V3.0 files from this project’s GitHub release with Zenodo as the fallback), a full disk (the model installer wants the file’s size plus 512 MiB free), or a SHA-256 mismatch, which means the bytes were wrong and nothing was kept. To bring your own model, mount it over /data/model and set BIRDNET_SKIP_MODEL_DOWNLOAD=1 (Docker), or BIRDNET_SKIP_MODEL=1 when running the installer.

Database errors

sudo -u "$SVC" birdnet-behavior --check-db

PASSED means the schema and pages are intact. FAILED — corruption detected means restoring from a backup: the station takes a snapshot every 7 days into $DATA/backups/ and keeps the most recent 14, and also takes one at start-up whenever it had to recover the write-ahead log. Backups & Recovery says how to put one in place, and the field runbook’s database section says why the write-ahead log has to be removed first. birdnet-behavior --backup-db makes a snapshot on demand.

Behavioral analytics show “extension required”

On the Analytics page, the Activity Sessions, Species Retention and Next Species cards read “the duckdb-behavioral extension is required…”, and the startup log warns duckdb-behavioral extension not loaded.

Up to v0.9.1 the duckdb-behavioral community extension was compiled for a specific DuckDB version, and DuckDB refuses to load such a build into any other one. From v0.10.0 it is built on DuckDB’s stable C API (abi: "C_STRUCT" in /api/v2/analytics/status) and loads into any engine whose C API is at least the one it was built for, but the community registry still publishes it only under the DuckDB releases it was built for. A copy of the extension is also embedded in every release binary, and that copy is what a station uses when the cache and the registry cannot supply one.

This is non-fatal. Everything that reads SQLite directly — Migration, the Dawn Chorus, the Heatmap, Co-occurrence and the whole Time-series page — keeps working; only the extension-backed sessionize / retention / next-species queries are unavailable. The Analytics status badge says connected without claiming behavioral analytics are active.

Diagnose it in one command. --doctor will not answer this: it deliberately never opens DuckDB (a preflight open could contend with the running service), so it reports whether analytics is configured, not whether the extension loads. Use:

birdnet-behavior --verify-extension

It opens a throwaway DuckDB database, loads the extension the way the station does, prints the engine version, the extension version and what the embedded copy targets, and exits 0 when it loads and non-zero when it does not. To prove the offline guarantee — the one that matters on an air-gapped or metered station — run it with no network:

unshare -rn birdnet-behavior --verify-extension          # bare metal: a network namespace with no interfaces
docker run --rm --network none --entrypoint /usr/local/bin/birdnet-behavior \
    ghcr.io/tomtom215/birdnet-behavior:latest --verify-extension   # the image you run

With no network neither the extension cache nor the community registry can supply either extension, so a pass proves the embedded copies loaded. A station that passes with a network and fails without one has a packaging defect — the embedded extension targets the wrong DuckDB version and the registry has been covering for it — which you cannot repair yourself: open an issue with the output.

What you can do. On a station with network access, birdnet-behavior --refresh-extension force-installs the build the community registry has for the bundled DuckDB version, loads it to check, and exits (it needs --analytics-db or ANALYTICS_DB_PATH set). Upgrading to a newer release, which bundles an engine and extension that were built and pinned together, is the other fix.

Every analytics dashboard is empty, and the logs say nothing

The Analytics and Time-series pages render but show no data, the health endpoint is green, --doctor is happy, and nothing in journalctl -u birdnet-behavior looks like an error. It does not recover on its own — stations have sat like this for days. This is not the extension problem above: there the extension-backed cards degrade and say so; here every dashboard is empty, including the ones that need no extension.

Check the journal for this line:

journalctl -u birdnet-behavior --no-pager | grep -i 'duckdb": Read-only'
# Failed to create directory "/home/pi/.duckdb": Read-only file system

Every dashboard query filters on a look-back window, which reaches DuckDB as detection_date >= CURRENT_DATE - INTERVAL n DAYS. CURRENT_DATE lives in DuckDB’s ICU extension, as does every other way to name the current local date. Before the fix below, ICU was fetched at run time, into $HOME/.duckdb; the shipped systemd unit sets ProtectHome=read-only, so that write failed and every date-ranged query failed with it. The web layer renders a query error as a cached “temporarily unavailable” fragment, which is why nothing surfaced as an error.

Fixed in versions after 0.13.1, two ways over: DuckDB’s extension directory now sits beside the analytics database inside the data directory, and the ICU binary is embedded in the release binary, so nothing is downloaded and $HOME is never touched. Upgrading is the fix, and birdnet-behavior --verify-extension now also runs the date-window query the dashboards open with, so it answers this too (including under unshare -rn / --network none).

If you are stuck on 0.13.1 and cannot upgrade yet, pointing HOME at the data directory — the one place the unit already allows writes — restores analytics at once:

sudo systemctl edit birdnet-behavior
# [Service]
# Environment=HOME=/home/pi/BirdNet-Behavior     # your data directory; "pi" is your account
sudo systemctl restart birdnet-behavior

The override is harmless to leave in place after upgrading, and unnecessary.

--doctor reports a quarantined analytics database

The startup log shows “analytics database is unusable; quarantining it and rebuilding from SQLite”, and --doctor warns about a ….duckdb.corrupt.<timestamp> file.

No detections were lost, and nothing needs doing. The DuckDB analytics store holds nothing but a copy of rows that live in SQLite, so when the file cannot be read — a bad block on the SD card, a half-written file after a power cut, a DuckDB version change — the station moves it aside and rebuilds it from SQLite on that same start. Delete the quarantined file once you are satisfied nothing else is wrong. If it keeps happening, the storage is the suspect: check dmesg for I/O errors and consider replacing the card.

Memory and CPU pressure on small hardware

Symptoms: kernel OOM-killer messages in dmesg, container restarts in a loop, inference latency spikes, detections that lag minutes behind the audio. Mitigations, in order of effectiveness:

1. Enable ZRAM. The bare-metal installer sets it up on hosts with 2 GB of RAM or less during install and reinstall (not repair); SKIP_ZRAM=1 opts out. To run it again: sudo bash install.sh reinstall.
2. Reduce overlap. Analysis windows advance by the window length minus OVERLAP, so the inference work per recording is window ÷ (window − overlap) times the work at no overlap. With BirdNET V2.4’s 3 s windows, OVERLAP=1.5 is twice the work of OVERLAP=0.0, and 2.0 is three times.
3. Use the smaller model. BirdNET V2.4 (the default for a new install) is a 54 MB file; the BirdNET+ V3.0 preview is 541 MB. This page does not give a memory figure for V2.4, because none has been measured.
4. Disable analytics. Analytics is compiled into every release binary and on by default: with no --analytics-db the daemon still opens <database>.duckdb beside the SQLite file, so removing the flag does not turn it off. Pass an empty value instead. On bare metal change the unit’s --analytics-db <path> to --analytics-db "" (sudo systemctl edit birdnet-behavior, then restart); in Docker add a compose override that sets BIRDNET_ANALYTICS_DB: "" (the compose file sets it under environment:, so .env alone cannot blank it). The daemon logs DuckDB analytics disabled via empty --analytics-db on start. A --no-default-features build leaves the engine out entirely. DuckDB roughly doubles RAM use during sync.

Notifications never arrive

apprise -t "test" -b "from birdnet" <YOUR_APPRISE_URL>     # the Apprise tool, independent of this station
sudo -u "$SVC" birdnet-behavior --doctor 2>&1 | grep -i apprise

The Send Test Push Notification button under Settings → Alerts uses the values saved on the Settings page, so a passing test means live detections will notify too. Common gotchas:

• BIRDNET_NOTIFY_CONFIDENCE defaults to 0.8; lower it to see anything during testing.
• BIRDNET_NOTIFY_TRIGGER defaults to each. new-species-daily notifies on the first detection of each species per day, and new-species only while a species has fewer than 5 detections this week; use each while debugging.
• The Apprise URL must be URL-encoded if it contains special characters.

Non-Latin species names show as boxes

The dashboard ships all its Latin fonts self-hosted, but non-Latin scripts (CJK, Devanagari, …) rely on the client device’s system fonts. On a desktop or phone these are present already; on an always-on Pi kiosk, install a system CJK font:

sudo apt-get install -y fonts-noto-cjk

Nothing here fits

Run these and attach the output to your issue; it answers most of the questions a maintainer would otherwise have to ask:

birdnet-behavior --version
sudo -u "$SVC" birdnet-behavior --doctor
uname -a; free -m; df -h
sudo journalctl -u birdnet-behavior -n 200 --no-pager
docker --version; docker compose version; docker compose logs --tail=200 birdnet    # Docker only

SUPPORT.md says which channel to use, and the architecture notes on the risk register and the diagnostics design explain why the doctor checks what it does.

Field deployment runbook

Practical guidance for running BirdNet-Behavior unattended on a single piece of hardware, in the field, for months at a time, with no operator on site to push a button when something goes wrong.

This is the document you read once before deploying and once again the month before the next field season. It is intentionally opinionated — the defaults pick the safe option at every fork.

Contents

1. Hardware checklist
2. Power and thermals
3. Storage planning
4. Networking
5. System hardening
6. Time synchronisation
7. Watchdog and process supervision
8. Database and backup policy
9. Remote diagnostics and monitoring
10. Update strategy
11. Pre-flight checklist
12. Recovery runbook

1. Hardware checklist

Recommended baseline for unattended deployments:

The bare-metal installer’s --doctor pass will tell you if any of the sanity checks fail (CPU cores, disk space, audio device, etc.) before you ever start the daemon.

2. Power and thermals

• UPS or battery + charge controller. A clean shutdown beats a corrupted database. The Pi 5 PSU draws ~5 W at idle; a 10000 mAh battery rides through a 15-minute mains glitch easily.
• Thermal headroom. Stick a passive heatsink on the Pi 5 SoC; in sealed enclosures add a 40 mm 5 V fan with a temperature switch. The Prometheus /api/v2/metrics endpoint exports birdnet_cpu_count and you can scrape vcgencmd measure_temp in parallel.
• Solar deployments. Size for 3× average daily watt-hours to ride out cloudy weeks. Use a battery monitor (e.g. INA219 over I²C) and stop the service via systemctl stop birdnet-behavior when battery drops below 30 %.

3. Storage planning

How big birds.db actually gets. Measured on a synthetic three-year station — 3 285 000 rows (3 000 detections/day), 180 species, the shipped schema and all sixteen shipped indexes, ANALYZE run:

Two things follow. Budget from the detection rate, not from calendar time — a station hearing 8 000/day reaches the same size in a bit over a year. And note that most of the file, and most of the write amplification on your SD card, is index rather than data; the backup ring multiplies whatever that number is by up to fourteen.

Set the disk policy explicitly:

# /etc/birdnet/birdnet.conf
RECS_DIR=/data/recordings
MAX_FILES_SPECIES=100         # cap clips per species
DISK_PURGE_THRESHOLD=85       # autopurge starts at 85 %

The bundled disk manager supervises two directories, once a minute, with the retention each one needs:

• the recordings directory, holding your extracted clips beside birds.db. These are your data, so they are never removed by age. Only the disk-full backstop touches them: once usage exceeds DISK_PURGE_THRESHOLD it removes a tenth of them, taken from the most-recorded species first (lowest confidence, then oldest, within a species) and never taking a species below PURGE_SPECIES_FLOOR clips (5 unless you set it; 0 removes the floor), so the one clip of a rare bird outlives the thousandth of a common one. It skips any file the database has marked locked (the 🔒 Lock action on Recordings, or on a Today row). The locked set is re-read every cycle, so locking a clip takes effect immediately — no restart needed.
• the raw capture directory (--watch-dir, typically the RAM-backed /tmp/birdnet-stream), which the detector reads and never needs again. It is drained continuously by age and by a total-size ceiling (STREAM_RETENTION_SECS, STREAM_MAX_MB) so the tmpfs self-empties. Set RAW_AUDIO_KEEP_EVERY=N to copy one aged segment in N (in capture order) into <recordings>/raw before the drain removes it: that is the audio a season can be re-analysed from under a new model, and without it only the audio that already triggered a detection survives. Budget it — a 15 s segment at 48 kHz mono is about 1.4 MB, so 1 is roughly 8 GB a day per source and 10 about 0.8 GB — and know that the disk-full purge takes kept raw audio before it takes any clip.

When inference falls behind. The daemon measures its own queue — the raw segments waiting for analysis — and publishes it as birdnet_analysis_queue_depth and on /api/v2/health as analysis_queue_depth. While more than 40 are waiting (ten minutes of 15 s segments from one source), or while the board is at or above 80 °C or reports throttling, it analyses one segment in two, in capture order, and counts the rest in birdnet_segments_shed_total by reason. The queue then drains at twice the rate, the skipped audio is counted rather than lost, and the backlog station-health condition tells you it happened. Before this, the same situation resolved to the stream drain deleting the oldest unanalysed audio with nothing to show for it. If the condition keeps returning, the board cannot keep up with what it is asked: fewer sources, a longer segment, or a faster board.

Two further limits are enforced from the database on the daily maintenance tick, and both leave the detection rows intact — only the audio is reclaimed, so your counts, species lists and analytics are unaffected:

• MAX_FILES_SPECIES — keep the newest N clips per species.
• CLIP_RETENTION_DAYS — reclaim audio older than N days. Off by default (0 = keep forever); set it in Settings → General → System & Display (“Keep Clip Audio”) or the config file if you want a rolling window.

Locked clips are exempt from both. A reclaimed clip keeps its filename and gains the date its audio was removed, so the record of what was captured survives even though the file does not.

All of these can be set from the web UI — you never have to edit this file to change them. A command-line flag or BIRDNET_* variable wins over the UI, which wins over the config file.

Maintenance runs on wall-clock time, not uptime. The daily jobs (integrity check, session prune, species cap) and the weekly backup + reclaim record their completion in the database, so a station that reboots often still runs them — an overdue job fires shortly after the next boot rather than restarting its timer.

Use endurance-class SD cards. A standard A1 card will write out ~3000 P/E cycles per cell; WAL on a busy station can wear that out in a year. SanDisk High Endurance and Samsung PRO Endurance are tested choices. SSD-on-USB is dramatically better if your power budget allows it.

4. Networking

The daemon assumes the network may be down or expensive, and no network failure can slow or block the detection pipeline — every integration is dispatched off the detection path. Verified behaviours:

• BirdWeather uploads — store-and-forward. A post that fails after its in-flight retries is parked in the local database (outbound_queue) and replayed oldest-first when the network returns: batches of 25 with 200 ms spacing so a returning uplink isn’t slammed, per-entry backoff 1 min → 1 h, bounded to 5 000 entries / 48 attempts so a months-long outage can’t fill the disk. Nothing is lost to a flaky link; see §9 for the queue-depth gauge and the self-hosted-ingest override.
• Apprise notifications — best-effort, dispatched off the detection path; non-delivery is logged but never blocks detection. Not queued by design — a look-now alert replayed hours later is noise.
• MQTT publisher — fire-and-forget per detection, opening a fresh bounded-timeout connection; dispatched off the detection path so an offline broker never stalls detection. Not queued by design (live telemetry).
• Wikipedia image cache — populated lazily; works fine with no network at all.
• Auto-update check — daily, non-blocking; failure logged at debug. The check reads bounded response bodies (it cannot be made to exhaust memory by a hostile or misbehaving endpoint).
• Heartbeat URL — fire-and-forget; no retry, by design (the monitoring side is the one that should care if it didn’t arrive).

For cellular deployments, consider scheduling cron pppd up/down windows so the modem only powers up for the daily upload batch.

5. System hardening

The installer’s systemd unit (install.sh) ships hardened by default:

• Type=notify + WatchdogSec=120 — systemd restarts the daemon if it stops calling sd_notify(WATCHDOG=1) for 2 min.
• ProtectSystem=strict, ProtectHome=read-only, explicit ReadWritePaths — the daemon can only write where it needs to.
• PrivateTmp=yes, NoNewPrivileges=yes, LockPersonality=yes, MemoryDenyWriteExecute=yes, RestrictRealtime=yes, RestrictNamespaces=yes.
• SystemCallFilter=@system-service minus the @privileged @resources @mount @debug @cpu-emulation @obsolete @reboot @swap @raw-io @clock @module groups, with sched_setaffinity allowed back: ONNX Runtime pins its threads with it, and a denied call kills the service rather than failing.
• MemoryHigh=768M, MemoryMax=1G, TasksMax=512, LimitNOFILE=65536, LimitNPROC=256 — bounded resource ceilings; runaway processes can’t take down the host. The FP32 model is loaded into anonymous memory, which a limit cannot reclaim — measured at about 575 MB idle and 650 MB while analysing, with the bundled DuckDB analytics on — so the 1 GiB ceiling is headroom for analytics queries, not slack. The Docker compose files use the same limit. On a 512 MB board physical RAM plus zram binds first.
• OOMPolicy=stop — under memory pressure the unit stops cleanly instead of being killed mid-write.

If you customise the unit, run systemd-analyze security birdnet-behavior.service to check the score (the shipped unit is graded around 1.5–2.0, “OK” on the systemd scale).

6. Time synchronisation

Every detection row carries a wall-clock timestamp. If the clock jumps backwards, analytics break.

• Enable systemd-timesyncd (default on Raspberry Pi OS) or chrony (preferred for cellular deployments — handles long offline windows better).
• The unit is ordered after time-sync.target, so on a host running systemd-timesyncd or chrony the sync normally lands first. It is ordering only — nothing Wants= that target, so the service starts even if the clock never syncs. That is why the daemon fails open on clock-dependent gating (see below) rather than assuming a good clock.
• For deployments with no network at all, fit a battery-backed RTC module (DS3231 on I²C) and load rtc-ds1307 at boot.

Daylight saving, and the hour that happens twice

Detections are stored the way BirdNET-Pi stored them: a local Date and a local Time, with no offset recorded alongside. That is fine for 8 759 hours of the year and needs one paragraph of thought for the other one.

Autumn, when the clocks go back. One local hour repeats. A station on Europe/Berlin records 02:00–02:59 twice on the last Sunday in October; one on America/New_York records 01:00–01:59 twice on the first Sunday in November. In the database those two hours are indistinguishable — they carry the same local Date and Time — so:

• Anything that reads the history as a timeline sees that hour’s detections interleaved rather than in order. A dawn-chorus curve is unaffected (the transition is at night); a session or gap analysis spanning that hour is not, and will report a gap or a burst that did not happen.
• Two detections of the same species, at the same local second, at the same rounded confidence, in both passes, collide on the detections table’s identity. The second is refused and lost. It is counted — see birdnet_detection_write_failures_total under Remote diagnostics — so the station can tell you it happened rather than leaving it to the journal. The clip is kept either way, under a -2 suffix.

Spring, when the clocks go forward. One local hour does not exist. Nothing is lost; the history simply has an hour-shaped hole in it, on one night, and any “quietest hour” or “longest gap” statistic computed across that night will find it.

If any of that matters to your analysis — a phenology study, a year-over-year comparison across the transition, published data — run the station on UTC (sudo timedatectl set-timezone UTC) and accept that every hour-of-day chart is then in UTC rather than in your local morning. That is the only configuration in which no local hour ever repeats or vanishes. --doctor reports the station’s offset and how the recording window is interpreted, so you can check which convention a station is on without guessing.

7. Watchdog and process supervision

This is the workhorse of unattended operation:

1. The daemon calls sd_notify(READY=1) once the HTTP server is listening.
2. A background tokio task calls sd_notify(WATCHDOG=1) every WATCHDOG_USEC / 2 (usually 60 s).
3. If the daemon hangs (livelock, GPU deadlock, ML thread stuck), the pings stop. systemd kills it after WatchdogSec and restarts via Restart=always.
4. StartLimitIntervalSec=0 — the rate limit is off and the unit never gives up. A tight restart loop is prevented by backing off instead (RestartSec=10, RestartSteps=10, RestartMaxDelaySec=300), so a permanently-broken install retries quietly every five minutes for ever and recovers by itself the moment its cause is fixed. An unattended box never parks itself in failed waiting for a visit.
5. ExecStartPre runs birdnet-behavior --doctor-gate (or plain --doctor for a binary too old to have the gate, such as a rolled-back .prev): the full doctor report, in the journal on every start. It exits 2, blocking startup, only for a failure the station cannot run past (an unreadable configuration file, an invalid listen address, an unwritable database directory, an unusable HTTPS setup), so the journal shows what is broken instead of just “service kept restarting”. Any other failure is reported and the service starts; run birdnet-behavior --doctor for the plain exit codes.

Smoke-test the watchdog after installation:

# Pause the daemon to simulate a hang. systemd should kill it after 2 min.
sudo kill -STOP "$(pidof birdnet-behavior)"
journalctl -u birdnet-behavior -f
# Expect: "Watchdog timeout" then "Restarting" within 120 s.

Per-source gain and quiet window (manual hardware checks)

Each audio source (Settings → Capture, /station/capture; the old /admin/audio redirects there) carries an optional quiet window and, in the audio_sources table, a software gain (gain_db). Like every other per-source setting (device, sample rate, RTSP transport), these are read when the capture subsystem starts, so restart the service after editing them for the change to take effect:

sudo systemctl restart birdnet-behavior

Gain (gain_db). At unity gain (0 dB) a local microphone records through arecord (the lightest path). A non-zero gain routes that source through ffmpeg instead so the gain can actually be applied. There is currently no control for gain_db in the web UI — the per-source edit form exposes the label, device, quiet window, pipeline toggles and equaliser only, and the value is merely shown in the source’s detail line — so write the column directly to exercise this path, and verify on real hardware:

# Set a source's gain to e.g. +12 dB (no UI control yet — write the column), restart, then:
sqlite3 ~/BirdNet-Behavior/birds.db "UPDATE audio_sources SET gain_db = 12 WHERE label = '<label>';"
ps -ww -C ffmpeg -o args= | grep -- '-af volume'
# USB mic with gain → ffmpeg: "-f alsa -i <device> … -af volume=12.00dB"
# Set the gain back to 0, restart, and confirm the mic is back on arecord:
pgrep -a arecord            # present again at unity gain
# RTSP / PipeWire sources are always ffmpeg; the filter appears only with gain.

A captured clip from the gained source should be audibly louder (or quieter for a negative dB cut) than at unity gain.

Quiet window (schedule_quiet). Set a window that currently includes the time of day (each end is a clock time such as 22:00 or a solar anchor such as sunset+30 / sunrise-15), in the station’s local time — a quiet window means the operator’s night, so it is evaluated against the local clock, as is a fixed:HH:MM-HH:MM recording window. (A solar schedule is not: sunrise and sunset are absolute instants, so that gate is evaluated in UTC and needs no timezone thought at all.) Within ~2 reconcile ticks (≈ a few seconds) the source’s capture subprocess stops:

journalctl -u birdnet-behavior -f
# Expect: "recording paused (outside schedule or in quiet window)" for the source,
# and the birdnet_audio_source_up{source=<id>} gauge drops to 0 on /api/v2/metrics.
# Move the window so "now" is outside it, restart, and confirm the subprocess
# is respawned and the gauge returns to 1.

While the system clock looks unsynced (no RTC yet at boot, NTP not ready) the quiet window is not enforced — capture fails open exactly as the schedule does, so a bogus boot-time date can never silence a source.

Multi-source resilience (USB + several RTSP at once)

You can run one or more local microphones (USB/ALSA or PipeWire) and any number of RTSP streams simultaneously — set them up in Settings → Capture, or seed them from the config file with ALSA_CARDS (;-separated) and RTSP_URLS (,-separated). Each source is captured by its own subprocess and recordings carry a per-source tag (local/MIC_n and RTSP_n, or the source row’s id), so detections, recordings, and the birdnet_audio_source_up{source=…} gauge stay distinct per source.

Every source is supervised independently — the central property for an unattended field station with flaky cameras:

• One source failing never disturbs the others. A dead subprocess (camera rebooted, USB mic unplugged, network blip) is restarted with capped exponential backoff (2 s → 4 s → … → 60 s, then every 60 s forever — a source down for an hour is still recording when it comes back on hour two). The other sources keep recording and the detection pipeline keeps running throughout.
• Silent stalls are caught, not just crashes. An RTSP camera (or a USB mic wedged after a re-enumeration) whose process stays alive but stops delivering audio is detected by watching each source’s newest segment: no fresh segment for several segment-durations (floor 2 min) and the source is restarted, exactly like a crash. Stall detection fails open while the clock is unsynced (segment mtimes aren’t trustworthy before NTP).
• A network outage never blocks detection. BirdWeather, Apprise, MQTT, email, and heartbeat are all dispatched off the detection path, so a dead broker or an offline uplink for days slows none of them down — detections keep landing in the local database and you reconcile from there.

Verify per-source isolation on real hardware before sealing the unit:

journalctl -u birdnet-behavior -f
# Unplug ONE RTSP camera (or one USB mic). Expect, for that source only:
#   "audio source DOWN … still trying to restart"  and the
#   birdnet_audio_source_up{source=<id>} gauge for THAT id drops to 0,
# while every other source's gauge stays 1 and detections keep flowing.
# Plug it back in: "audio source up" and the gauge returns to 1 on its own.

8. Database and backup policy

The daemon runs a scheduled maintenance task in the background (no operator action needed):

• Daily PRAGMA integrity_check. Failure is logged at ERROR and appears in the /api/v2/health endpoint.
• Weekly WAL checkpoint + PRAGMA incremental_vacuum, a MiB at a time, to return the pages that deletes freed. Not VACUUM: that rewrote the whole file through the temp directory under one lock — three times the file size written, staged in the unit’s memory-charged /tmp, and a detection lost to database is locked while it ran. A database created before this mode existed is converted once, at the next start, with the copy staged beside the file; the log says so.
• Weekly backup snapshot taken just before the reclaim, written to ${DATA_DIR}/backups/. The 14 most recent are kept; older ones are pruned automatically.
• Manual snapshot any time: birdnet-behavior --backup-db.

Every one of those lives on the station’s own storage. For a box that is expected to run a season unattended, set OFFSITE_BACKUP so each weekly snapshot is encrypted and uploaded to an object store or an SSH host as well — it rides the same weekly job, keeps the newest OFFSITE_KEEP (default 8), and never touches the local rotation. Restore with birdnet-behavior --decrypt-backup <file> --out <path>. See Backups & Recovery.

Restore from the most recent good backup (only do this after the daemon is stopped):

sudo systemctl stop birdnet-behavior
ls -lt ~/BirdNet-Behavior/backups/ | head -3

# Delete the write-ahead log FIRST. This step is not optional — see below.
rm -f ~/BirdNet-Behavior/birds.db-wal ~/BirdNet-Behavior/birds.db-shm

cp ~/BirdNet-Behavior/backups/birds.db.backup.<timestamp> ~/BirdNet-Behavior/birds.db

# Confirm you got what you asked for before starting the daemon again.
sqlite3 ~/BirdNet-Behavior/birds.db 'PRAGMA integrity_check; SELECT COUNT(*) FROM detections;'
sudo systemctl start birdnet-behavior

Why the rm -f comes first. The database runs in WAL mode, so birds.db-wal holds committed transactions that are not yet in birds.db. Copying a backup over the main file while that log is still beside it does not replace the database: on the next open SQLite replays the log and you are back on the data you were trying to discard.

This was reproduced rather than reasoned about. A backup taken after a VACUUM (1 000 rows) was copied over a database that had since grown to 9 000 rows plus a table the backup did not contain, with the log left uncheckpointed. Reopening reported integrity_check: ok and 9 000 rows — the restore silently did nothing, and said so in green. A second run that happened to leave birds.db-shm in place restored correctly, so it fails intermittently, which is worse than failing every time. Deleting both sidecars removes the ambiguity.

Restoring from the web UI (Settings → Data → Backups & recovery) removes them for you and runs the integrity check itself; this is the manual equivalent.

9. Remote diagnostics and monitoring

Once the unit is sealed and shipped, the loop is:

1. Heartbeat URL (HEARTBEAT_URL=) — set to a free https://healthchecks.io check. The daemon pings it every five minutes, whether or not it has heard a bird, and pings once immediately at startup so a station clears its alarm within seconds of coming back from a power cut. You get an email if the pings stop for longer than your grace period (recommend: 15 min — three missed pings, so one dropped packet on a 4G bearer does not page you).

   This signal answers exactly one question: is the box still there? It deliberately says nothing about whether the station is hearing anything — a December night at 55° N is sixteen hours long, and a heartbeat that only fired on a detection could not tell a quiet night from a dead Pi. “Has it stopped detecting?” is birdnet_detection_silence_seconds and the detection deadman (DEADMAN_HOURS); “is it degrading?” is the station-health alerts. Three signals, three meanings; wire up all three.

2. /api/v2/health — pulled by your monitoring (Uptime Kuma, Healthchecks remote endpoints, custom cron) over the LAN or via a port-forward.

3. /api/v2/metrics — Prometheus text format. Scrape with Prometheus, Grafana Agent, or VictoriaMetrics. Key series: birdnet_uptime_seconds, birdnet_detections_stored, birdnet_process_resident_memory_bytes, birdnet_species_distinct, and the two field-health gauges below.

   Also worth watching for an unattended station: birdnet_noise_floor_dbfs and birdnet_noise_floor_drift_db, per capture source. A microphone that fails outright is caught by birdnet_audio_source_up and by the deadman; one that merely goes deaf — water in the capsule, a web across the port, a connector loosened by a year of thermal cycling — keeps both of those green and shows up only as fewer detections, which is what autumn looks like too. The background does not stop when the birds do, so a sustained drop in one source’s noise floor against its own history points at the equipment. The same figures are on the Settings Health tab. No threshold ships with them on purpose — set one from what your own site does over a few weeks.

   Worth an alert of its own: birdnet_detection_write_failures_total counts detections the model produced and the database refused. It should stay at zero. A non-zero value means the station heard something and could not keep it — a full or read-only disk, a locked database, or the repeated daylight-saving hour described in Time synchronisation. Alert on any increase; the journal line beside it names the species and timestamp.

4. Detection deadman — the end-to-end “is it actually detecting?” check that no per-component gauge can answer. The station measures how long ago the last detection landed and exports it as birdnet_detection_silence_seconds (also detection_silence_secs on /api/v2/health, and the “last detection” figure on Settings → Health, /station — the old /system redirects there). After DEADMAN_HOURS of silence (default 24; 0 disables; also --deadman-hours / BIRDNET_DEADMAN_HOURS) it logs a loud warning and — when Apprise is configured — pushes one alert per quiet episode, with a recovery notice when detections resume. Stations in sparse habitats should raise the threshold; a Grafana alert on the gauge gives finer control.

5. Store-and-forward uploads — BirdWeather posts that fail while the uplink is down are parked in the local database and replayed automatically when connectivity returns (oldest first — the upstream record’s sequence matches what happened in the field — in capped batches, exponential backoff up to 1 h, bounded queue). Watch birdnet_outbound_queue_depth{kind="birdweather"} — a depth that only grows means the uplink (or token) has been broken for a while. Settings → Health (/station) shows a queued-uploads figure whenever the queue is non-empty. MQTT and Apprise/email are deliberately NOT queued: they are live telemetry and look-now alerts, and replaying them hours later is worse than dropping them — the local database is always the ground truth.

   Self-hosted ingest (sensitive species). Research programmes that must keep observation locations under their own governance — rare or endangered species where a public community map is a poaching risk — can redirect the same upload pipeline (including the offline queue and ordered replay) at their own endpoint that implements the BirdWeather station API shape:

   # /etc/birdnet/birdnet.conf
   BIRDWEATHER_URL=https://ingest.example.org/api/v1
   

   (Env equivalent: BIRDNET_BIRDWEATHER_URL; only the host changes — the /stations/<token>/detections path shape is preserved.) The active endpoint is logged at startup so a misdirected station is visible in the first journal lines.

6. birdnet-behavior --doctor-json — for monitoring scripts that speak JSON (Home Assistant command sensor, Nagios, Zabbix). Same exit codes as the human-readable mode. The same report is served over HTTP behind the admin login — /admin/doctor (rendered), /admin/doctor.json (the --doctor-json document) and /admin/support-bundle (the redacted archive --support-bundle writes; it shows the station’s coordinates to one decimal place, about 11 km) — so a station can be diagnosed from a browser without SSH.

7. SSH tunnel via Tailscale / ZeroTier / Cloudflare Tunnel — gives you the web UI from anywhere without exposing a port to the open internet. Recommended over plain port-forward.

Station-health alerts

The detection deadman answers “is the station detecting at all?”. Station health answers the questions that leave it quiet — the faults a station keeps detecting straight through:

Each alerts once per episode, with a recovery notice when it clears, through the same Apprise notifier as the deadman. Every condition must persist for three consecutive five-minute polls before it fires, so a mic that re-enumerates or a disk that spikes during clip extraction stays silent.

Once per delivered alert. The loud journal line is written when the condition is first observed; the push is then retried at every five-minute poll until it actually reaches a destination, so a fault raised while the uplink was down is still announced when the uplink comes back. A recovery that happens before the onset alert got out replaces it, so you are never handed a fault that has already cleared. Alerts about the station are also exempt from NOTIFY_RATE_PER_MINUTE, which is sized for detections — a deadman crossing its threshold during a dawn chorus used to lose that race silently. Whatever still cannot be delivered is counted in birdnet_notifications_dropped_total.

The clock check is the one that catches a silent loss rather than a visible one. A station whose NTP has been unreachable for months keeps recording, keeps detecting, and keeps every gauge green — while filing an entire season under the wrong hours. Nothing else notices, because a plausible-looking date passes every other check the station makes.

It is deliberately silent where it cannot know: in Docker there is no systemd to ask, and the container’s clock is the host’s, so the condition never fires and birdnet_clock_synced is absent rather than 0.

A single-source station that goes fully down is deliberately not reported here — the deadman covers that, with better wording, and two notifications for one fault is how a channel gets muted. This check exists for what the deadman structurally cannot see: some sources up, some down.

On by default. Disable with --station-health-alerts false, or STATION_HEALTH_ALERTS=false in /etc/birdnet/birdnet.conf.

# Confirm it started.
journalctl -u birdnet-behavior | grep 'station-health notifier started'

10. Update strategy

Field-deployment philosophy: don’t auto-update.

• The daemon checks for updates daily (logged at INFO when one is available) but never applies them automatically. The admin panel’s Check for Updates button tells you when one exists; apply it with sudo bash install.sh update.
• Test a new release on a bench unit first. Run it for at least 72 h before pushing it to field units.
• When you do push, do it during the species’ low-activity window (e.g. local 14:00 for songbirds) so a downtime blip costs the fewest detections.
• install.sh keeps the outgoing binary at /usr/local/bin/birdnet-behavior.prev, so a one-line mv rollback is available if the new build misbehaves. The update prints the exact command. The unit it writes asks for --doctor-gate only from a binary that has it, so the rolled-back binary starts under it. A unit written by 0.17.0 did not do that: after rolling back from 0.17.0, run sudo bash install.sh repair with the current installer to rewrite it. When the update added the geomodel to a config that had none, it prints a second rollback command that also takes those lines back out; use that one, because a release from before the geomodel cannot use it.
• Rolling back leaves the database at the newer schema. The previous binary logs a warning about it at every start and keeps recording; every release is tested for this (below). Its analytics pages may stop updating, because the analytics copy carries columns it does not know; the detections are unaffected.
• Every release is gated on this path before it is published: the newest previous releases are installed under systemd, given detections, updated in place, and rolled back with the printed command (installer/test/upgrade-e2e.sh).

11. Pre-flight checklist

Run through this the day you take the unit to the field:

# 1. Hardware and audio.
birdnet-behavior --doctor               # ALL green (or warnings only).

# 2. Time sync working.
timedatectl status | grep "System clock synchronized: yes"

# 3. Disk has > 5 GiB free.
df -h /data

# 4. Backup directory exists and is writable.
ls -la ~/BirdNet-Behavior/backups/

# 5. Watchdog smoke test (see § 7).
sudo kill -STOP "$(pidof birdnet-behavior)" && sleep 130 && \
  systemctl is-active birdnet-behavior

# 6. Reboot test — comes back clean?
sudo reboot
# After reboot, wait 2 min, then:
systemctl is-active birdnet-behavior   # expect "active"
curl -sf http://localhost:8502/api/v2/health | jq .status

# 7. Network failure tolerance.
sudo ip link set wlan0 down
sleep 60
journalctl -u birdnet-behavior --since "1 minute ago" | grep -i error
sudo ip link set wlan0 up

# 8. Heartbeat reaches your dead-man switch.
# Configure HEARTBEAT_URL, restart, then confirm in the dashboard at
# https://healthchecks.io/.

If any of those eight steps fails, fix it on the bench, not in the field.

12. Recovery runbook

Symptom-driven, oldest-known-cause first:

See also: Troubleshooting for general diagnostics not specific to field deployments.

See also

• Troubleshooting — symptom-organised problem solving (the repository’s TROUBLESHOOTING.md is only a pointer to it)
• SECURITY.md — disclosure policy
• docs/architecture/12-risks.md — risk matrix
• docs/architecture/14-diagnostics.md — design of the --doctor system

Security Hardening Guide

BirdNet-Behavior is designed to be safe by default on a trusted home network, but if you are deploying it somewhere more exposed — a shared flat, a research site with multiple tenants, a campus network, or anywhere reachable from the internet — this guide collects the knobs that matter.

For the project’s threat model and trust boundaries, see docs/architecture/12-risks.md. To report a vulnerability, see SECURITY.md.

TL;DR for an exposed deployment: keep CADDY_PWD set (a fresh install generates one automatically), restrict the bind to loopback (or a VPN) if you don’t need LAN access, put a reverse proxy with TLS in front for anything off-LAN, leave CORS at its same-origin default, and verify release artifacts before installing.

1. Network exposure

The single most important decision is what can reach the web UI. Viewing the dashboard requires no login; the /admin panel — which can change settings, trigger database backups, and update the software — is gated by a session-cookie sign-in enforced by the binary itself. Treat reachability as the primary control — and when the station is reachable from beyond the LAN, turn on private mode, which puts the dashboard itself behind that sign-in.

• Default: all interfaces. A bare-metal binary defaults to --listen 0.0.0.0:8502, so the dashboard is reachable from other devices on the LAN out of the box. The installer auto-generates an admin password (CADDY_PWD) on a fresh install, so /admin is protected by default; the open dashboard exposes only read-only views.

• Restrict to this host: set BIRDNET_LISTEN=127.0.0.1:8502 (env, the config file, or answer “restrict to this device” in the interactive installer) — then reach it remotely with an SSH tunnel (ssh -L 8502:localhost:8502 pi@host) or a VPN.

• Startup guard. When the server binds to a non-loopback address and no CADDY_PWD is configured (e.g. you cleared it), it logs a prominent warning at startup. If you see

  WARN admin web UI is bound to a non-loopback address with NO authentication …
  

  in the journal, either set CADDY_PWD (below) or bind to 127.0.0.1.

• Encrypt the LAN traffic. --tls-mode self-signed brings HTTPS up on 8503 and generates a local CA to import once; --tls-mode manual serves your own certificate and reloads it when your ACME client renews it. Off by default. --doctor verifies the whole setup before startup does.

• Private mode for anything reachable from outside. A tunnel, a mesh VPN shared with other people, or a port forward makes “anyone who can reach the port” a much larger set than your LAN, and --listen 127.0.0.1 does not help: the tunnel is what connects to it. Set BIRDNET_PRIVATE_MODE=true (config file: PRIVATE_MODE=true) and the whole station — dashboard, read API, live audio, both WebSockets — needs the sign-in. See Private mode below.

• Never port-forward 8502/8503 to the internet. Built-in HTTPS encrypts the traffic; it does not add a login lockout or a WAF, and a self-signed certificate carries no publicly-trusted name. Put it behind a reverse proxy (Caddy/nginx) that terminates HTTPS with a real certificate and adds authentication, or use a mesh VPN (Tailscale/WireGuard). See Remote Access & Security for proxy configs.

2. Authentication

Authentication gates the /admin* panel, the Settings management tabs (/station/capture|alerts|data|settings|access) and every page action that changes something — viewing the dashboard, the read-only /api/v2/* endpoints, the WebSockets, and the health check are open to anyone who can reach the port, unless private mode is on. A fresh install auto-generates a strong admin password, so /admin is protected by default; for anything LAN- or internet-reachable, keep it set (and add TLS off-LAN).

• Built-in admin sign-in. A fresh install sets CADDY_PWD automatically and prints it once in the post-install summary, storing it in /etc/birdnet/birdnet.conf. Sign in as admin — the account the dashboard seeds. /admin* without a session redirects to a /login form that issues a session cookie; this is not HTTP Basic Auth, so curl -u does not apply. Change the password any time on the Accounts page, or by editing CADDY_PWD in the config or the environment to a new value (the station records the CADDY_PWD it last applied, so an unchanged one never replaces a password changed on the Accounts page):

  CADDY_PWD=a-long-random-password
  

  CADDY_USER is consulted from the process environment only (Docker), not from birdnet.conf — the systemd unit sets no EnvironmentFile, so on a bare-metal install the sign-in name stays admin.

  A signed-in session survives a restart of the station: the signing secret is generated once and kept beside the database as session.secret (mode 0600), unless BNB_SESSION_SECRET is set, which takes precedence. Rotating CADDY_PWD in the config signs every session out at the next start; rotating on the accounts page signs every other session out.

  The form is throttled per client address: five failed attempts inside fifteen minutes and that address is answered 429 Too Many Requests (with a Retry-After) until its oldest failure is a quarter-hour old — the password is not even checked, so a guessing script costs the Pi a map lookup rather than an Argon2 hash per guess. Each refused attempt is in the audit log as auth.login.throttled; a successful sign-in clears the address, and a restart forgives everything. Behind a reverse proxy the address is the visitor’s only if the proxy is trusted (BIRDNET_TRUSTED_PROXIES; there is no command-line flag for it); otherwise every visitor shares the proxy’s bucket, which is the conservative failure. An attempt counts from the moment it arrives, not when its password check finishes, so twenty sent at once still get five checked. A trusted hop can name any visitor it likes, so each hop other than this machine also has a budget of its own — thirty failures a quarter-hour across every address it names — and a LAN device that invents a new X-Forwarded-For per guess runs out there. CF-Connecting-IP is believed only when cloudflare is in BIRDNET_TRUSTED_PROXIES.

  This is compatible with the BirdNET-Pi CADDY_PWD convention. The password crosses the wire in clear text unless TLS is on — turn on --tls-mode, put a proxy in front, or keep the station on a trusted LAN. Clearing CADDY_PWD leaves /admin open — and with it every state-changing action on the dashboard (delete a detection, relabel it, set a review verdict, approve or delete a quarantined record, save the onboarding wizard) — to anyone who can reach it. Reading stays open either way.

  “Anyone who can reach it” means by a local name. With no password, the admin panel answers only when the station is addressed by an IP address, localhost, a one-word name (birdnet), or a name ending in .local, .lan, .home, .home.arpa, .internal or .localdomain. Any other name gets a page asking for a password to be set first. That closes DNS rebinding: without it, a website anyone in the house visits could point its own name at the Pi and operate the open panel through their browser, because the browser’s Origin and Host would agree. If you reach an open station through your own domain and want that to keep working, list the name in BIRDNET_ALLOWED_HOSTS — or, better, set a password, which makes the check moot.

• Reverse-proxy auth (recommended for internet exposure): terminate TLS and require a password at the proxy (Caddy basic_auth, nginx auth_basic), so credentials never cross the wire in clear text.

• WebSocket caveat. The live-detection WebSocket (/api/v2/ws/detections) and the health endpoint (/api/v2/health) are intentionally exempt from the built-in sign-in layer, because a browser cannot attach credentials to a WebSocket handshake. (They are read-only and outside the gated router in any case.) The live detection stream is therefore readable by anyone who can reach the port. If that matters, gate access at the network layer (VPN / proxy allow-list) rather than relying on app-level auth.

Private mode: everything behind the sign-in

BIRDNET_PRIVATE_MODE=true
BIRDNET_PUBLIC_ACCESS=share,metrics   # optional carve-outs

(PRIVATE_MODE=true and PUBLIC_ACCESS=… in birdnet.conf; --private-mode and --public-access on the command line.)