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.