feat(app): unify into Bird Audio Analyzer — single Tauri app with Batch + Review modes

[leyangloh]

Pull Request: Unified Tauri Desktop App & Curation Pipeline (leyang/pwa-prototype)

🛠️ Overview

This Pull Request introduces the unified Tauri desktop application for the Bird Audio Analyzer. It consolidates the high-performance Python machine learning backend with an interactive desktop interface featuring two distinct workflow modes:

1. Batch Mode (Analyze): Automates the ML inference pipeline over directories of field recordings.
2. Review Mode (Curation): Provides visual spectrogram inspection, audio playback, time-frequency bounds adjustment, and manual annotation curation.

---

Here is the recorded walkthrough demonstrating the full end-to-end smoke test (starting the batch processing session, monitoring progress, viewing results, and curating detections in Review Mode):

Tip

You can also play or view the media files directly:

• Play Walkthrough Video (MP4 - 768 KB)
• View Walkthrough Animation (GIF - 2.7 MB)

---

🚀 Setup & Execution Guide

Prerequisites

Ensure the following tools are installed on your environment:

• uv: Python package resolver (astral-sh/uv)
• Rust & Cargo: Tauri compiler toolchain (Rustup)
• Node.js & npm: Frontend React/TypeScript compiler (NodeJS)

Installation

Execute these commands from the repository root (/Users/leyangloh/.warp/worktrees/bird-audio-pwa/cuesta-lechuguilla):

1. Install React Frontend Dependencies:

   npm install

2. Sync Python Virtual Environment & ML Engine:

   uv sync

Running the Desktop App (Development)

Launch the unified Tauri application in local developer mode:

npm run tauri dev

Note

The initial launch will compile Rust crate dependencies (this may take a few minutes). Subsequent launches are cached and start incrementally.

---

🧪 Feature Testing & Verification Guide

Follow these steps to manually verify the application features end-to-end:

Step 1: Verify System Health Panel & Initialization

1. Launch the app (npm run tauri dev).
2. Verify the Health Panel banner at the top of the Setup view:
   • It should query your environment and check for model weights (models/buzz_localizer.pt and models/classifier.pt).
   • If model weights are missing or the environment is not ready, the banner will display "Setup required before listening". Click Prepare System and confirm it runs setup successfully, changing the banner to green: "Instrument ready to listen".

Step 2: Test Batch Analysis Mode

1. In the Select recording folder field, input or browse to a directory containing audio recordings (e.g., /tmp/smoke_data).
2. Set the thresholds:
   • Detection sensitivity: Set to 0 (or your preferred test threshold).
   • Quality filter: Set to 0.53 (recommended default).
3. Click the Begin Listening → button.
4. Verification:
   • The UI should transition to the Run View.
   • A circular progress bar should fill up as files are processed.
   • The active file currently being scanned should display in real time (▸ /tmp/smoke_data/file.wav).
   • Stats blocks (Processed, Active, Remaining, Speed, ETA) should update.
   • Upon completion, the banner should change to "Analysis complete".

Step 3: Verify the Post-Run Dashboard & Charts

1. Once the batch run is complete, verify that the Results Summary displays:
   • Count of detections found (with a smooth count-up animation).
   • Count of high-quality buzzes.
   • Count of retained records.
2. In the charts panel below the summary, click through the tabs to verify data visualization:
   • Elevation: Displays box plots of detection duration across Low/Medium/High elevations. Hover over the boxes to verify statistics tooltips.
   • Timeline: Displays a chronological bar chart showing detection activity bins.
   • Sites: Displays a tabular overview of detections categorized by device/site ID.

Step 4: Test Interactive Spectrogram Curation (Review Mode)

1. Navigate to the Review tab in the main navigation bar (it should now be enabled since a batch run finished).
2. Select a file from the left sidebar list.
3. Verification:
   • The spectrogram canvas should render the audio signal with frequency ranges on the Y-axis and time on the X-axis.
   • Golden bounding boxes should be drawn over detected events.
   • Below the spectrogram, the event table should list all detections.
4. Test curation actions:
   • Click the Checkmark (Confirm) button on a row. The row highlight and box status should turn green (Confirmed).
   • Click the X (Reject) button on a row. The status should turn red (Rejected).
   • Adjust a box bounds: Click and drag the golden boundaries of an event box on the spectrogram canvas. Verify the duration and frequency bounds update in the table.
   • Add a manual box: Click and drag on an empty spectrogram area to draw a box. Verify a new row is added to the table marked as Manual source.
   • Click the Play button to listen to the audio selection.

Step 5: Test Data Export

1. Go back to the Batch tab.
2. Scroll to the Export Options section.
3. Select an export format: CSV, JSON, or Raven format.
4. Click Pick save destination and select a path (e.g. events.csv).
5. Toggle Confirmed events only or Complete only and click Export.
6. Verify the exported file contains the correct columns and rows matching your curated session.

---

💻 Running Automated Test Suites

For developer unit and integration verification, run the automated suites:

• Rust Backend Tests: Run cargo test --workspace to verify SQLite store functions and Tauri API route parsing (e.g. batch-core/src/store.rs and src-tauri/src/commands.rs).
• Python ML Pipeline Tests: Run uv run pytest to verify YOLO windowing and consolidation algorithms (e.g. tests/test_stageb.py).

---

📖 Related Documentation

For full architectural details, consult:

• USAGE.md: User guide and manual operations.
• batch-app.md: Schema definitions, database columns, and Tauri channel structures.
• architecture.md: YOLO window logic, spectrogram processing constants, and classification math.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[heisenshtadt3]

I see the engine from Erik's original code - is the evaluation, preprocessor, etc in here all brand new? I'm guessing some of this has already been set up in Erik's code, I'll double check that it's fine for us to use a new version for now