Library Cleanup

Start here

A guided clean-up for a messy library.

Safety: Can change files · asks first

Time: Several sessions; preparing a large library can run overnight and review time depends on library size.
You'll get: A cleaner, enriched, genre-ready library plus approved metadata XML files for manual Rekordbox import.

Files can change. The assistant must show you its plan and wait for approval. There is no automatic rollback, so keep a recoverable backup.

Review before import. Changes are prepared only. Approved export creates a backup and XML; import and verify it in Rekordbox, and keep the XML until then.

Online access: Online services are used only when the chosen step needs information that is not available locally.

Start with Session 1: Collection Audit. It is the first direct action in the full five-session path.

Before you start, consider running a Library Health scan to catch broken links, orphan files, and duplicates. Fixing structural issues first saves you from redoing work later.

Why order matters

Clean metadata > accurate enrichment > label data > genre signals

Enrichment matches on artist and title — typos cause missed matches. Genre classification uses enrichment and audio analysis as evidence. If you skip ahead, you’ll get worse results and end up re-running things.

Sessions

Session 1: Collection Audit

Requires reklawdbox connected

Paste into your agent:

Audit my collection for naming and tagging issues.

This fixes artist names, track titles, and file naming conventions. Getting these right first means better enrichment match rates in Session 2.

Collection Audit details

Checkpoint

No XML needed here — Collection Audit writes directly to files. If the agent lists successfully changed imported tracks, select only those tracks in Rekordbox and choose Reload Tag. This is a hard checkpoint: wait for the agent to verify a bounded sample of artist/title/album values before starting Session 2.

Reload Tag can overwrite intentional Rekordbox database-only edits with values from the audio files. For WAV files, label and track number are not available in RIFF INFO and will not update through Reload Tag.

Session 2: Enrichment

Requires Session 1 complete

Run this in your terminal (not through the agent):

reklawdbox hydrate --cpu overnight -y

This warms Discogs, Beatport, built-in Stratum analysis, and optional Essentia analysis. Bandcamp and MusicBrainz are targeted sources used later for remaining metadata gaps. --cpu overnight uses most of your cores; -y skips the confirmation prompt.

When it finishes, run reklawdbox hydrate again. Session 2 is complete when the selected hydration work finishes without pending or retryable failures. A cached no-match is a completed search, not a failed run or a required match.

Session 3: Metadata Backfill

Requires Session 2 selected hydration complete

Paste into your agent:

Find tracks missing labels and years in my collection and fill them from enrichment data.

Labels are the strongest genre signal for electronic music. Years give era context. The agent fills in what’s missing from enrichment data and shows you any conflicts for review.

Metadata Backfill details

Checkpoint

The agent will ask to export to XML. Approve, then import into Rekordbox:

Add XML to Rekordbox — Open Preferences → Advanced → rekordbox xml → Imported Library → Browse → select the exported XML file.
Verify in the XML view — In the sidebar, click the “Display rekordbox xml” icon. Browse the imported tracks under “All Tracks” and check that the metadata looks correct before importing.
Import into collection — Once satisfied, select all tracks (Cmd+A), right-click → Import To Collection. When prompted “Do you want to load information in the tag of the library being imported?”, click Yes (tick “Don’t ask me again” for bulk imports).

Start a fresh session for Session 4.

Session 4: Genre Classification

Requires Session 3 XML imported

Paste into your agent:

Classify genres for my ungenred tracks.

The agent normalizes any genre aliases first, then classifies tracks in batches. You review results grouped by confidence — high and medium confidence can usually be approved in bulk, while low confidence needs a closer look.

Genre Classification details

Checkpoint

Export to XML, import into Rekordbox. Verify a few genres look right, then start a fresh session for Session 5.

Add XML to Rekordbox — Open Preferences → Advanced → rekordbox xml → Imported Library → Browse → select the exported XML file.
Verify in the XML view — In the sidebar, click the “Display rekordbox xml” icon. Browse the imported tracks under “All Tracks” and check that the metadata looks correct before importing.
Import into collection — Once satisfied, select all tracks (Cmd+A), right-click → Import To Collection. When prompted “Do you want to load information in the tag of the library being imported?”, click Yes (tick “Don’t ask me again” for bulk imports).

Session 5: Genre Audit

Requires Session 4 XML imported

Paste into your agent:

Audit my existing genre tags.

This checks your existing genre tags against enrichment and audio evidence. It only shows you conflicts and things that need a second look — confirmed genres are skipped.

Genre Audit details

Checkpoint

Export to XML, import into Rekordbox. Spot-check the corrections.

Add XML to Rekordbox — Open Preferences → Advanced → rekordbox xml → Imported Library → Browse → select the exported XML file.
Verify in the XML view — In the sidebar, click the “Display rekordbox xml” icon. Browse the imported tracks under “All Tracks” and check that the metadata looks correct before importing.
Import into collection — Once satisfied, select all tracks (Cmd+A), right-click → Import To Collection. When prompted “Do you want to load information in the tag of the library being imported?”, click Yes (tick “Don’t ask me again” for bulk imports).

Skipping sessions

Metadata already clean? Start at Session 2.
Already hydrated? Re-run reklawdbox hydrate — if the selected Discogs, Beatport, and analysis work has no pending failures, jump to Session 3.
Labels and years present? Skip Session 3.
No ungenred tracks? Skip Session 4.
No existing genre tags? Skip Session 5.

Technical details

Technical details, safety, and recovery

Complete reference

Workflow contract

Direct file writes and staged metadata

Clean file metadata, hydrate evidence, backfill metadata, then classify and audit genres in an ordered five-session path.

Best for: New users and anyone preparing a disorganized library for reliable enrichment and DJ workflows.
Network: Network when neededHydration or gap research needs provider data that is not already cached; local audit and classification passes are cache-first.
Scope: Usually the full collection, with individual audit, hydration, and review passes scoped when needed.
Time: Several sessions; preparing a large library can run overnight and review time depends on library size.
Resuming: Session boundaries are checkpoints and caches/audit state persist. Bounded enrichment/audio preparation advances through page.next_offset while page.has_more, records failures, and retries failed explicit track IDs after traversal; restart at offset zero after selector/library-order changes, enrichment provider/cache-policy changes, or changed audio skip_cached/Essentia availability. Staged metadata is in memory, so export it before restarting the MCP host.
Result: A cleaner, enriched, genre-ready library plus approved metadata XML files for manual Rekordbox import.

What can change

Staged metadata: This workflow creates in-memory metadata changes for XML export.
Direct user files: Audio tags When needed — Session 1 finds and the user approves tag fixes.
File or directory moves/renames When needed — Session 1 finds naming issues on files that are not already imported into Rekordbox.
Local state: Audit state When needed — Session 1 is run; users with already-clean metadata can skip it.
Enrichment cache When needed — Selected Discogs, Beatport, Bandcamp, or MusicBrainz evidence is missing.
Audio-analysis cache When needed — Selected Stratum or optional Essentia analysis is missing.
Provider session When needed — Discogs authentication is required for uncached enrichment.
Files created: Rekordbox database backup On export — XML export proceeds only after the built-in backup succeeds or the configured custom script exits zero
Metadata XML file On export — Sessions 3–5 have approved staged metadata to export.

Before you start

reklawdbox connected to the intended Rekordbox library.
A file backup before direct tag or rename work.
Enough time to complete and verify each session checkpoint before moving on.

Approval checkpoints

Approve direct file fixes and complete the scoped Reload Tag checkpoint after Session 1.
Review conflicts and low-confidence recommendations before staging them.
Approve each XML export and verify its Rekordbox import before starting the next session.

Recovery

Re-run the audit or hydration pass after correcting unreadable files, provider errors, or incomplete coverage.
Clear and re-stage unwanted in-memory metadata before export.
Keep each XML file until its imported values are verified; direct audio-file changes require the user’s own file backup to undo.

Rekordbox handoff

Reload Tag for changed imported tracks When needed — After successful Session 1 tag changes to files already imported into Rekordbox; complete this before enrichment.
Metadata XML file On export — After each approved staged-metadata session.

What’s next

With your library clean, enriched, and genre-tagged, you’re ready for the good stuff:

Set Building

Build transition-scored DJ sequences with energy curve shaping. Build a set

Pool Building

Find compatible track pools for live improvisation. Build a pool

DJ Prompts

Gig prep, collection analysis, practice sessions, and more. Browse prompts