Accurate music metadata for Rekordbox libraries, sourced from Beatport.

How to run • Technical analysis

---

Clean metadata Key, BPM, label, genre, release date-kept consistent and reviewable.

Auditable matches Every query and candidate is logged so decisions are traceable.

Built for scale Handles large libraries with parallel search and time budgets.

What is Cuepoint

DJs use an app called Rekordbox to import downloaded songs, sort them into playlists, and export them to USBs for performance. To play reliably, each track needs metadata like musical key, label, and release date. The official source for this data is Beatport.com. CuePoint takes a Rekordbox XML export of its playlists, matches each track to Beatport, and outputs clean metadata you can review or import back into your library. It keeps a full audit trail of queries and candidates so you can verify every decision.

Context

• Rekordbox: DJ library software used to organize music, playlists, and performance data.
• Beatport: Online music store with official release metadata (label, release date, genre, key, BPM).

CuePoint bridges Rekordbox (your library) and Beatport (official metadata) so you don’t have to fix this by hand.

Why it matters

Manual matching is slow and inconsistent. Accurate keys, labels, genres, and release dates matter for sets, exports, and library hygiene. Beatport has the official info, but copying it track‑by‑track is a time sink.

What’s implemented

• Update manager: in‑app update checks, download flow, and installer handoff
• Auto‑research: optional second‑pass search for missed matches
• Config system: YAML config + CLI overrides for repeatable runs
• Caching: request caching to speed up repeated runs
• Audit logging: query and candidate logs for verification
• GUI + CLI: run via desktop UI or command line

How to run

See docs/how-to-run.md for:

• Install from GitHub Releases
• Build locally
• Run the GUI directly

UI

Quick demo

What you get

• Clean metadata: key, BPM, label, genres, release details
• Review workflow: low‑confidence rows flagged for manual pass
• Audit trail: every query and candidate recorded

Before / After

Before (Rekordbox export)	After (CuePoint)
Missing key, label, release date, genre	Key, label, release date, genre filled in
Manual lookup track‑by‑track	Batch matching with review flags
No audit trail	Queries + candidates logged for verification

How it works (short)

1. Parse the Rekordbox XML export.
2. Generate multiple search queries per track.
3. Search Beatport and collect candidates.
4. Score candidates and apply guards.
5. Write results and review files.

Architecture

flowchart LR
  RekordboxXML[Rekordbox_XML] --> Parser[Input_Parsing]
  Parser --> QueryGen[Query_Generation]
  QueryGen --> Search[Beatport_Search]
  Search --> Parse[Candidate_Parsing]
  Parse --> Scoring[Scoring_and_Guards]
  Scoring --> Decision[Match_Decision]
  Decision --> MainCSV[Main_CSV]
  Decision --> CandidatesCSV[Candidates_CSV]
  Decision --> QueriesCSV[Queries_CSV]
  Decision --> ReviewCSV[Review_CSV]

  subgraph Search_Strategy
    Direct[Direct_Search]
    DDG[DuckDuckGo]
    Browser[Browser_Automation]
  end
  Search --> Direct
  Search --> DDG
  Search --> Browser

Loading

Technical analysis

Deeper technical details, pipeline notes, and constraints live in .github/TECHNICAL_ANALYSIS.md.

Inputs

• Rekordbox XML export file
• Playlist name (must match the XML playlist name exactly)

Support policy

• Supported OS: Windows 10+ (x64), macOS 12+ (Intel/Apple Silicon)
• Rekordbox export: XML export format from recent Rekordbox versions
• File size guidance: XML exports <= 100MB recommended (larger files can be slower)

See docs/user-guide/support-policy.md for update cadence and end-of-life policy.

Project layout

• src/cuepoint: application code
• src/tests: canonical tests
• scripts/: utilities

License

See THIRD_PARTY_LICENSES.txt and repository notices.

---

Get started