Architecture

Overview

reklawdbox is a single binary that talks to your AI agent over stdio. It reads your Rekordbox database, fetches metadata from external services, analyzes audio, and exports XML. No runtime dependencies beyond an optional Python install for Essentia.

Data flow

Your AI agent (Claude Code / Claude Desktop / Codex)
  │
  │  stdio
  ▼
reklawdbox
  ├── Rekordbox master.db ──── read-only, encrypted
  ├── Local cache ──────────── enrichment, audio analysis, sessions
  ├── Discogs broker ───────── OAuth proxy for metadata lookups
  ├── Beatport ─────────────── metadata extraction (no API key needed)
  ├── Audio analysis ───────── tempo/key, rhythm/structure, dynamics, timbre
  └── XML output ───────────── Rekordbox-compatible export files

Rekordbox database

Rekordbox 6/7 encrypt master.db with SQLCipher. reklawdbox bundles everything needed to decrypt it and opens it read-only.

Key tables

Table	What’s in it
djmdContent	Tracks (title, artist, genre, BPM, key, rating, comments)
djmdPlaylist	Playlists and folders
djmdSongPlaylist	Which tracks are in which playlists
djmdArtist, djmdAlbum, djmdGenre, djmdKey, djmdLabel, djmdColor	Lookup tables

Discogs broker

Discogs requires OAuth for API access. A companion service on Cloudflare Workers handles this so reklawdbox never holds consumer secrets directly.

1. Ask the agent to look up any track on Discogs.

2. On first use, you get an authorization URL — open it in your browser and approve.

3. After that, lookups work automatically. Your session is stored locally in macOS Keychain.

The broker is open-source and self-hostable if you prefer. See Environment Variables for configuration.

Audio analysis

Two analysis backends are cached per track and reused while their schema, audio-file identity, and analyzer-specific inputs remain current. An audio-file identity change invalidates both backends. A Stratum schema change invalidates only Stratum, and an Essentia schema change invalidates only Essentia. A Rekordbox grid change also invalidates only Stratum.

Built-in (stratum-dsp) — BPM/key confidence, grid provenance and stability, decay, dub-stab and kick-pattern evidence, and structural sections in Rust. Always available, no setup needed.

Essentia (optional) — adds integrated loudness, danceability, rhythm and onset evidence, brightness, and other spectral/timbral features via a Python subprocess. It has no returned energy field. Transition and pool scoring derive energy from danceability, integrated loudness, and onset rate only when all three are present. Installed by reklawdbox setup.

Without complete Essentia energy inputs, scoring falls back to a BPM-based estimate; unavailable brightness/rhythm axes are excluded from the transition composite. Classification, transition scoring, pool scoring, audit, calibration, and audio-profile summaries each use only a subset of the returned evidence. See the canonical audio evidence and consumers table.

CLI

The same binary also works as a standalone CLI — no AI agent needed. Useful for batch operations:

Command	What it does
hydrate	Batch enrichment + audio analysis
analyze	Audio analysis only
backup	Manage Rekordbox library backups
read-tags / write-tags	Read or write audio file tags
extract-art / embed-art	Cover art operations
setup	Install Essentia and configure MCP hosts

See CLI Commands for details.