mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-09-13 05:09:08 +02:00
docs(birdnet-go-dev): document the first-daily-consensus setting (#3056)
* docs(birdnet-go-dev): document the first-daily-consensus setting Adds a "Fork-only settings" section to the add-on README covering the first-daily-detection consensus rule from alexbelgium/birdnet-go#63, which this build compiles in because merge-prs.sh merges every open non-draft PR on the fork. The section leads with what the setting does NOT affect, because "requires two models to confirm" reads as far more invasive than it is: it is inert on a single-model install (the default), on bats and non-bird sound classes, on species not known to every active bird model, and when a dynamic threshold has already lowered the bar. Without that list a user reasonably concludes the add-on will start dropping detections. Also qualifies the header's "everything below is identical to the standard add-on" claim, which the new section would otherwise contradict. Docs only; no add-on behaviour changes. Version bumped so Supervisor offers the rebuild. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(birdnet-go-dev): correct the first-daily-consensus wording Copilot, Codex and CodeRabbit each independently flagged the same three inaccuracies on PR #3056. Verified each against merge-prs.sh and the alexbelgium/birdnet-go implementation before fixing. - The "disappears once merged upstream" claim was backwards. merge-prs.sh syncs the fork's main with upstream BEFORE applying open PRs, so a PR that merges upstream stays in every future build via that sync step - it only stops being fork-only. Only a PR closed without merging drops out. - "Every later detection... behaves exactly as today" undersold the rule. Every attempt for a species is held to the two-model bar until one is accepted, not just the first attempt - confirmed by reading firstDailyGateApplies, which re-evaluates every detection against the same memo until acceptedToday is true. - "known to every active bird model" is decided per audio source (speciesSharedByActiveBirdModels scopes to sourceModelIDs, which comes from AnalysisBuffers(sourceID)), not add-on-wide across every source. Docs only. validate.sh passes, no new lint findings. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Alexandre
@@ -1,3 +1,7 @@
|
||||
## 20260909.7 (10-09-2026)
|
||||
- Correct the "first daily detection consensus" README section (review feedback on PR #3056): a merged-upstream setting stays in the build rather than disappearing, every attempt for a species is held back until one is accepted rather than only the first, and the "known to every active bird model" exemption is scoped per audio source, matching the implementation.
|
||||
## 20260909.6 (10-09-2026)
|
||||
- Document the fork-only "first daily detection consensus" setting (alexbelgium/birdnet-go#63): requires a second model to confirm each bird species' first detection of the day. Off by default; no behaviour change unless enabled.
|
||||
## 20260909.5 (09-09-2026)
|
||||
- Minor bugs fixed
|
||||
## 20260909.4 (09-09-2026)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Home assistant add-on: Birdnet-Go (from source)
|
||||
|
||||
> **⚠️ Test build.** This is a special variant of the [standard birdnet-go add-on](https://github.com/alexbelgium/hassio-addons/tree/master/birdnet-go). Instead of pulling the prebuilt `ghcr.io/tphakala/birdnet-go` image, it **compiles BirdNET-Go from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork**. At build time it syncs the fork's `main` with the `tphakala/birdnet-go` upstream and **merges every open non-draft ("in review") pull request on the fly** (see [`merge-prs.sh`](./merge-prs.sh)), so the binary reflects upstream main plus all work currently under review. Everything below is identical to the standard add-on.
|
||||
> **⚠️ Test build.** This is a special variant of the [standard birdnet-go add-on](https://github.com/alexbelgium/hassio-addons/tree/master/birdnet-go). Instead of pulling the prebuilt `ghcr.io/tphakala/birdnet-go` image, it **compiles BirdNET-Go from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork**. At build time it syncs the fork's `main` with the `tphakala/birdnet-go` upstream and **merges every open non-draft ("in review") pull request on the fly** (see [`merge-prs.sh`](./merge-prs.sh)), so the binary reflects upstream main plus all work currently under review. Everything below is identical to the standard add-on, except the fork-only settings listed under [Fork-only settings](#fork-only-settings).
|
||||
|
||||
|
||||
|
||||
@@ -65,6 +65,38 @@ Additional variables can be configured using the config.yaml file found in /conf
|
||||
- Config_env.yaml
|
||||
Additional environment variables can be configured there
|
||||
|
||||
### Fork-only settings
|
||||
|
||||
These are currently fork-only settings from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork and are **not** in the standard add-on. [`merge-prs.sh`](./merge-prs.sh) syncs the fork's `main` with upstream before applying open PRs, so once a PR merges upstream the setting stays in this build — it just arrives via that sync instead of the PR-merge step, and stops being fork-only. Only a PR that is **closed without merging** drops its setting from later builds.
|
||||
|
||||
#### First daily detection consensus
|
||||
|
||||
Requires a second model to confirm the **first** detection of each bird species each day. Until one is accepted, every attempt for that species is held to the same two-model bar; only once a detection clears it does every later detection that day behave exactly as it does today, on a single model.
|
||||
|
||||
The first detection of a species in a day is the weakest evidence the pipeline produces, and it is the one that creates a "new species today" entry. Asking two models to agree on just that one detection removes most spurious new-species entries without slowing anything else down.
|
||||
|
||||
**Off by default.** Turn it on in the web UI under *Settings → Filters → First Daily Detection Consensus*, or in `config.yaml`:
|
||||
|
||||
```yaml
|
||||
realtime:
|
||||
firstdailyconsensus:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
The setting is re-read on each detection cycle, so it takes effect without restarting the add-on.
|
||||
|
||||
It deliberately does **nothing** in these cases, all of which keep today's single-model behaviour:
|
||||
|
||||
- you run only one bird model (the default) — a second opinion does not exist, so the rule can never trigger
|
||||
- the species is not a bird — bats and the non-bird sound classes Perch reports (insects, amphibians, mammals, `power_tool`, and so on)
|
||||
- the species is not known to *every* active bird model analyzing that audio source — a species only one of them can name could never reach two confirmations. With several sources running different model combinations, this is decided per source, not add-on-wide
|
||||
- a dynamic threshold has actually lowered the bar for that species, meaning you asked for a more permissive gate
|
||||
- the taxonomy or the database cannot be consulted — it fails open and accepts the detection
|
||||
|
||||
In practice it only bites when a single audio source has two or more bird models (for example BirdNET plus Perch) analyzing it, on species all of them can identify. The trade is fewer false new-species entries, at the cost of occasionally delaying a genuine first sighting until a second model agrees.
|
||||
|
||||
Requires [alexbelgium/birdnet-go#63](https://github.com/alexbelgium/birdnet-go/pull/63).
|
||||
|
||||
### MQTT and MariaDB auto-configuration (opt-in)
|
||||
|
||||
If the Home Assistant **MQTT** addon is installed and running and you set `mqtt_auto_config: true` in the addon options, the addon writes the HA Mosquitto credentials directly into BirdNET-Go's `config.yaml` on every startup: `realtime.mqtt.enabled`, `broker`, `username`, and `password` are populated, and the topic defaults to `birdnet`. In addition, it enables BirdNET-Go's **native Home Assistant MQTT auto-discovery** (`realtime.mqtt.homeassistant.enabled`), so the detection sensors show up in Home Assistant automatically — **no manual MQTT sensor YAML required** (the hand-written sensors in [HAINTEGRATION.md](./HAINTEGRATION.md) remain available if you prefer to build your own). Messages are also retained (`realtime.mqtt.retain: true`) so sensor states survive Home Assistant restarts. When the option is `false` (the default), the addon still logs the broker details and reminds you about the option whenever Mosquitto is detected — nothing is written.
|
||||
|
||||
@@ -127,5 +127,5 @@ slug: birdnet-go-dev
|
||||
udev: true
|
||||
url: https://github.com/alexbelgium/hassio-addons
|
||||
usb: true
|
||||
version: "20260909.5"
|
||||
version: "20260909.7"
|
||||
video: true
|
||||
|
||||
Reference in New Issue
Block a user