Key & Phrase Segmentation
Relevant source files
The following files were used as context for generating this wiki page:
Key & Phrase Segmentation is a core analysis module within DJ-Assistant that determines the musical key and structural boundaries of audio files. The system computes these features locally using a combination of deterministic digital signal processing (DSP) and ONNX Runtime inference. By identifying Camelot keys and structural phrases, the application enables harmonic mixing and automated, structure-aware cue point placement.
Sources: README.md:104-106, CHANGELOG.md:85-98
Phrase Segmentation Architecture
The phrase segmentation system identifies metrical phrases and assigns heuristic section labels to different parts of a track. It relies on a BeatGrid as a metrical backbone to snap detected boundaries to bar-aligned positions.
Analysis Pipeline
The segmentation process follows a five-step deterministic path:
- Normalization: The system decodes audio to mono and resamples it to a standard analysis rate (typically 44.1 kHz).
- Feature Aggregation: The module computes RMS energy, mean spectral flux, and 12-bin chroma profile for every bar in the track.
- Novelty Detection: A boundary novelty curve is generated by calculating a weighted sum of per-bar deltas, including energy steps, chroma cosine distance, and flux steps.
- Grid Snapping: The engine snaps identified boundaries to unit lengths of {4, 8, 16, 32} bars, which are standard phrase units in electronic music.
- Section Labeling: The system analyzes the track-relative energy profile to assign labels such as "Intro," "Build," or "Drop."
Sources: crates/analysis/src/phrase.rs:7-25, crates/analysis/src/phrase.rs:120-134
Data Structures
The phrase segmentation module uses specific structures to represent the track layout:
| Structure | Description |
|---|---|
PhraseMap | Contains a list of phrases, overall confidence, and the method used (e.g., BeatGridNovelty). |
Phrase | Represents a single segment with start/end times (seconds), start bar, length (bars), and a SectionKind. |
SectionKind | Enum labeling segments as Intro, Build, Drop, Breakdown, Outro, or Phrase. |
Sources: crates/analysis/src/phrase.rs:37-86
Phrase Segmentation Flow
This diagram illustrates how raw audio is transformed into a metrical map.
The diagram shows the sequential processing steps from audio input to the final phrase map creation.
Sources: crates/analysis/src/phrase.rs:114-165
Key Detection and Mapping
Key detection identifies the tonal center of a track, allowing DJs to perform harmonic mixing. The system supports both classical notation (e.g., "A minor") and Camelot codes (e.g., "8A").
Remapping Logic
While the analysis engine detects keys via spectral analysis, the metadata module provides utilities to map classical key names found in file tags to the Camelot wheel. The mapping uses a lookup table where major keys follow a specific sequence (e.g., C major = 8B) and minor keys follow another (e.g., A minor = 8A).
Sources: crates/core/src/metadata.rs:374-415
Camelot Wheel Mapping Table
The following table demonstrates the mapping for several common keys:
| Classical Key | Camelot Code | Type |
|---|---|---|
| C Major | 8B | Major |
| A Minor | 8A | Minor |
| G Major | 9B | Major |
| E Minor | 9A | Minor |
| D Major | 10B | Major |
Sources: crates/core/src/metadata.rs:394-415
Persistence and Data Flow
Analysis results are persisted to a local SQLite database. The desktop application manages a background analysis queue that drains track IDs and updates their records upon completion.
Database Updates
When analysis finishes, the persist_analysis_results function updates the tracks table with the following fields:
bpm: Detected beats per minute.key_camelot: The Camelot code (e.g., "11A").key_classical: The standard musical name (e.g., "F# minor").loudness_lufs: Integrated loudness measured in LUFS.vocal_presence: A boolean indicating detected vocal content.phrase_confidence: A reliability score for structural segmentation.analysis_version: A composite stamp aggregating analyzer versions to drive future re-analysis.
Sources: apps/desktop/src-tauri/src/analysis.rs:33-58
Sequence of Analysis Persistence
This sequence diagram shows the interaction between the background thread, the analysis engine, and the database.
The diagram outlines the flow of analysis from the worker thread through the engine and into the database, ending with a UI event.
Sources: apps/desktop/src-tauri/src/analysis.rs:77-135
Summary
The Key & Phrase Segmentation system provides the structural and harmonic intelligence required for advanced DJ preparation. By automating the detection of bar-snapped phrases and Camelot keys, the module facilitates deterministic cue point placement and harmonic set building. All results are stored with an analysis_version stamp, ensuring that library data remains synchronized with the latest improvements to the underlying analysis algorithms.
Sources: README.md:104-118, CHANGELOG.md:85-115