Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
DJ Assistant accelerates music library preparation for professional DJ performances. The application automates mechanical tasks including metadata cleanup, audio analysis, cue point placement, and set sequencing. It operates as a local-first desktop application, ensuring that audio files never leave the user's machine.
The project follows four core principles: local-first operation, non-destructive processing, user-in-the-loop control, and transparent sequencing logic. It functions as a companion to industry-standard software like rekordbox and Serato rather than a replacement for live mixing platforms.
Sources: README.md:1-26, README.md:89-100
Preparation Pipeline
The preparation workflow consists of five distinct stages termed "Skills." Each stage provides a preview and supports reversible actions through a state snapshot system.
- Analyze: Computes BPM, key, beat grid, phrase boundaries, vocal presence, and loudness locally via ONNX Runtime.
- Clean: Normalizes artist and title metadata using fuzzy clustering without modifying source audio files.
- Cue: Generates hot and memory cues based on detected phrase boundaries and genre-specific templates.
- Sequence: Orders tracks using a deterministic Beam Search optimizer based on harmonic, tempo, and energy constraints.
- Export: Produces rekordbox XML, Serato crates, and Pioneer-compatible USB media.
Sources: README.md:32-41, README.md:126-150
Processing Flow
The following diagram illustrates the path from library import to final export.
The diagram shows the logical progression of track processing where automated gates allow for manual intervention when AI confidence is low.
Sources: README.md:126-150
System Architecture
DJ Assistant utilizes a monorepo structure containing multiple Node.js packages and Rust crates. The desktop application uses Tauri v2 to bridge a React-based frontend with a high-performance Rust core.
Core Components
- Desktop Shell (Tauri v2): Manages window lifecycle and secure IPC.
- Frontend (React 18): Provides the Library UI, Waveform editor, and Set Builder.
- Rust Core: Handles file scanning, BLAKE3 fingerprinting, and SQLite database management.
- Audio Engine: Decodes audio via Symphonia and executes ONNX inference for analysis.
Sources: README.md:183-200, README.md:270-280, apps/desktop/src-tauri/Cargo.toml:17-30
Architecture Overview
This diagram represents the structural boundaries where performance-critical tasks remain local, and external connectivity is strictly metadata-focused and optional.
Sources: README.md:175-215
Data Model
The application stores all library metadata and process states in a local SQLite database using Write-Ahead Logging (WAL) for concurrency.
Database Schema
| Table | Purpose | Key Fields |
|---|---|---|
workspaces | Isolates different libraries | id, name, created_at |
tracks | Stores metadata and analysis results | file_path, file_hash, bpm, key_camelot, analysis_status |
cue_points | Stores generated and custom cues | track_id, position_ms, cue_type, slot |
skill_runs | Tracks process history for undo/redo | skill_name, before_state, after_state, status |
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:5-75
Technology Stack
The project leverages modern web and systems programming tools to ensure safety and performance.
| Layer | Technology |
|---|---|
| Shell | Tauri v2 |
| Frontend | React 18, TypeScript 6, Vite 8, Tailwind CSS v4 |
| Backend (Core) | Rust 1.82+, SQLite |
| Audio Processing | Symphonia (Decoding), ONNX Runtime (Inference) |
| Package Management | pnpm 10.14+ |
Sources: README.md:283-294, package.json:5-15, apps/desktop/src-tauri/Cargo.toml:17-30
Development and Contribution
The project is organized as a pnpm workspace. Developers use specific scripts to maintain code quality across the multi-language codebase.
- pnpm ci:local: Runs the full suite of linters (Prettier, ESLint), typechecks, and tests (Cargo and Node).
- Conventional Commits: All contributions must follow standard commit formatting (e.g.,
feat(analysis): ...,fix(desktop): ...). - Phase Status: The project is currently in Phase 1 (Analysis Engine). Foundation tasks (Phase 0) including scanning and fingerprinting are complete.
Sources: package.json:16-25, CONTRIBUTING.md:6-12, CHANGELOG.md:120-135
Summary
DJ Assistant provides a local, automated solution for DJ set preparation. By combining a Rust-powered audio engine with a React frontend, it enables rapid, non-destructive library management. The system maintains high technical standards through a strictly typed IPC bridge, comprehensive fixture testing, and a reversible skill-based processing model.