Data model

Technical reference for Helm DJ’s core objects. For the user-facing view of the same concepts, see Tracks & setlists.

An assignment is the central object — it binds a track to everything the system should do when that track plays.

Track identity (track key)

Every track is identified by a track key derived from what the CDJ broadcasts over Pro DJ Link — which for rekordbox media is the track’s ID within that USB’s exported database. Rekordbox assigns fresh IDs on every USB export, so the same audio file on two different sticks arrives with two different track keys.

Helm DJ bridges this with content matching (on by default): when a captured track’s content signature — normalised title + artist + rounded duration — matches an existing track, the new key is recorded as an alias of the existing canonical track rather than creating a duplicate. All assignment lookups and setlist membership checks resolve through the alias map, so cues and timecode carry across USB exports. The toggle lives in Settings → Devices → Track Matching; turning it off restores strict per-USB identity (for cloned-stick workflows).

Track repository

The track repository stores Track objects:

Field	Description
`track_key`	Identity key (see above)
`title` / `artist` / `album`	Metadata from Pro DJ Link
`duration_seconds`	Total track length
`bpm`	Base BPM from CDJ metadata
`waveform_points`	Waveform preview data (0–255 per point)
`waveform_color_segments`	Frequency band per point (0–7; bass→treble)
`content_key`	Content signature used for cross-USB matching (`title\|artist\|duration`)
`metadata_source`	`pro-dj-link`, `local-import`, or `manual`

Tracks persist in local storage across sessions.

Track lists (setlists)

Assignments are grouped into track lists. A track list is a named, ordered collection of tracks.

Field	Description
`list_id`	Unique ID (the default is `default-track-list`)
`name`	Display name
`tracks`	Ordered list of `TrackListEntry` records

The active track list is the one the cue engine fires from. Named lists let you manage separate show configurations — different support acts, a recurring night with a changing lineup.

Track list entries

track_key
captured_at_ms       — when the track first appeared in this list
source_deck_id       — which deck it was on
title_snapshot       — title at time of capture (display only)
artist_snapshot
bpm_snapshot
duration_snapshot_seconds

The snapshots are informational. The live assignment always uses current Pro DJ Link metadata.

Assignments

An assignment binds a (list_id, track_key) pair to show data:

Field	Description
`timecode_start_seconds`	Offset added to elapsed time for timecode output
`auto_arm_on_load`	Automatically arm this track’s cues when it loads
`cues`	List of cue definitions (see Cues & triggers)
`display_label`	Custom name shown in the track list (falls back to CDJ title)
`notes`	Free-text notes — shown in the editor, exported with the setlist
`audio_file_path`	Path to a local reference audio file
`audio_offset_seconds`	Offset (±) to align the audio file to the track’s start

Assignments are created automatically when a track is captured. An empty assignment (no cues) is a no-op.

Timecode start

timecode_start_seconds sets the timecode value at track position 0 — output is always start + elapsed. Give each track a distinct offset (commonly one hour apart) so downstream desks can identify the song from the timecode alone.

Reference audio

audio_file_path + audio_offset_seconds drive the local preview and waveform scrubbing. A positive offset means the audio file starts that many seconds after the track’s nominal start. Audio files are copied into app-local storage on import.

Assignment lifecycle

Track loads on CDJ
     │
     ▼
Track repository captures metadata
     │  (content matching may alias to an existing canonical track)
     ▼
Assignment service looks up (list_id, canonical track_key)
     │
     ├── Exists? → Return existing assignment
     │
     └── New?   → Create empty assignment, persist
                       │
                       ▼
                   Cue engine watches for trigger events

Assignments persist to local storage on every change (see the Saved cell in the health bar).

Setlist bundles

Setlists export as .helm bundle folders — setlist + assignments + cues + copies of reference audio. Export/import lives in Tracks → Track Migration → Setlist Manager. See Tracks & setlists.