File size: 10,168 Bytes
67890b5
 
 
 
 
 
ed91682
67890b5
 
22198e9
4b6e3ab
 
67890b5
 
 
72de27a
c85843b
dbfb2bf
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
77fa5a9
 
72de27a
77fa5a9
 
dbfb2bf
 
72de27a
4b6e3ab
dbfb2bf
22198e9
 
72de27a
 
 
 
 
 
22198e9
 
dbfb2bf
baf0e08
 
72de27a
 
 
 
baf0e08
 
dbfb2bf
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72de27a
baf0e08
 
72de27a
 
 
baf0e08
 
 
 
dbfb2bf
baf0e08
72de27a
 
baf0e08
 
dbfb2bf
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72de27a
baf0e08
dbfb2bf
baf0e08
 
72de27a
baf0e08
 
72de27a
baf0e08
 
72de27a
baf0e08
 
72de27a
baf0e08
72de27a
 
dbfb2bf
72de27a
 
 
 
 
 
 
 
 
baf0e08
 
72de27a
baf0e08
dbfb2bf
 
 
 
 
 
 
 
baf0e08
72de27a
dbfb2bf
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
---
title: BirdNET-Validator-App
emoji: "🐦"
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: "5.23.1"
python_version: "3.11"
app_file: app.py
hf_oauth: true
hf_oauth_scopes:
  - read-repos
pinned: false
---

# BirdNET Validator

Professional collaborative validation for BirdNET audio segments hosted in
Hugging Face datasets.

BirdNET Validator helps research teams review thousands to millions of
BirdNET-extracted audio segments with authenticated users, project-level access,
private validation state, progress dashboards, and clean scientific exports.

> Screenshots below are captured from a local demo workspace. Production Spaces
> use Hugging Face OAuth and private Hugging Face-backed storage.

![BirdNET Validator admin workspace](assets/readme/admin-workspace-demo.png)

## What It Solves

Large BirdNET runs can produce huge volumes of short audio segments. Reviewing
those segments manually becomes difficult when several validators need to work
at the same time without duplicating effort or losing provenance.

BirdNET Validator provides a shared validation workspace where:

- administrators register datasets and manage project access;
- validators review audio by species, confidence, and status;
- every decision is attributed to a signed-in user;
- rejected detections require a corrected species label;
- progress can be monitored by project, species, and validator;
- exports combine the original detection metadata with validation results.

## Core Workflow

```mermaid
flowchart LR
    A[BirdNET segments in a HF Dataset] --> B[Create project in the app]
    B --> C[Invite or assign validators]
    C --> D[Validate audio segments by species]
    D --> E[Track project progress]
    E --> F[Export CSV/XLSX for analysis]
```

1. Upload BirdNET segments to a Hugging Face dataset.
2. Create a project in BirdNET Validator using the dataset repo ID.
3. Add project-level access for validators.
4. Select a project and species in the validation workbench.
5. Validate each segment as confirmed, rejected, uncertain, skipped, or favorite.
6. Download a complete CSV/XLSX table at any point in the project lifecycle.

![Project selection workspace](assets/readme/project-selection-demo.png)

## User Roles

| Role | Purpose | Main Capabilities |
| --- | --- | --- |
| Admin | Owns and manages a validation project | Create projects, connect private state, update tokens, invite users, assign roles, delete owned projects, export results |
| Validator | Reviews assigned project segments | Select authorized projects, validate audio, add corrected species, add notes, monitor personal/project progress |

Access is scoped per project. A user can be an admin in one project and a
validator in another.

## Validation Experience

The validation tab is optimized for repeated review work:

- species-level queues prioritize pending detections first;
- pending detections are sorted from highest to lowest confidence;
- already reviewed segments move behind pending segments;
- fully reviewed species show a completion message instead of silently restarting;
- validators can still manually select rows to revisit or correct earlier work;
- rejected segments cannot be saved until `Corrected species` is filled;
- the corrected label is stored as both `validation_corrected_species` and the
  effective scientific label for downstream analysis.

Keyboard shortcuts are active only in the validation workspace:

| Shortcut | Action |
| --- | --- |
| Up arrow | Confirm |
| Down arrow | Reject |
| Left arrow | Uncertain |
| Right arrow | Skip |
| Space | Favorite |

## Progress And Scientific Export

The Progress tab summarizes validation coverage and activity while preserving a
download path for analysis.

![Progress dashboard](assets/readme/progress-dashboard-demo.png)

Exports include the full detection table, even when validation is still in
progress. Validation fields are appended in a predictable block:

| Field | Meaning |
| --- | --- |
| `validation_status` | Current validation status |
| `validation_corrected_species` | Species entered when a detection is rejected |
| `validation_effective_species` | Corrected species when available; otherwise original species |
| `validation_notes` | Validator notes |
| `validation_validator` | User who saved the latest validation |
| `validation_updated_at` | Timestamp of the latest validation |
| `validation_version` | Current version number for that detection |
| `validation_conflict` | Whether a concurrency conflict was detected |
| `validation_conflict_reason` | Conflict explanation when available |
| `validation_reviewed` | Boolean review flag derived from validation status |

CSV and XLSX exports are intended for scientific workflows, reproducible
summaries, and downstream statistical analysis.

## Privacy And Storage Model

The current production model is built around Hugging Face infrastructure:

- Users sign in with their own Hugging Face identity.
- Audio segments live in Hugging Face datasets.
- Each project can use a private companion state dataset named with the
  `_state` suffix.
- Validation state is stored in private Hugging Face-backed storage managed by
  the app backend.
- Project access is enforced by the application layer using project ACLs and
  invitations.

This model is designed for trusted research groups that need to keep datasets
private from external users while allowing multiple authorized validators to work
in parallel.

## Hugging Face Space Configuration

### Required Space Secret

Configure this secret in the Hugging Face Space:

```text
BIRDNET_HF_STORAGE_TOKEN
```

Use a Hugging Face token from the project/Space owner account with permissions
to create, read, write, and delete the private project state repositories and
validation storage used by the app.

### Recommended Optional Settings

```text
BIRDNET_PAGE_SIZE=10
BIRDNET_VALIDATOR_HOST=0.0.0.0
BIRDNET_VALIDATOR_PORT=7860
BIRDNET_INVITE_EMAIL_MODE=off
BIRDNET_INVITE_FROM_EMAIL=
BIRDNET_INVITE_REPLY_TO=
```

EmailJS is optional and only needed when email invitations are enabled:

```text
BIRDNET_EMAILJS_SERVICE_ID=
BIRDNET_EMAILJS_TEMPLATE_ID=
BIRDNET_EMAILJS_PUBLIC_KEY=
BIRDNET_EMAILJS_PRIVATE_KEY=
```

## Dataset Requirements

Each project should point to a Hugging Face dataset containing BirdNET audio
segments and metadata produced by the uploader workflow.

Recommended dataset structure:

```text
audio/
  Species_name/
    shard-000000/
      recorder_timestamp_start-end_confidence__key.wav
index/
  files.parquet
validation/
  detections.csv or detections.parquet
```

The app can derive queue metadata from the dataset index and enrich exports with
the original detection table when available.

For private or gated datasets, add a project token in the Admin tab so the app
can read audio and metadata during validation.

## Using The App

### 1. Sign In

Open the Space and sign in with Hugging Face. In local development mode, a
username login can be enabled for testing.

![Local demo login](assets/readme/login-local-demo.png)

### 2. Create Or Connect A Project

In the Admin tab:

1. Enter a stable project slug.
2. Add the project display name.
3. Add the Hugging Face dataset repo ID.
4. Choose visibility.
5. Add a dataset token when the source dataset is private or gated.
6. Create the project.

The app prepares the project state structure and registers the creator as admin.

### 3. Add Validators

Admins can assign a known Hugging Face username directly or send an invite for
later acceptance. Pending invites can be reviewed and revoked from the Admin
tab.

### 4. Validate Segments

In the Validate tab:

1. Select an authorized project.
2. Choose a species.
3. Optionally filter by confidence, status, validator, date, or conflicts.
4. Review the spectrogram and audio.
5. Save a validation decision.
6. Continue through the pending queue.

### 5. Monitor Progress

Use the Progress tab to review:

- coverage by species;
- validator activity;
- recent validation activity;
- remaining items;
- complete CSV/XLSX exports.

## Local Development

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt
python app.py
```

Open:

```text
http://127.0.0.1:7860
```

For a clean local demo workspace:

```powershell
$env:BIRDNET_ENABLE_DEMO_BOOTSTRAP="true"
$env:BIRDNET_AUTH_MODE="username"
python app.py
```

Demo usernames:

```text
admin_user
demo_user
validator_demo
```

## Verification

Run the automated test suite:

```bash
pytest -q
```

Run a lightweight deployment check:

```bash
python scripts/check_deployment.py
```

## Repository Layout

```text
app.py                         Gradio app entry point
assets/readme/                 README screenshots
src/auth/                      Hugging Face identity and access helpers
src/cache/                     Ephemeral audio/cache utilities
src/config/                    Runtime configuration
src/domain/                    Shared data models
src/repositories/              Project state and validation persistence
src/services/                  Queue, audio, validation, deletion, email services
src/ui/                        Gradio screens, components, and theme
scripts/check_deployment.py    Pre-deployment smoke check
tests/                         Unit and integration tests
```

## Deployment

The GitHub workflow `sync-hf-space.yml` uploads `main` to the Hugging Face
Space. Configure the GitHub Actions secret:

```text
HF_TOKEN
```

The token must have write access to the target Space.

The CI workflow runs tests on every push and pull request to `main`.

## Suggested GitHub About

**Description**

```text
Collaborative BirdNET audio-segment validation app for research teams, with Hugging Face OAuth, private project state, multi-validator workflows, progress dashboards, and CSV/XLSX scientific exports.
```

**Website**

```text
https://huggingface.co/spaces/jrrribeiro/BirdNET-Validator-App
```

**Topics**

```text
birdnet, bioacoustics, biodiversity-monitoring, audio-validation, gradio, huggingface-spaces, research-software, scientific-workflows, machine-learning-datasets, python
```