GitHub - haivala/dj-usb-tkit: DJ USB T[ool]Kit, Local-first DJ library manager — scan, analyze, export and possibly repair broken USB drives compatible with Pioneer CDJ players and rekordbox

GitHub

5 min read Original article ↗

Local-first DJ library manager and USB exporter built with Rust + Tauri.

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

DJ USB Tkit screenshot

Installing a Prebuilt Release

macOS

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.

Current Capabilities

  • Library scanning, playlist management, and native local playback.
  • USB import/export with mirror and additive playlist sync modes.
  • Local BPM, key, waveform, and artwork analysis for missing track metadata.
  • 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.
  • 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.

Design Goals

  • 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 (Settings → Open Backups). 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.

Project code is licensed under AGPL-3.0-or-later; 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.

Prerequisites

  • Rust (stable)
  • Node.js 24 LTS (required for frontend build/tests and optional Essentia runtime path)
  • 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.

System Libraries

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.

Build & Run

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).

Release Bundles

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

macOS

Install prerequisites and build with:

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

Windows

Open PowerShell as Administrator and run:

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

Linux

Build installers/packages with:

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.
  • The Tauri UI does not require Node at runtime.

Examples:

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

Artifacts are written under:

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

Project Structure

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

Donate

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

Support DJ USB Tkit on chiph.art