DJ USB T[ool]kit 0.2.5

Chiph.art

10 min read Original article ↗

Overview#

DJ USB T[ool]kit is a local-first desktop app for getting DJ USB drives ready for CDJ/XDJ players. It needs no cloud connection and no account. The first public release (0.1.0) covered the core workflow: scan, build playlists, analyze, export, and diagnose and repair.

Version 0.2.5 is the latest release. This post covers what has changed since 0.1.0. The biggest addition is the cue point and beat-grid editor, which arrived in the 0.2 series. Alongside it came faster analysis and import, backups you can browse and restore, named drives, playlist reordering, and a wider set of repair tools.

What's new in 0.2#

Cue point and beat-grid editor#

Every track row now has a per-track editor, opened from the magnifier button next to its waveform. It shows the full-detail colour waveform with a beat-grid overlay.

Moving around

  • Scroll to zoom, drag to pan. The editor opens zoomed in on the first two minutes. A readout such as "0:00–2:00" under the waveform shows which part of the track you are looking at, with the track's length at the right end, and "Fit" shows the whole track.
  • Overview strip. A strip of the whole track under the waveform boxes the part in view and marks the cues. Click or drag it to move around.
  • Click to play from a point. The view follows the playhead.
  • Play and pause in the editor. Pausing holds the track where it is, and "+ Cue" drops a cue right at the paused spot.
  • Keyboard shortcuts. Space plays and pauses, C adds a cue at the playhead, 1–8 jump to cues A–H, and ←/→ move the selected cue one beat (with Shift, 10 ms).

Beat grid

  • Bar numbers and a brighter or fainter grid. Bars are numbered under the waveform, and a "Beat grid" slider sets how strongly the grid shows. Bar starts always stay visible.
  • Nudge the first beat one beat at a time to line up the grid, or type it in milliseconds.
  • Edit BPM and key in the same editor. The ÷2 and ×2 buttons fix a half- or double-tempo analysis in one click.
  • See the grid move as you edit. Changing the first beat or the BPM redraws the beat grid on the waveform right away, so you can line it up by eye before saving.
  • Hear the grid. A metronome clicks on the beat grid while the track plays, with an accent on every bar start. The clicks are mixed into the track itself, so they sit exactly on the beat you hear. A Mix slider balances the music against the clicks, so they cut through even a loud track.

Cues

  • Double-click to add a cue, or hit "+ Cue" while the track plays. You can add up to 8 cues. Each gets its own name and colour, and both can be edited.
  • Quantize. With "Q" on, which is the default, new and dragged cues snap to the nearest beat. Hold Shift to place a cue freely. With Q off, Shift snaps instead.
  • Drag cue points along the waveform to move them. A plain click on a marker still plays from that cue.
  • Undo and redo for BPM, key, first beat and cue edits, with buttons or Ctrl+Z and Ctrl+Shift+Z. The editor no longer closes on an outside click or Escape while you have unsaved changes.

Playback start

A toggle picks whether the CDJ loads a track at its first beat or at its first cue point. When the first beat is chosen, the track gets a playback-start marker: a memory cue without a hot-cue pad, listed first and shown apart from the other cues. The marker follows the first beat, and you can drag it anywhere before the first hot cue. The part of the waveform before the start point is greyed out. The app remembers your choice and uses it for every track you add cues to.

On the CDJ

Each cue is exported as both a memory cue and a hot-cue pad (A–H, with its colour). Cues are written to the local analysis files and to the USB's Rekordbox database, and they come back when a drive is imported again. The beat grid goes along with them, built from the track's BPM, so the tempo the CDJ shows is the one you set, whether it came from analysis or from the editor.

The editor works in every track list: Library, app playlists, USB playlists, and USB history. Editing a USB track writes the change straight onto the drive, so the CDJ sees it without a new export. The same edit also goes into the local library, so the two always stay in step.

Cue points and edited beat grids have been tested on real CDJ-2000NX and CDJ-2000NXS2 players. Cues trigger at their saved positions.

Faster analysis and import#

  • Track analysis is several times faster. The audio analysis engine is now compiled for speed.
  • USB import is much faster, especially from drives on spinning disks. The per-track work now happens only for tracks you actually open or add to a playlist.
  • Browsing USB playlists is quicker. The drive's databases are read once and kept in memory until they change, so scrolling, searching, and sorting are instant.

Also new since 0.1.0#

The releases between 0.1.0 and 0.2.0 added a lot around the core workflow, with a focus on big, real-world drives, including drives that rekordbox set up.

Library and analysis#

  • Analyze Selected. Select tracks in the Media Library and the "Scan Library" button becomes "Analyze Selected", so you can re-analyze just those tracks.
  • Pause, resume and cancel analysis from the progress bar. Tracks already in progress finish, and the timer picks up where it left off.
  • Analysis fits your machine. The number of analysis workers is set by available memory as well as CPU cores, so big batches run smoothly on laptops too.
  • Moved music folders. A missing source folder shows up as a warning chip instead of being treated as deleted. Point it at the new location and every track keeps its playlists.
  • CDJ-ready WAV files. WAV files with an extensible header are flagged during scanning, and export rewrites the header losslessly so they play on CDJs.
  • Warnings link to the Event Log. When a status message mentions warnings or errors, you can click it to jump straight to the details.

Playlists#

  • Drag to reorder tracks in an app playlist.
  • Sort to set the order. Sorting a playlist by a column sets its real, exported track order when you leave the playlist or export it.
  • Reorder USB playlists by dragging them in the USB Playlists panel. The new order is written to the drive, so CDJs and rekordbox see it too.

USB drives#

  • Name your drives. The first time you connect a drive, the app asks for a name and suggests the drive's own volume label. The name is stored on the drive, so it stays the same across ports and computers.
  • Status at a glance. The status bar shows the active playlist and the connected drive, with a coloured dot for the drive's health from the last diagnostics run.
  • Export history per drive. The app remembers every drive and what was exported to it, even when the drive isn't plugged in. The export log on the drive records whether each export was additive or mirror, and the tracks in playlist order.
  • Export Tracklist. Save a USB History session as a plain Artist - Title text file, starting from any track, with optional estimated times for each track.

Backups#

  • Backups panel (Settings → Open Backups) to list, restore and delete database backups. A backup is taken before every export, reorder, playlist removal, repair and menu change.
  • The newest backup stays on the drive, so it travels with it. Older ones move to a local cache, and you choose how many to keep.
  • Backups with context. Each backup shows why it was taken ("Before export", "Before repair") and how many playlists the drive had. Any backup can be restored, not just the latest.

Diagnostics and repair#

  • Interrupted exports. Diagnostics recognizes a database left half-written, for example when a drive is unplugged mid-export, and repair brings it back to a clean state.
  • Text field alignment. Diagnostics checks that every track and album text field sits where CDJ hardware expects it, and repair can move the ones that don't.
  • Remove Duplicate PDB Playlist Entries, a standalone repair that cleans up duplicate playlist entries without rewriting the whole database.
  • Playlist order checks. Strict parity diagnostics compare playlist order between the two USB databases, and repair brings them back in sync.

Text that won't freeze a CDJ#

Some track names can lock up a CDJ. Hardware testing for 0.1.2 found two: "zalgo" text, where dozens or hundreds of combining marks are stacked on a single letter, and short names that mix many unrelated scripts, such as Braille, Yi, Tibetan and Arabic in 25 characters. Either one froze the player's browse menu or track-load screen, even though the names were well inside the length limit. The real-world torture test was 00000ooooo's album "–5". rekordbox itself threw an "unexpected error" and broke playlists exporting the same album to a USB.

The app now tames such text on export, in titles, artists, albums, playlist names and file and folder names on the drive. Each letter keeps at most a handful of its marks, and a name keeps the first three scripts it uses. The same release fixed a freeze on non-ASCII album names. Non-ASCII titles and filenames, including extreme Unicode, are written exactly the way CDJ hardware expects.

Works with more drives and music#

  • Playlists of any size. Export handles playlists of hundreds of tracks, on fresh drives and on drives that already have a library.
  • Clean mirror and additive exports. Export keeps every file that is still in use and leaves the database tidy, however many times you re-export the same playlist.
  • rekordbox on macOS. The app finds the rekordbox library on current macOS installs.
  • Smoother on Windows. The optional essentia engine runs silently in the background.

Validated on real hardware#

Exports and repairs are checked on real players: CDJ-2000NXS2, CDJ-3000 and CDJ-3000X (all re-validated on 0.1.36), CDJ-2000NXS, and CDJ-2000NX / CDJ-2000NXS2 for the new cue editor. Testing covers whether the database is recognized, browsing playlists, loading tracks, playback, and triggering every saved cue. Every scenario passes on every tested device. Additive export to drives set up by rekordbox has worked since 0.1.0.

Technology#

The app is built with Rust and Tauri, and the frontend is plain HTML, JS, and CSS with no framework. SQLite stores the local library. On the USB, the app reads and writes the reverse-engineered CDJ database and analysis formats, with optional cross-checks against the Rekordbox database. The desktop app checks for updates and tells you when a new release is out. Since 0.2.5, a release with notable new features shows a "New features available" banner, and a release with a must-have fix shows a red "Critical update" banner.

Status & access#

License: AGPL-3.0-or-later (MIT up to 0.1.x)
Availability: Public release (v0.2.5), open source
Platforms: Linux (deb/rpm/AppImage), macOS, Windows
Requirements: Prebuilt binaries don't need Node.js. Building from source, or using the optional essentia analysis engine, does.

Download & support#

DJ USB T[ool]kit support