Bird Audio Classification Interface

A React-based web application for visualizing and analyzing bird audio detection data. This tool provides an interactive interface for reviewing bird detection segments with audio playback, waveform visualization, and comparison capabilities.

Features

🎵 Audio Visualization

• Interactive Waveform: Visual representation of audio with segment overlays
• Segment Highlighting: Color-coded detection segments on the waveform
• Audio Playback: Click-to-play functionality for individual segments
• Sticky Player: Waveform player stays visible while scrolling through data

📊 Data Analysis

• CSV Data Import: Support for bird detection CSV files
• Comparison Mode: Side-by-side comparison of two detection datasets
• Sortable Tables: Sort segments by time, confidence, duration, etc.
• Detection Review: Review and analyze detection results

🔍 Filtering & Search

• Time Range Filtering: Filter segments by time ranges
• Confidence Thresholds: Filter by detection confidence scores
• Advanced Filtering: Filter segments by various criteria
• Real-time Updates: Instant filtering without page reloads

💾 Data Management

• File Upload: Drag-and-drop support for custom audio and CSV files
• Default Data: Pre-loaded sample data for immediate exploration
• Session Persistence: Settings and preferences saved locally

Technology Stack

• Frontend: React 18 with TypeScript
• Audio Processing: WaveSurfer.js for waveform visualization
• CSV Parsing: PapaParse for data processing
• Styling: Tailwind CSS with custom design system
• Deployment: Firebase Hosting
• Build Tool: Create React App

Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn package manager

Installation

1. Clone the repository

   git clone <repository-url>
   cd bird-audio-classification-interface

2. Install dependencies

   npm install

3. Start the development server

   npm start

4. Open your browser Navigate to http://localhost:3000 to view the application.

Available Scripts

• npm start - Runs the app in development mode
• npm build - Builds the app for production
• npm test - Launches the test runner
• npm run deploy - Builds and deploys to Firebase Hosting

Usage

Default Data

The application loads with sample bird detection data by default, including:

• Audio file: 20250602_051000.mp3
• Detection data: 20250602_051000_detections.csv
• Comparison data: 20250602_051000_nobo_detections.csv

Uploading Custom Data

1. Prepare your files:

   • Audio file (MP3, WAV, etc.)
   • CSV file with detection data

2. CSV Format Requirements:

   file,start_time,end_time,NOBO,Present
   audio_file.wav,10.5,12.3,0.85,1
   audio_file.wav,25.1,27.8,0.92,1
   

3. Upload Process:

   • Use the drag-and-drop zone or file picker
   • Select both audio and CSV files
   • The application will automatically process and display your data

CSV Data Format

The application expects CSV files with the following columns:

Column	Type	Description
file	string	Audio filename
start_time	number	Segment start time (seconds)
end_time	number	Segment end time (seconds)
NOBO	number	Confidence score (0-1)
Present	number	Detection flag (1 = present, 0 = absent)

Comparison Mode

Compare two detection datasets:

1. Load default comparison data or upload two CSV files
2. Toggle between single and comparison view
3. View side-by-side segment tables
4. Analyze differences in detection results

Project Structure

src/
├── components/           # React components
│   ├── DataTableSection.tsx    # Main data display component
│   ├── ErrorDisplay.tsx        # Error handling UI
│   ├── FileDropZone.tsx        # File upload interface
│   ├── Header.tsx              # App header with controls
│   ├── Instructions.tsx        # User instructions
│   ├── LoadingSpinner.tsx      # Loading state UI
│   ├── SegmentTable.tsx        # Data table component
│   ├── UploadSection.tsx       # File upload section
│   └── WaveSurferPlayer.tsx    # Audio waveform player
├── hooks/               # Custom React hooks
│   ├── useAudioData.ts         # Audio data management
│   └── useAudioPlayer.ts       # Audio playback logic
├── utils/               # Utility functions
│   ├── csvExporter.ts          # Data processing utilities
│   ├── csvParser.ts            # CSV parsing logic
│   └── localStorage.ts         # Local storage management
├── types.ts             # TypeScript type definitions
├── App.tsx              # Main application component
└── index.tsx            # Application entry point

Configuration

Firebase Deployment

The application is configured for Firebase Hosting:

{
  "hosting": {
    "site": "bird-audio-app",
    "public": "build",
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

Tailwind CSS

Custom design system classes are configured in tailwind.config.js. The application uses a consistent color scheme and spacing system.

Data Processing

Filtering Logic

Segments are filtered based on:

• Present === 1 (detection present)
• NOBO >= 0.3 (minimum confidence threshold)
• Valid time ranges (start_time < end_time)

Audio Segment Processing

1. CSV Parsing: Raw CSV data is parsed and validated
2. Filtering: Apply confidence and presence filters
3. ID Assignment: Each segment gets a unique ID (CSV row number)
4. Rendering: Display segments in table and waveform

Browser Support

• Chrome (recommended)
• Firefox
• Safari
• Edge

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Common Issues

Audio not playing

• Ensure audio file format is supported (MP3, WAV, OGG)
• Check browser audio permissions
• Verify file is not corrupted

CSV parsing errors

• Verify CSV format matches expected schema
• Check for missing required columns
• Ensure numeric values are properly formatted

Performance issues

• Large CSV files (>10MB) may cause slowdowns
• Consider filtering data before upload
• Use Chrome for best performance

Support

For issues and questions:

1. Check the browser console for error messages
2. Verify file formats and data structure
3. Try with the default sample data
4. Clear browser cache and local storage if needed

Acknowledgments

• WaveSurfer.js - Audio waveform visualization
• PapaParse - CSV parsing library
• Tailwind CSS - Utility-first CSS framework
• React - UI framework