Concepts

reklawdbox is an MCP server that sits between an AI agent and Rekordbox 7.x. It reads your encrypted database directly, stages metadata changes in memory, and exports Rekordbox-compatible XML for reimport.

Read-only database access

reklawdbox opens the Rekordbox master.db read-only via SQLCipher (AES-256-CBC, PBKDF2-HMAC-SHA512). The database is never modified.

• Auto-detects at ~/Library/Pioneer/rekordbox/master.db (override with REKORDBOX_DB_PATH)
• Key tables: djmdContent (tracks), djmdPlaylist, djmdSongPlaylist, plus lookup tables for artists, albums, genres, keys, labels, and colors
• BPM is stored as integer × 100 (128.50 BPM = 12850) — converted to float automatically

Caution

Never open master.db in a generic SQLite browser without SQLCipher support — you’ll see garbage data or corrupt it.

In-memory change staging

Changes to genre, comments, rating, color, label, year, or album are staged in memory — not written anywhere. You can review, modify, or discard freely before exporting.

• update_tracks — stage changes for one or more tracks
• preview_changes — review everything staged so far
• clear_changes — discard all staged changes

Nothing touches disk until you call write_xml. If the server restarts, staged changes are lost.

Tip

The agent calls preview_changes before every export so you can review exactly what will end up in the XML.

XML export (never direct DB writes)

write_xml produces a Rekordbox-compatible XML file. In Rekordbox: Preferences → Advanced → rekordbox xml → Imported Library, then import tracks to your collection. See XML Export for the full import workflow and known quirks.

Caution

XML reimport is additive only — it updates or adds tracks, never deletes them.

Local caching

A separate SQLite database (WAL mode) caches enrichment, audio analysis, and broker sessions. Safe to delete — data is re-fetched on next use.

• Default: ~/Library/Application Support/reklawdbox/internal.sqlite3 (override with CRATE_DIG_STORE_PATH)
• Enrichment cache: Discogs, Beatport, MusicBrainz, and Bandcamp metadata keyed by search terms
• Audio analysis cache: stratum-dsp and Essentia results keyed by file path and analyzer
• Broker sessions: OAuth tokens for the Discogs broker

Classification, set building, and transition scoring all read from cached data. Run enrichment and audio analysis first, then use the results downstream.

Tip

Use cache_coverage to check how much of your library has cached data before starting a workflow.

Human-in-the-loop

Every stage requires human approval:

• The agent proposes changes; you review via preview_changes before export.
• write_xml produces a file — you import it into Rekordbox yourself.
• Enrichment lookups populate the cache but never modify track metadata.

The agent handles the tedious work (genre normalization, key math, Discogs lookups). You make the final call on every change.

What reklawdbox does not do

• No DB writes. The only output is XML.
• No background process. Request-response only — your agent calls a tool, reklawdbox responds.
• No auto-sync. New Rekordbox tracks appear on the next read_library or search_tracks call.
• macOS Apple Silicon only. No Windows or Linux support.

Architecture

How the binary, database, external services, and audio pipeline connect. Read more

Harmonic Mixing

Camelot wheel, key compatibility scoring, and multi-axis transitions. Read more

Pool Discovery

Symmetric pool scoring, timbral similarity, and iterative pool expansion. Read more