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.