Plug in a USB stick after practice. Get an organized library of songs and takes.
BandBox turns hours of raw rehearsal recordings into a searchable, playable collection — automatically. Silence trimming, riff-based song identification, and a real-time web UI for the whole band. Built for heavily distorted genres where standard music analysis tools give up.
🎤 Record → 🔌 Plug in USB → 🧠 Auto-process → 🎵 Browse your songs
- Record your practice session to a USB stick (from your mixer, interface, or portable recorder)
- Plug the stick into a Raspberry Pi running BandBox
- Relax — BandBox copies, uploads, normalizes, trims silence, extracts riff fingerprints, and groups recordings into songs
- Review — open the web UI, listen to takes, audit trim decisions, and fix any groupings
Everything updates in real time. When the worker finishes processing a recording, it appears in your browser without refreshing.
┌─────────────────────────────────────────────┐
│ Docker Compose │
USB Stick │ │
│ │ Caddy ──┬── /api/upload ──→ SvelteKit ◄──┤──── Convex Cloud
▼ │ │ ▲ │ │ (database)
Raspberry Pi ─────┼── Wi-Fi ─┤── /pocket-id/* ──→ Pocket-ID │
(bandbox.py) │ │ │
│ ├── /oauth2/* ──→ oauth2-proxy │
│ │ │
│ └── /* ──→ oauth2-proxy ──→ SvelteKit
│ │ │
│ Python Worker │
│ (audio processing) │
└─────────────────────────────────────────────┘
| Service | Role |
|---|---|
| 🌐 Caddy | Reverse proxy, automatic HTTPS |
| 🎨 SvelteKit | Frontend + upload API (Bun) |
| 🐍 Python Worker | Normalize, trim, encode, fingerprint, match |
| 🔑 Pocket-ID | Passkey/WebAuthn login (OIDC provider) |
| 🛡️ oauth2-proxy | Auth gate — keeps SvelteKit auth-free |
| ☁️ Convex | Real-time cloud database |
Standard music analysis chokes on heavy distortion, blast beats, and alternate tunings. BandBox uses features that survive all three. For the full deep dive, see Audio Analysis.
HPSS Preprocessing — every recording is split into harmonic (guitar, bass, vocals) and percussive (drums, transients) layers via Harmonic-Percussive Source Separation. This single step dramatically improves both pitch and rhythm extraction.
Riff Segmentation — novelty detection on a self-similarity matrix built from spectral contrast and onset strength. A checkerboard kernel slides along the diagonal to find structural boundaries, merging short segments (<3s) and splitting long ones (>60s).
Fingerprinting — five features per riff, weighted adaptively based on riff type:
| Feature | Blast/Tremolo | Groove/Breakdown | What it captures |
|---|---|---|---|
| 🎵 Contour | 55% | 15% | Melodic shape via a three-method cascade (spectral centroid → rolloff → pYIN), normalized for tuning independence |
| 🥁 Groove | 10% | 35% | Beat-aligned 16-slot onset pattern — captures rhythmic identity |
| 🎯 Drums | 10% | 20% | Kick/snare patterns from the percussive layer — most consistent across takes |
| 🎸 Spectral | 5% | 10% | Tonal character per frequency band — captures the distortion signature |
| ⏱️ Tempo | 20% | 20% | BPM with double/half tempo detection — catches tracker ambiguity |
Weights shift automatically by measuring onset uniformity: uniform onsets (blast beats, tremolo) lean on contour; sparse onsets (grooves, breakdowns) lean on rhythm.
Matching — DTW with open begin/end on 200-point normalized contours (handles partial takes and tempo variation), cosine similarity on rhythm features. Double/half tempo detection ensures a riff tracked at 100 BPM still matches one tracked at 200 BPM.
Recordings flow through four stages. Each has clear ownership and retention rules.
💾 USB Stick ──→ 📂 Pi Staging ──→ 📥 Server Incoming ──→ 🎵 Processed Files
(keep) (temporary) (temporary) (permanent)
| Stage | What happens | Retention |
|---|---|---|
| 💾 USB Stick | Never modified by BandBox. Read-only mount. Band decides when to format. | ♾️ Band's responsibility |
| 📂 Pi Staging | New files copied here, deleted after server confirms upload. ~29 GB buffer. | 🗑️ Auto-deleted after upload |
| 📥 Server Incoming | WAV received via HTTP, manifest created for worker. | 🗑️ Deleted after processing |
| 🎵 Processed | FLAC master + Opus segments (song, pre, post). Metadata in Convex. | ♾️ FLAC never deleted |
Resilience:
- 🔌 Lost your Pi? Plug the USB into a new one. Duplicates are skipped by SHA-256 hash.
- 💥 USB stick died? FLAC masters are safe on the server.
- 💽 Server disk full? Opus files can be regenerated from FLACs.
- 🔄 Want to reprocess? The FLAC is always there.
- A server with Docker and Docker Compose
- A domain name pointed at your server
- A Convex account
cp .env.example .env
# Fill in: DOMAIN, PUBLIC_CONVEX_URL, CONVEX_HTTP_URL, PI_API_KEY, WORKER_API_KEY
# Generate a cookie secret (must be exactly 16, 24, or 32 raw bytes):
openssl rand -hex 16Then set the worker API key on your Convex deployment (must match the value in .env):
bunx convex env set WORKER_API_KEY "your-key-here" --prodStandalone (includes Caddy + Pocket-ID — everything in one box):
# First: uncomment caddy_data, caddy_config, and pocket_id_data
# in the volumes section of docker-compose.yml
docker compose --profile standalone up -dBring-your-own (you already have a reverse proxy and/or OIDC provider):
docker compose up -dThen add BandBox to your existing Caddy:
bandbox.example.com {
reverse_proxy localhost:48231
}That's it — oauth2-proxy handles authentication and proxies to SvelteKit internally. Set OIDC_ISSUER_URL in .env to point at your existing OIDC provider. Change the port with OAUTH2_PROXY_PORT if needed.
If using the bundled Pocket-ID (standalone profile):
Open https://your-domain/pocket-id and create your admin account (passkey). Then:
- Go to OIDC Clients → Create new client
- Set redirect URI to
https://your-domain/oauth2/callback - Copy the Client ID and Client Secret into
.env docker compose restart oauth2-proxy
If using an existing OIDC provider:
- Create an OIDC client with redirect URI
https://your-domain/oauth2/callback - Set
OIDC_ISSUER_URL,OIDC_CLIENT_ID, andOIDC_CLIENT_SECRETin.env docker compose restart oauth2-proxy
Each member registers in your OIDC provider (passkey, password, SSO — whatever it supports). BandBox doesn't need per-user features; the only question is "are you in the band?"
Follow the Pi Setup Guide to turn a Pwnagotchi into your recording uploader.
# Install
bun install
# Dev server (two terminals)
bun run dev # SvelteKit
bunx convex dev # Convex| Command | Description |
|---|---|
bun run dev |
Start development server |
bun run build |
Build for production |
bun run check |
Type-check the project |
bun run lint |
Lint and format check |
bun run format |
Auto-format all files |
bun run test |
Run unit tests |
- Audio Analysis Deep Dive — How BandBox recognizes riffs through distortion, blast beats, and alternate tunings
- Pi Setup Guide — Pwnagotchi setup, Arch Linux ARM, e-ink display
- Implementation Guide — Full technical spec, schema, audio pipeline details