https://github.com/ryan-voitiskis/reklawdbox
AI-powered Rekordbox metadata tool for genre tagging, classification, and library management.
https://github.com/ryan-voitiskis/reklawdbox
audio cli dj mcp
Last synced: 3 months ago
JSON representation
AI-powered Rekordbox metadata tool for genre tagging, classification, and library management.
- Host: GitHub
- URL: https://github.com/ryan-voitiskis/reklawdbox
- Owner: ryan-voitiskis
- License: mit
- Created: 2026-02-15T12:34:09.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T14:37:08.000Z (3 months ago)
- Last Synced: 2026-04-03T01:07:40.160Z (3 months ago)
- Topics: audio, cli, dj, mcp
- Language: Rust
- Homepage: https://reklawdbox.com/
- Size: 4.02 MB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# reklawdbox
MCP server for [Rekordbox](https://rekordbox.com/) 7.x library management.
Gives an AI agent full read access to your encrypted Rekordbox database, stages
metadata edits in memory, and exports Rekordbox-compatible XML for safe
reimport. The database is never written to directly.
**Docs, workflows, and tool reference: [reklawdbox.com](https://reklawdbox.com)**
## How it works
You have a conversation with Claude. Claude calls reklawdbox tools to search
your library, analyze audio, look up metadata from external sources, classify
genres, score transitions, and build DJ sets. When changes are proposed, they're
held in memory until you explicitly export them as an XML file. You then import
that file into Rekordbox yourself.
The result is an AI-assisted curation workflow where the agent handles the
tedious work (metadata lookups, genre classification, harmonic analysis,
set sequencing) while you retain full control over what actually changes in your
library.
### Workflows
The server includes step-by-step SOPs (standard operating procedures) compiled
into the binary. Call `help()` in conversation to see the workflow menu.
| Workflow | What it does |
| -------------------- | ------------------------------------------------------------- |
| Collection Audit | Fix naming, tagging, and convention violations |
| Metadata Backfill | Fill missing labels, years, albums from enrichment |
| Genre Classification | Classify ungenred tracks using enrichment + audio evidence |
| Genre Audit | Verify existing genre tags against evidence |
| Library Health | Scan for broken links, orphans, duplicates, coverage gaps |
| Set Building | Sequence DJ sets with transition scoring and energy shaping |
| Pool Building | Discover clusters of compatible tracks for live improvisation |
| Chapter Set Planning | Plan multi-chapter sets with bridge tracks |
| Batch Import | Tag, rename, and embed cover art for new music |
## Architecture
```mermaid
flowchart TB
claude(["Claude Code / Claude Desktop"])
claude <-->|"MCP (stdio)"| router
subgraph binary["reklawdbox (single Rust binary)"]
router["Tool Router"]
subgraph acquire["Acquire"]
library["Library Search"]
analysis["Audio Analysis
stratum-dsp + Essentia"]
enrich["Enrichment
Discogs · Beatport
Bandcamp · MusicBrainz"]
end
subgraph reason["Reason"]
classify["Genre Classifier
multi-evidence decision tree"]
scoring["Transition & Pool Scoring
multi-axis weighted"]
sets["Set Sequencer
beam search"]
end
subgraph stage["Stage & Export"]
changes["Change Manager
(in-memory)"]
xml["XML Export"]
end
router --> acquire
router --> reason
router --> changes
changes --> xml
end
library -.->|"read-only"| db[("Rekordbox master.db
(SQLCipher)")]
analysis --> files["Audio Files"]
enrich <--> cache[("Cache Store
(SQLite)")]
analysis --> cache
enrich --> broker["Discogs Broker
Cloudflare Workers + D1"]
enrich --> apis["beatport.com
bandcamp.com
musicbrainz.org"]
xml -->|".xml"| rb(["Rekordbox
File → Import Collection"])
rb -.->|"applies changes"| db
```
### Key design decisions
- **Read-only database access.** The Rekordbox `master.db` is opened via
SQLCipher with `SQLITE_OPEN_READ_ONLY`. No write path exists in the codebase.
- **Staged mutations.** All proposed changes live in an in-memory `ChangeManager`
until explicitly exported. You can preview, modify, or discard staged changes
before anything touches disk.
- **XML as the write path.** Rekordbox has no scripting API. The only safe
programmatic write path is XML import. The server generates
Rekordbox-compatible XML that you import yourself via File → Import Collection.
- **Separate cache store.** Enrichment results and audio analysis are cached in a
local SQLite database (WAL mode), separate from Rekordbox. Cache entries are
keyed by schema version and auto-evicted when the analysis pipeline changes.
- **Two-tier audio analysis.** [stratum-dsp](https://github.com/ryan-voitiskis/stratum-dsp)
(Rust, always available) handles BPM and key detection. [Essentia](https://essentia.upf.edu/)
(Python, optional) adds energy, timbre, rhythm, and spectral features. All
scoring axes degrade gracefully when Essentia is absent.
- **Broker-mediated enrichment.** Discogs API access is proxied through a
[Cloudflare Workers service](broker/) that handles OAuth, rate limiting, and
response caching. The Rust binary never holds Discogs consumer secrets.
- **SOPs compiled in.** Workflow procedures are embedded in the binary via
`include_str!` so documentation can't drift from the release.
## Install
Requires macOS on Apple Silicon (M1 or later) and Rekordbox 7.x.
```bash
brew tap ryan-voitiskis/reklawdbox
brew install reklawdbox
```
Then run interactive setup:
```bash
reklawdbox setup
```
This installs Essentia (audio analysis), configures Claude Code and Claude
Desktop, and verifies the Rekordbox database connection. See the
[install guide](https://reklawdbox.com/getting-started/) for details.
## Build from source
Requires the [Rust toolchain](https://rustup.rs/) and Xcode Command Line Tools.
```bash
git clone https://github.com/ryan-voitiskis/reklawdbox.git
cd reklawdbox
cargo build --release
```
The binary is at `./target/release/reklawdbox`.
## CLI subcommands
The binary runs as an MCP server by default. Subcommands are available for local
workflows outside your MCP host:
| Subcommand | Description |
| ------------------- | ------------------------------------------------------ |
| `setup` | Install Essentia and configure MCP hosts |
| `hydrate` | Batch enrichment + analysis (Discogs, Beatport, audio) |
| `analyze` | Batch audio analysis (stratum-dsp + Essentia) |
| `backup` | Manage Rekordbox library backups |
| `read-tags` | Read metadata tags from audio files |
| `write-tags` | Write metadata tags to audio files |
| `extract-art` | Extract embedded cover art from an audio file |
| `embed-art` | Embed cover art into audio files |
| `disconnect-broker` | Clear stored Discogs broker session |
Run `reklawdbox --help` for usage details.
## Development
```bash
cargo build --release
cargo test
cargo test -- --ignored # integration tests
dprint fmt && cargo fmt # format
dprint check && cargo fmt --check # verify formatting
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for expectations and workflow.
Agent-specific notes: [CLAUDE.md](CLAUDE.md), [AGENTS.md](AGENTS.md).
## Releasing
```bash
./scripts/release.sh 0.25.0
```
Tags and pushes. CI builds the binary, creates a GitHub Release, and updates the
[Homebrew tap](https://github.com/ryan-voitiskis/homebrew-reklawdbox).
## License
[MIT](LICENSE)