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 ───────── BPM, key, energy, danceability, spectral features
  └── 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, both cached per track so they only run once:

Built-in (stratum-dsp) — BPM and key detection in Rust. Always available, no setup needed.

Essentia (optional) — adds danceability, rhythm regularity, brightness (spectral centroid), loudness, onset rate, and dynamic complexity via a Python subprocess. These features are combined to produce energy scores and improve genre classification, set building, and pool discovery significantly. Installed automatically by reklawdbox setup.

Without Essentia, energy scoring falls back to a BPM-based estimate and brightness/rhythm axes are dropped from transition scoring.

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.