Aubio BeatCheck

A comprehensive validation and benchmarking tool for testing aubio audio analysis functions. Designed for closed-loop optimization of aubio parameters and performance tracking.

Features

• 🎯 Standard Test Suites - Comprehensive pre-built test signals for tempo, onset, pitch, and complex analysis
• 📊 Evaluation Metrics - Precision, recall, F-measure, and timing accuracy (MAE)
• 📈 Waveform Visualization - Interactive plots comparing ground truth vs detected events
• 💾 JSON Artifacts - Machine-readable outputs for AI-driven optimization
• ⚡ Performance Metrics - Frame processing times (mean, P95, P99)
• 🌐 Web UI + CLI - Choose between interactive web interface or scriptable CLI

Installation

# Clone the repository
git clone https://github.com/shauneccles/aubio-beatcheck.git
cd aubio-beatcheck

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Quick Start

CLI Mode (for AI Agent Integration)

Run analysis and generate JSON/PNG artifacts:

# Run tempo suite with 10-second signals
aubio-beatcheck run --suite tempo --duration 10 --output ./results

# Run all suites
aubio-beatcheck run --suite all --duration 15 --output ./results

# Output structure:
# ./results/
# ├── test_input.json          # Test configuration
# ├── ground_truth.json        # Expected events
# ├── analysis_results.json    # Detected events + metrics
# ├── evaluation.json          # Precision/recall/F1
# └── plots/
#     └── *.png                # Waveform visualizations

Web UI Mode

Start the web server for interactive analysis:

# Start backend
aubio-beatcheck web --port 8000

# Start frontend (in another terminal)
cd web && npm run dev

# Open http://localhost:5173

Test Suites

API Reference

REST Endpoints

JSON Artifact Formats

See docs/API.md for detailed schema documentation.

Development

# Install dev dependencies
uv sync --all-extras --dev

# Run tests
uv run pytest tests/ -v

# Lint & format
uv run ruff check .
uv run ruff format .

Architecture

aubio-beatcheck/
├── aubio_beatcheck/          # Core package
│   ├── cli.py                # CLI entry point
│   ├── core/                 # Analysis logic
│   │   ├── analyzers.py      # Aubio wrappers
│   │   ├── evaluation.py     # Metrics calculation
│   │   ├── ground_truth.py   # Pydantic schemas
│   │   └── thebeat_gen.py    # Signal generation
│   └── suites/               # Test suite definitions
├── web_api/                  # Litestar REST API
│   ├── main.py
│   ├── routers.py
│   └── plotting.py
├── web/                      # React frontend
└── tests/                    # pytest tests

References

• aubio - Audio analysis library
• thebeat - Research-validated signal generation
• Litestar - Python ASGI framework

License

GPL-3.0