Structure-Aware Cue Placement

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• crates/analysis/src/phrase.rs
• crates/analysis/src/bpm.rs
• apps/desktop/src-tauri/migrations/001_initial_schema.sql
• apps/desktop/src/services/api.ts
• crates/core/src/metadata.rs

Structure-Aware Cue Placement positions hot cues and memory cues automatically by analyzing a track's rhythmic and harmonic structure. The system detects phrase boundaries—such as transitions between intros, drops, and breakdowns—and snaps cues to metrical grid markers. This automation reduces manual preparation time by ensuring cues align with logical performance entry and exit points.

The process depends on the local analysis engine, which computes BPM, beat grids, and phrase segments entirely offline. Every automated cue includes provenance data, allowing you to review, edit, or reverse placement decisions.

Sources: README.md:129-132, crates/analysis/src/phrase.rs:7-17

Architecture and Data Flow

The cue placement system operates as part of the analysis pipeline. It transforms raw audio data into structured metrical segments, which are then stored as actionable cue points in the local database.

Analysis Pipeline Flow

The following diagram illustrates the progression from raw audio decoding to the generation of structure-aware phrase maps.

Phrase Segmentation Logic

Phrase segmentation identifies structural boundaries by measuring changes in audio features across the track's timeline. The system calculates a "novelty curve" to pinpoint significant transitions.

Analysis Components

1. Feature Aggregation: The system computes RMS energy (loudness), spectral flux (transient brightness), and 12-bin chroma (harmonic content) for every bar in the track.
2. Novelty Detection: Boundary novelty is calculated as a weighted sum of per-bar deltas.
   • Energy Step (50%): Captures loudness changes between sections.
   • Chroma Distance (30%): Detects harmonic shifts or key changes.
   • Spectral Flux (20%): Identifies changes in percussive or timbral intensity.
3. Metrical Snapping: The system moves detected boundaries to the nearest allowed phrase length, typically {4, 8, 16, 32} bars. It uses a snap_tolerance_bars (default: 2) to filter unsnappable candidates.

Sources: crates/analysis/src/phrase.rs:7-17, crates/analysis/src/phrase.rs:242-258, crates/analysis/src/phrase.rs:326-335

Section Labeling Heuristics

Each segmented phrase receives a heuristic label based on its energy profile relative to the rest of the track:

Label	Energy Profile
Intro	Quiet opening segment (Energy < 0.35).
Outro	Quiet closing segment (Energy < 0.35).
Drop	Near-peak energy segment (Energy >= 0.8).
Build	Energy rising by at least 25% into the next segment.
Breakdown	Mid-track energy dip (Energy < 0.45) between louder segments.
Phrase	Generic segment that fits no specific profile.

Sources: crates/analysis/src/phrase.rs:260-281, crates/analysis/src/phrase.rs:41-51

Data Model and Storage

Cues are stored in the cue_points table, linked to specific tracks. The schema distinguishes between different types of cues and their origins.

Cue Point Schema

Table: cue_points Field Definitions

Field	Type	Description
position_ms	INTEGER	Precise time in milliseconds from track start.
cue_type	TEXT	Categorized as 'hot_cue', 'memory_cue', or 'loop'.
slot	INTEGER	Hot cue slot index (1-8); NULL for memory cues.
source	TEXT	Identifies if the cue was 'ai_generated', 'user_custom', or 'imported'.
label	TEXT	Descriptive name (e.g., "Drop", "Breakdown").

Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:50-61, crates/analysis/src/phrase.rs:54-68

Configuration and Constraints

The PhraseOptions structure defines the constraints used during the analysis and snapping phase.

pub struct PhraseOptions {
    pub sample_rate: u32,
    pub frame_size: usize,
    pub hop_size: usize,
    pub target_peak: Option<f32>,
    pub allowed_lengths_bars: Vec<usize>,
    pub snap_tolerance_bars: usize,
}

Sources: crates/analysis/src/phrase.rs:104-111

If the system cannot establish a metrical structure (e.g., due to missing BPM or a grid with fewer than two bars), it returns an empty PhraseMap with 0.0 confidence rather than throwing an error. This allows the application to remain functional for tracks with ambiguous rhythms.

Sources: crates/analysis/src/phrase.rs:136-145

Summary

Structure-Aware Cue Placement leverages multi-feature audio analysis to automate DJ set preparation. By combining energy, timbre, and harmonic data with strict metrical snapping, the system identifies logical transition points. These points are stored as editable cue points, ensuring that automated decisions align with the 4/4 bar structures standard in electronic music.

Sources: README.md:129-132, crates/analysis/src/phrase.rs:1-20