DJ USB T[ool]kit
Overview
DJ USB T[ool]kit is a local-first desktop app for preparing DJ USB drives for CDJ/XDJ players, built as a real alternative to Rekordbox on Linux, and a lighter, no-account, no-cloud option on macOS and Windows too. It manages a local music library, builds playlists, analyzes tracks, and exports/repairs CDJ-compatible USB drives, all offline.
How It Works
The core workflow is built around fast prep, not full-library busywork:
- Point the app at your music folders. Indexing is fast and metadata-only, so tracks show up in the library immediately.
- Build or update the playlist you actually need for tonight's export.
- Run "Analyze Missing Tracks", which analyzes only the unanalyzed tracks in that playlist, not your whole library.
- Export once the missing-analysis count hits zero.
Analysis runs in the background in batches, and the UI updates each track row as its BPM, key, waveform, and artwork data complete, so there's no waiting for a full-library job to finish before you can start working.
Feature Deep Dive
Library scanning & analysis
Scanning and analysis are deliberately separate stages. Scanning is I/O-bound and stays conservative to keep large libraries stable; analysis is CPU-bound and runs with a parallel worker queue for throughput. BPM/key detection defaults to a native Rust engine with zero extra runtime setup. An optional alternate engine can be downloaded in-app from Settings if you want a different detection path. Waveform data is always generated natively in Rust, at two resolutions: a lightweight preview for the UI, and a higher-resolution detail buffer for the CDJ's on-screen waveform view. Bad or undecodable files are reported and skipped rather than aborting the whole batch.
Playlists & native playback
Playlists are ordered, stable lists backed by explicit position data, so tracks don't reshuffle on add/remove. Playback is backend-driven and source-aware: for tracks that came from an imported USB, the app only substitutes a local file when it can verify the identity match, falling back to playing straight from the USB otherwise. That avoids the classic failure mode of loose filename matching silently playing the wrong file.
USB import
Import reads and merges across the player database and the library database, tolerating incomplete or corrupted metadata on either side instead of failing outright. For large drives, import loads metadata first: playlists and track lists appear immediately, and expensive data like waveform previews and artwork are hydrated per-track only when you actually open them in the view. The parser also carries specific compatibility handling for row-count edge cases seen on real-world exports from other tools.
USB export
Export supports two sync modes: a mirror mode, where USB playlist membership exactly matches the local playlist, and an additive mode, where missing tracks are appended and existing playlist tracks are left alone. Both operate playlist-locally, so other playlists on the drive are untouched. Before writing, the player and library databases are backed up with a timestamp into a backups folder on the drive itself, so a bad export can be walked back. Under the hood, export patches the existing player database in place rather than rebuilding it from a static layout: history playlists, existing pages, tombstoned rows, and table-chain topology are preserved, and if a requested change can't be represented as a safe in-place patch, the write fails before committing rather than producing a player-corrupt file. Re-exporting the same playlist is deterministic and won't duplicate entries.
Diagnostics & repair
Diagnostics and strict-parity checking are separate concerns. One report answers "is this USB usable": database integrity, playlist resolution, analysis/media path presence. A stricter report answers a tougher question: do the two on-drive databases agree on every field, in the same order, with no orphaned or duplicate entries? A drive can be fully playable on hardware while still failing that strict check, and the app tells you which one you're looking at. Repairs always run preview-first, reporting proposed fixes and estimated writes/deletes before anything is applied, database backups are taken before any repair write, and the repair catalog covers everything from playlist-parity merges down to specific low-level database page-shape and footer-byte fixes for compatibility issues seen in real exports. Repair tools can also initialize a USB drive that's writable but missing the export database structure entirely.
Validated on real hardware
Beyond automated tests, export and strict-parity-repair output is validated on physical CDJ-2000NXS2 and CDJ-3000 units: USB recognition, database mount, playlist browsing, track load, and playback start are all confirmed working end to end, including after applying strict parity repairs.
Technology
Built in Rust and Tauri, with a vanilla HTML/JS/CSS frontend (no framework). Local library data is stored in SQLite. USB read/write targets the CDJ player's binary database format and its companion library database format, both handled through specifications reverse-engineered from the open-source community, plus optional cross-reference against Rekordbox's own master database on import.
Status & Access
Publicly released (v0.1.0), MIT-licensed and open source. Prebuilt installers are available for Linux (deb/rpm/appimage), macOS, and Windows. The app works fully without Node.js when using prebuilt binaries and the default analysis engine; Node is only needed to build from source or to use the optional alternate analysis engine. Actively maintained, with automated backend and frontend test coverage across scanning, analysis, playlists, playback, import, export, and diagnostics/repair. Source code and downloads are on GitHub; donations are supported through the project website.
