DJ USB Tkit

Local-first DJ library manager — scan, analyze and export playlists to USB for Pioneer CDJ/XDJ, rekordbox and Engine DJ players (Denon, Numark), and repair broken USB drives. Built with Rust + Tauri.

Prebuilt installers for macOS, Windows, and Linux are on the Releases page.

The .dmg builds are not signed with an Apple Developer certificate or notarized, so Gatekeeper will refuse to open the app on first launch ("DJ USB Tkit is damaged and can't be opened" or "the developer cannot be verified").

To run it:

1. Open the .dmg and drag DJ USB Tkit to /Applications.

2. Clear the extended attributes macOS added to the download:

   xattr -cr "/Applications/DJ USB Tkit.app"

3. Launch the app normally. If you skipped step 2, you can instead right-click (or Control-click) the app icon, choose Open, and confirm once — but the xattr command is the reliable fix on Apple Silicon.

This only needs to be done once per installed version. Building from source (see below) also avoids the prompt.

Download the .AppImage, .deb, or .rpm from the Releases page. The prebuilt packages need glibc 2.35 or newer (Ubuntu 22.04, Linux Mint 21, Debian 12, Fedora 36, or later).

For the AppImage, make it executable and run it:

chmod +x DJ_USB_Tkit_*_amd64.AppImage
./DJ_USB_Tkit_*_amd64.AppImage

If rekordbox runs under Wine, use this Linux build, not the Windows one: the Windows build's interface (WebView2) stays blank under Wine. The Linux build finds rekordbox's library in $WINEPREFIX, ~/.wine, or a Bottles bottle. For a prefix somewhere else, start the app with WINEPREFIX=/path/to/prefix (see docs/EXTERNAL_LIBRARIES.md).

If the window stays blank or black, or the app closes right after it opens, start it with the GPU renderer turned off:

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./DJ_USB_Tkit_*_amd64.AppImage

The app then draws on the CPU, which uses more CPU during long exports and analysis runs.

• Library scanning, playlist management, and native local playback.
• Import tracks and playlists from a rekordbox or Mixxx library on the same computer, including their hot cues (see docs/EXTERNAL_LIBRARIES.md).
• USB import/export with mirror and additive playlist sync modes.
• An Engine DJ library on the USB for Denon and Numark players, kept in step with every change to the stick, so they get the app's beat grids and waveforms without analyzing every track again. Off by default: turn on Settings → Export → "Write Engine DJ library" (see docs/ENGINE_DJ.md).
• Local BPM, key, waveform, and artwork analysis for missing track metadata.
• A cue editor for setting a track's hot cues, memory cues, beat grid, key, genre, star rating, and where the CDJ starts playback, from the library or straight on a connected USB (see Cue Editor below).
• USB diagnostics, strict parity reporting, and preview-first repair actions.
• Repair tools can help recover some broken USB database states; backups are created before repair writes, but recovery is not guaranteed.
• USB initialization for drives that are writable but missing the expected export database structure.
• USB drives can be given a persistent name, so the same physical drive keeps its identity across replugs, ports, and computers. What selecting a USB does, and what changes while one is connected, is in docs/USB_CONNECT.md.
• A dedicated Backups panel to list, restore, and delete USB database snapshots, with configurable retention.
• Automated backend and frontend coverage for core workflows, export behavior, diagnostics, and UI interactions.

Open it with the magnifier button next to an analyzed track's waveform, in the library, an app playlist, a USB playlist, or USB history. It shows the track's full-detail colour waveform with the beat grid over it.

• Hot cues: up to 8, lettered A–H by position, each with a name and colour. Add them by double-clicking the waveform, with "+ Hot cue" or with C while playing; drag markers to move them. Quantize (Q) snaps cues to the beat, and Shift places one freely.
• Beat grid: fix the BPM (type it, nudge it by 0.01, or ×2 / ÷2 for a half or double tempo analysis), move the first beat, and set the key.
• Playback start: choose whether the CDJ loads the track on the first cue or on the first beat, as a memory cue with no hot-cue pad.
• Listening: play and pause in the editor, with a metronome that clicks on the grid so you can hear whether it lines up, and a Mix slider to balance the clicks against the music.
• Editing: undo/redo, keyboard shortcuts, and zoom, pan and a whole-track overview strip.

Each hot cue is exported as both a memory point and a hot-cue pad. Memory cues (memory points without a pad, any number, with name and colour, as rekordbox makes them) are shown as ▼ flags, edited in one compact slot, added with M, and kept through import, editing and export. Saving from a USB row writes the change straight onto the USB (no re-export needed) and into the local library. Full details, shortcuts and the storage format are in docs/CUE_EDITOR.md.

• Local-first desktop workflows — no cloud dependency for indexing, playlists, USB import/export, diagnostics/repairs, or playback.
• Fast prep flow: index library quickly, build playlists, analyze only missing tracks for the target playlist, then export.
• Strict parity reporting is kept separate from operational passability, so users can distinguish "works" vs "fully parity-clean" outcomes.
• Pluggable analysis engine: stratum (default) and optional essentia.

Detailed behavior and requirements are documented under docs/, starting with docs/README.md; command reference details are in docs/COMMANDS.md. See docs/COMPARISON.md for how this differs from rekordbox.

Warning: This software writes to DJ USB drives and library databases. Use it at your own risk: the author and maintainers are not responsible for broken USB exports, corrupted databases, data loss, or other damage to your USB drive. Always keep your own backups.

The app creates timestamped backups of the existing PDB/eDB database files before every export, playlist reorder/removal, repair, or menu-config write. The newest backup always stays on the USB drive in PIONEER/rekordbox/backups/; older ones are moved to a local cache to avoid filling up the drive. Backups can be browsed, restored, or deleted from the Backups panel (the Backups button on the USB page). The repair tools have also recovered broken USB database states in real use, but recovery is not guaranteed. This software is provided without warranty; see LICENSE.

Copyright (c) DJ USB Tkit contributors. Project code is licensed under AGPL-3.0-or-later (full text in LICENSE); contributions are accepted under the same terms (inbound = outbound). See CONTRIBUTING.md. A redistribution-focused dependency/license audit is tracked in docs/THIRD_PARTY_LICENSES.md.

• Rust (stable)
• Node.js 24 LTS (24.15 or newer) or 26 (required for frontend build/tests; the optional Essentia engine uses whichever node is installed)
• System libraries for Tauri v2 (see below)
• Tauri CLI v2 for release bundles:

cargo install tauri-cli --version '^2'

Ensure ~/.cargo/bin is available in PATH.

Arch Linux:

sudo pacman -S --needed webkit2gtk-4.1 gtk3 libappindicator-gtk3 librsvg base-devel openssl pkg-config

Ubuntu / Debian:

sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev build-essential libssl-dev pkg-config

Fedora:

sudo dnf install webkit2gtk4.1-devel gtk3-devel libappindicator-gtk3-devel librsvg2-devel gcc gcc-c++ openssl-devel pkg-config

For other distros see the Tauri prerequisites docs.

cd desktop/src-tauri
cargo build
cargo run

cargo run does not require Tauri CLI. Tauri CLI is required for release bundle builds (tauri build).

Published builds are available on the Releases page. To build your own:

Install prerequisites and build with:

chmod +x scripts/macos-build-setup.sh
./scripts/macos-build-setup.sh

Open PowerShell as Administrator and run:

powershell -ExecutionPolicy Bypass -File scripts\windows-build-setup.ps1

Build installers/packages with:

./scripts/release.sh

The script stages a clean frontend bundle into vanilla-ui/dist (excluding development folders such as node_modules) before packaging. On Linux, the default bundles are deb,rpm,appimage. AppImage packaging requires a working linuxdeploy binary on PATH. When AppImage is included, the script also sets NO_STRIP=1 by default to avoid linuxdeploy strip failures on RELR-enabled system libraries (common on Arch and newer distros). Set LINUXDEPLOY_NO_STRIP=0 to disable. Release builds do not bundle Essentia assets or a Node runtime. The app works without Node when using prebuilt binaries and the default stratum analysis engine. Node is only needed when building from source (frontend/tooling) or when enabling the optional Essentia analysis engine. Essentia can be downloaded in-app from Settings when the user enables the Essentia engine.

Linux packaging notes:

• The AppImage bundles most GUI/runtime dependencies needed by the Tauri/WebKit stack (for example webkit2gtk, gtk-3, libsoup, javascriptcoregtk, glib, gio, pango, and cairo).
• Core system libraries remain host-provided, following normal AppImage practice. This includes libraries such as libc, libm, libpthread, libstdc++, libX11, and libasound.
• Published release builds are made in an Ubuntu 22.04 container (scripts/linux-release-docker.sh), so they need glibc 2.35 or newer. ./scripts/release.sh builds against your own system's glibc, so its AppImage only runs on systems at least as new as yours. Use scripts/linux-release-docker.sh for a portable build.
• The AppImage, deb, and rpm include AppStream metadata (usr/share/metainfo/art.chiph.djusbtkit.metainfo.xml) for software centers and AppImage managers.
• The Tauri UI does not require Node at runtime.

Examples:

./scripts/release.sh
BUNDLES=deb,rpm ./scripts/release.sh

Artifacts are written under:

target/release/bundle

For release build workflow and publication checks, see docs/RELEASE_BUILD_INSTALL.md.

backend/       – Rust library: data model, SQLite storage, commands
desktop/       – Tauri host app
vanilla-ui/    – Frontend (vanilla HTML/JS/CSS)

If you find this app useful, consider supporting the developer.

Support DJ USB Tkit on chiph.art