Constraint-Driven Set Builder
Relevant source files
The following files were used as context for generating this wiki page:
The Constraint-Driven Set Builder sequences music tracks into a performance-ready DJ set based on user-defined parameters. It converts natural language intent into structured constraints to automate track ordering. This system prioritizes harmonic compatibility, tempo trajectories, and energy profiles while remaining deterministic and auditable. Sources: README.md:162-167, README.md:218-228
System Architecture
The sequencing logic uses a hybrid approach involving a Large Language Model (LLM) for intent parsing and a deterministic algorithm for the final calculation. The system maintains a strict boundary between these two intelligences to ensure reproducibility. Sources: README.md:218-228
Components and Responsibilities
| Component | Responsibility |
|---|---|
| LLM (Cloud) | Parses natural language input into structured constraints (e.g., tempo arc, key strategy). |
| Beam Search Optimizer | Executes a deterministic search (Width=10) to decide the final track order. |
| Rust Core | Handles performance-critical scoring and database operations. |
| SQLite DB | Stores track metadata, cues, and set versioning data. |
Sources: README.md:162-167, README.md:218-228, README.md:243-248
Sequencing Data Flow
The following diagram illustrates how user intent becomes a sequenced set of tracks.
The Beam Search makes all ordering decisions based on Camelot compatibility, tempo delta, and energy scores. This process is independent of LLM availability once constraints are defined. Sources: README.md:218-228, CHANGELOG.md:104-106
Scoring and Constraints
The system evaluates potential track transitions using specific scoring variables. These scores ensure the set maintains harmonic and rhythmic flow.
Transition Scoring Variables
- Camelot Compatibility: Scores harmonic matches based on the Camelot wheel.
- Tempo Delta: Evaluates the difference in BPM between adjacent tracks.
- Energy Profile: Matches tracks based on their detected or tagged energy levels.
- Locks and Exclusions: Hard constraints that force the inclusion or removal of specific tracks.
Sources: README.md:162-167, README.md:218-228, CHANGELOG.md:104-106
Implementation Logic
The sequencing engine is implemented within the dj-assistant-core Rust crate. It utilizes metadata extracted during the analysis phase, such as BPM and Key, which are stored in the tracks table. Sources: README.md:323-328, apps/desktop/src-tauri/migrations/001_initial_schema.sql:12-41
-- Relevant fields for set building in the tracks table
CREATE TABLE tracks (
id TEXT PRIMARY KEY,
bpm REAL,
key_camelot TEXT,
key_classical TEXT,
vocal_presence INTEGER DEFAULT 0,
analysis_status TEXT NOT NULL DEFAULT 'pending',
user_rating INTEGER
);
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:12-41
User Workflow
Sequence building is stage four of the overall preparation pipeline. It occurs after tracks are analyzed, cleaned, and cued. Sources: README.md:195-216
- Input Intent: You describe the desired set (e.g., "warm-up set peaking near 128 BPM").
- Constraint Parsing: The LLM identifies specific targets for tempo, key, and energy.
- Deterministic Optimization: The Beam Search generates the sequence.
- Review Alternatives: You select between "safer" or "bolder" transition options provided by the optimizer.
- Export: The finalized sequence is exported to formats like rekordbox XML or Serato crates.
Sources: README.md:162-167, README.md:195-216, README.md:218-228
Sequence Persistence and Skills
Each sequencing operation is treated as a Skill. These are scoped processing units that record state changes in the skill_runs table. This architecture allows you to preview, apply, or undo automated sequencing decisions. Sources: README.md:195-197, apps/desktop/src-tauri/migrations/001_initial_schema.sql:53-62
Skill Run Data Model
| Field | Description |
|---|---|
skill_name | Identifies the operation (e.g., "Sequence"). |
before_state | A snapshot of the set before the skill execution. |
after_state | A snapshot of the set after the skill execution. |
status | The current state of the run: started, success, failed, or undone. |
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:53-62
The Constraint-Driven Set Builder provides a bridge between creative intent and technical execution. By separating natural language parsing from deterministic optimization, it ensures that DJ sets are both harmonically sound and fully reproducible without the risks of AI hallucination. Sources: README.md:218-228