Spaces:
Sleeping
Sleeping
File size: 9,828 Bytes
22198e9 | 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 | # BirdNET Validator App - Testing Guide for HF Space
This guide explains how to test the BirdNET Validator application on Hugging Face Spaces.
## Quick Overview
The validator is a Gradio application for human review of BirdNET detections. It provides:
- Multi-project login with role-based access
- Detection queue with filtering and pagination
- Audio playback and validation actions
- Concurrency-safe writes with optimistic locking
- Conflict resolution and reporting
## Architecture
```
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Gradio Web UI (app.py) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β ββ Login Page (auth_service) β
β ββ Admin Panel (admin_panel) β
β ββ Queue Display (detection_queue_service) β
β ββ Audio Player (audio_fetch_service) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Services & Repositories β
β ββ ValidationService (save/validate/report) β
β ββ DetectionQueueService (filter/paginate) β
β ββ AudioFetchService (download/cache) β
β ββ AppendOnlyValidationRepository (atomic ops) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Data Sources β
β ββ Projects (bootstrap/config) β
β ββ Users & Access Control β
β ββ Detections (HF dataset or seed file) β
β ββ Validations (local append-only log) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ
```
## Testing on HF Spaces
### Step 1: Configure HF Space with Demo Data
1. Go to **BirdNET-Validator-App Space Settings**
2. Configure Variables/Secrets:
```
BIRDNET_ENABLE_DEMO_BOOTSTRAP=true
BIRDNET_PAGE_SIZE=25
```
These settings will:
- Load built-in demo users: `admin_user`, `demo_user`, `validator_demo`
- Load demo project: `demo-project`
- Load demo detections: 100 sample birds
### Step 2: Access the App
1. Go to your HF Space URL
2. Wait for the Gradio interface to load
3. You should see the login page
### Step 3: Test Login
**Test user 1 (Admin):**
- Username: `admin_user`
- Expected: Access to all projects with admin role
- Expected UI: "Admin Panel" tab visible
**Test user 2 (Validator):**
- Username: `demo_user`
- Expected: Access to demo-project with validator role
- Expected UI: "Admin Panel" tab NOT visible
**Test user 3 (Another Validator):**
- Username: `validator_demo`
- Expected: Same access as demo_user
### Step 4: Test Core Features
#### Feature 1: Project Selection
1. Login as `admin_user`
2. Click "Select Project"
3. Verify: `demo-project` appears in list
4. Click to select `demo-project`
5. Expected: Queue loads with 100 detections
#### Feature 2: Detection Queue & Filtering
1. Verify detections display with:
- Audio ID
- Scientific Name
- Confidence score
- Current validation status
2. Test filters:
- **Filter by Species**: Enter scientific name prefix, queue updates
- **Filter by Confidence**: Set min/max bounds, queue filters
- **Search**: Type audio ID, rows filtered in real-time
3. Test pagination:
- Default page size: 25 items
- Click "Next Page" / "Previous Page"
- Verify correct items load
#### Feature 3: Audio Playback
1. Click on a detection row
2. Click "Play Selected" button
3. Expected: Audio player loads with sample WAV
4. Verify audio plays correctly
5. Verify sample rate and duration display
#### Feature 4: Validation Actions
1. Select a detection by clicking the row
2. Choose validation status:
- **β Positive**: Species confirmed
- **β Negative**: False alarm
- **? Uncertain**: Unsure
- **β Skip**: Come back later
3. Optional: Add notes in the text field
4. Click "Save Validation"
5. Expected UI changes:
- Row highlights in green (valid) or yellow (uncertain)
- Status displays in "Validation Status" column
- Validator name appears in "Validated By" column
#### Feature 5: Batch Validation (Conflicts)
1. Simulate conflict: Validate same detection from 2 different users
- In separate browser windows:
- Window 1: Login as `admin_user`
- Window 2: Login as `demo_user`
- Both validate the same detection differently
2. Window 2 should show: "Optimistic lock conflict"
3. Click "Reapply my validation" to override
4. Expected: Validation saved, conflict row marked
#### Feature 6: Admin Panel (Admin Only)
1. Login as `admin_user`
2. Click "Admin Panel" tab
3. Verify options:
- View validation report
- Create invites
- Manage user roles
- View audit logs
4. Click "Validation Report"
5. Expected: Shows statistics:
- Total validations
- Breakdown by validator
- Breakdown by status
- Last updated time
## Keyboard Shortcuts (if enabled)
Press '?' in the app to see shortcuts:
- `P`: Positive validation
- `N`: Negative validation
- `U`: Uncertain validation
- `S`: Skip detection
- `β`: Next page
- `β`: Previous page
- `?`: Show this help
## Data Flow During Test
1. **User logs in**
- Auth service validates credentials
- RuntimeConfig loads projects and user access
- Dashboard loads project list
2. **User selects project**
- DetectionQueueService loads first page (25 items)
- Each detection loads from in-memory repository
3. **User clicks on detection**
- AudioFetchService fetches from HF dataset
- Audio cached in ephemeral memory
- Audio player displays WAV
4. **User validates**
- ValidationService creates validation event
- AppendOnlyValidationRepository appends to log
- Optimistic locking prevents conflicts
- UI updates with new status
## Expected Test Results
β
**All should pass:**
- [ ] Login with `admin_user` succeeds
- [ ] Login with `demo_user` succeeds
- [ ] Project selection loads demo-project
- [ ] Queue displays 100 detections
- [ ] Filters reduce queue size
- [ ] Audio playback works
- [ ] Positive/Negative/Uncertain/Skip actions work
- [ ] Validation status updates in real-time
- [ ] Pagination works (next/prev page)
- [ ] Notes are saved with validation
- [ ] Admin panel visible for `admin_user`
- [ ] Validation report shows correct stats
- [ ] Multiple concurrent validations don't lose data
- [ ] Conflict resolution works
## Troubleshooting
### "Loading..." spinner stuck
**Cause**: Audio fetch service timeout or missing audio
**Solution**:
1. Check HF dataset is accessible
2. Verify `BIRDNET_DETECTIONS_FILE` is set correctly
3. Check browser console for errors
### "Optimistic lock conflict" on first validation
**Cause**: Concurrent writes detected (expected in conflict test)
**Solution**:
1. Click "Reapply my validation" to override
2. Or click "Discard" to cancel
### "Project not found"
**Cause**: Bootstrap didn't load projects
**Solution**:
1. Ensure `BIRDNET_ENABLE_DEMO_BOOTSTRAP=true`
2. Or provide `BIRDNET_PROJECTS_FILE` pointing to valid JSON
3. Check Space logs for errors
### Audio player blank
**Cause**: Missing audio or fetch service error
**Solution**:
1. Verify HF dataset has audio files
2. Check `BIRDNET_DETECTIONS_FILE` points to valid detection JSON
3. Verify audio file paths in detection data
## Local Testing Before HF
To test locally before deploying to HF:
```bash
# Test with demo bootstrap
export BIRDNET_ENABLE_DEMO_BOOTSTRAP=true
export BIRDNET_PAGE_SIZE=25
python app.py
# Open browser to http://localhost:7860
```
Then follow the testing steps above.
## Performance Expectations
- **Login**: < 1 second
- **Project load**: < 2 seconds
- **Queue page load**: < 1 second
- **Audio fetch**: 2-5 seconds (depends on file size)
- **Validation save**: < 1 second
- **Pagination**: < 1 second
## Next Steps After Testing
1. β
Confirm all features work locally
2. β
Push to HF Space
3. β
Test on HF Space URL
4. β
Configure production data (real projects/users/detections)
5. β
Set up invite email (optional, requires EmailJS)
6. β
Share HF Space URL with validators
## Files Reference
**Main entry point:**
- `app.py` - Starts Gradio server
**UI Components:**
- `src/ui/app_factory.py` - Creates Gradio interface
- `src/ui/login_page.py` - Login form
- `src/ui/admin_panel.py` - Admin panel UI
**Services:**
- `src/services/validation_service.py` - Validation logic
- `src/services/detection_queue_service.py` - Queue filtering/pagination
- `src/services/audio_fetch_service.py` - Audio download/caching
- `src/auth/auth_service.py` - Authentication
**Data:**
- `src/repositories/append_only_validation_repository.py` - Write validation events
- `src/repositories/in_memory_detection_repository.py` - Read detections
- `src/config/runtime_config.py` - Configuration from env vars
- `src/cache/ephemeral_cache_manager.py` - Temporary audio cache
## Security Notes
- Tokens are validated against Hugging Face API
- Each user needs `read` access to the detection dataset
- Each user needs `write` access to create validations
- Admin users can manage invites and ACLs
- All writes are append-only (immutable audit log)
## Questions or Issues?
Check:
1. HF Space logs (Settings > Logs)
2. Browser console (F12 > Console)
3. README.md for configuration details
4. app_factory.py for initialization code
|