jrrribeiro's picture
Sync app from GitHub Actions (main)
dbfb2bf verified
|
Raw History Blame Contribute Delete
10.2 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade
metadata
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

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

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

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

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:

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

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:

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:

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

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

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

Open:

http://127.0.0.1:7860

For a clean local demo workspace:

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

Demo usernames:

admin_user
demo_user
validator_demo

Verification

Run the automated test suite:

pytest -q

Run a lightweight deployment check:

python scripts/check_deployment.py

Repository Layout

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:

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

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

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

Topics

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