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. Python/Essentia is not a startup dependency. A compatible runtime is needed to create or refresh Essentia evidence; Full genre classification and profile calibration consume current cached evidence and do not launch Python themselves.

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
  ├── 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. Changing the managed analyzer contract requires an Essentia schema/cache/profile review and version bump. 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 (capability-specific) — 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 into a managed CPython 3.14 runtime. Its exact Essentia/NumPy/PyYAML/six manifest governs analyzer compatibility; updates require cache-version, profile, and real-audio review. Essentia is an external AGPL-3.0-only package, not bundled with the MIT binary. Full classification requires fresh, valid Stratum and Essentia rows. Missing, stale, or invalid rows produce Degraded mode, cap confidence at Low, require review, and never auto-stage. A sparse payload that parses is still current; individual null detector values remain unknown. Profile calibration uses only complete Full-mode samples.

Without complete Essentia energy inputs, transition and pool scoring fall back to a BPM-based estimate; unavailable brightness/rhythm axes are excluded from their composites. Those workflows, metadata/export tools, explicit --stratum-only analysis, and server startup remain available without Essentia. 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.