Mixing & Sequencing
Score transitions and build DJ sets using six-axis scoring (key, BPM, energy, genre, brightness, rhythm), plus discover compatible track pools using the symmetric seven-axis pool kernel. See Harmonic Mixing for the transition scoring model and Pool Building for the pool discovery workflow.
score_transition
Section titled “score_transition”Score a single transition between two tracks across all six axes plus a weighted composite.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
from_track_id |
string | yes | Source track ID | |
to_track_id |
string | yes | Destination track ID | |
energy_phase |
string | ["warmup", "build", "peak", "release"] |
Energy phase | |
priority |
string | object | Transition weight spec (see below) | ||
master_tempo |
boolean | Master Tempo mode (default: true) |
||
harmonic_style |
string | ["conservative", "balanced", "adventurous"] |
Harmonic mixing style |
When master_tempo is false, the scorer accounts for pitch shift from BPM adjustment when evaluating key compatibility — a track sped up by 3% shifts its effective key by ~0.5 semitones.
query_transition_candidates
Section titled “query_transition_candidates”Rank pool tracks as transition candidates from a reference track, sorted by composite score.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
from_track_id |
string | yes | Source track to transition from | |
pool_track_ids |
string[] | Pool of candidate track IDs to rank | ||
playlist_id |
string | Use a playlist as the candidate pool | ||
target_bpm |
number | Target BPM — scores how well each candidate fits | ||
energy_phase |
string | ["warmup", "build", "peak", "release"] |
Energy phase | |
priority |
string | object | Transition weight spec (see below) | ||
master_tempo |
boolean | Master Tempo mode (default: true) |
||
harmonic_style |
string | ["conservative", "balanced", "adventurous"] |
Harmonic mixing style | |
limit |
integer | Max results (default: 10, max: 50) |
Provide either pool_track_ids or playlist_id to define the candidate pool.
build_set
Section titled “build_set”Generate candidate DJ set sequences from a track pool using beam search with energy-curve shaping.
| Parameter | Type | Required | Values | Item values | Description |
|---|---|---|---|---|---|
track_ids |
string[] | yes | Pool of candidate track IDs (pre-filtered) | ||
target_tracks |
integer | yes | Desired number of tracks per candidate set | ||
priority |
string | object | Transition weight spec (see below) | |||
energy_curve |
string or string[] | ["warmup_build_peak_release", "flat", "peak_only"] |
["warmup", "build", "peak", "release"] |
Preset or custom phase array | |
start_track_id |
string | Force a specific opening track | |||
beam_width |
integer | Search width: 1 = greedy/fast, higher = broader (default: 3, max: 8). Supersedes the deprecated candidates parameter. |
|||
candidates |
integer | Deprecated candidate count; use beam_width instead |
|||
harmonic_style |
string | ["conservative", "balanced", "adventurous"] |
Harmonic mixing style | ||
master_tempo |
boolean | Master Tempo mode (default: true) |
|||
bpm_drift_pct |
number | Max BPM drift from start track as % (default: 6.0) |
|||
bpm_range |
number[] | [start_bpm, end_bpm] — plans a BPM trajectory across the set |
Energy curve presets: "warmup_build_peak_release" (default), "flat", "peak_only". Pass a custom array of phase strings for full control (e.g., ["warmup", "build", "build", "peak", "peak", "release"]).
BPM trajectory: When bpm_range is set (e.g., [126, 134]), the builder plans a BPM arc across the set and outputs per-track play_at_bpm, pitch_adjustment_pct, and effective_key values.
Returns candidate sequences with per-transition scores, overall set score, and estimated total duration.
Evaluation thresholds (test harness only, not enforced at runtime)
Section titled “Evaluation thresholds (test harness only, not enforced at runtime)”These thresholds are used by the internal test suite (eval_scoring.rs) to catch scoring regressions. They are not enforced by build_set at runtime.
| Metric | Threshold | Description |
|---|---|---|
| Mean composite | ≥ 0.65 | Average transition score |
| Min composite | ≥ 0.30 | Worst individual transition |
| Composite variance | ≤ 0.08 | Consistency across transitions |
| Harmonic coherence | ≥ 50% | Fraction of transitions with key ≥ 0.8 |
| Energy fidelity | ≥ 40% | Fraction of transitions with perfect energy |
| Max pitch adjustment | ≤ 8% | Maximum BPM deviation across set |
Transition weight spec
Section titled “Transition weight spec”The priority parameter on score_transition, query_transition_candidates, and build_set accepts a flexible TransitionWeightSpec with three forms:
Named preset — a built-in or saved preset by name:
"balanced"Built-in presets: "balanced", "harmonic", "energy", "genre".
Preset with per-axis overrides — start from a preset and tweak individual axes (auto-renormalized):
{"preset": "harmonic", "overrides": {"energy": 0.25}}Fully custom weights — specify all axes directly (auto-renormalized to sum to 1.0):
{"key": 0.3, "bpm": 0.2, "energy": 0.2, "genre": 0.15, "brightness": 0.1, "rhythm": 0.05}Transition axes: key, bpm, energy, genre, brightness, rhythm (6 axes). All fields are optional in override and custom forms; missing fields inherit from the base preset (or default to 0 in fully custom mode).
Pool Discovery Tools
Section titled “Pool Discovery Tools”The pool tools use a symmetric scoring kernel — score(A,B) == score(B,A) always. No energy phases, genre streaks, or BPM drift. Seven axes: BPM, energy, key, genre, timbral, brightness, rhythm. Two presets: balanced (default) and timbral.
score_pool_compatibility
Section titled “score_pool_compatibility”Score pool compatibility between tracks. Three modes determined by which parameters are provided:
Pairwise mode — score two tracks:
| Parameter | Type | Required | Description |
|---|---|---|---|
track_a |
string | yes | First track ID |
track_b |
string | yes | Second track ID |
One-vs-pool mode — score a candidate against a pool:
| Parameter | Type | Required | Description |
|---|---|---|---|
track_id |
string | yes | Candidate track ID |
pool_track_ids |
string[] | yes | Pool member track IDs |
Cohesion mode — analyze a pool’s internal compatibility:
| Parameter | Type | Required | Description |
|---|---|---|---|
pool_track_ids |
string[] | yes | Pool track IDs (at least 2) |
Common parameters (all modes):
| Parameter | Type | Default | Description |
|---|---|---|---|
master_tempo |
boolean | false |
Master Tempo mode |
reference_bpm |
number | median | Reference BPM for key evaluation |
preset |
string | object | "balanced" |
Pool weight spec (see below) |
expand_pool
Section titled “expand_pool”Find tracks compatible with an existing pool via iterative greedy expansion. Each addition is guaranteed compatible with the full pool at the time it’s added.
| Parameter | Type | Required | Description |
|---|---|---|---|
seed_track_ids |
string[] | yes | Seed tracks defining the initial pool |
additions |
integer | Tracks to add (default: 3) |
|
master_tempo |
boolean | Master Tempo mode (default: false) |
|
reference_bpm |
number | Reference BPM (default: median of seeds) | |
cross_genre |
boolean | Disable genre family pre-filter (default: false) |
|
preset |
string | object | Pool weight spec (see below) | |
playlist_id |
string | Restrict candidates to a playlist | |
max_tracks |
integer | Cap on candidate universe size |
Also accepts all search filter parameters for scoping the candidate universe.
Returns additions with min_score (worst compatibility to any member), mean_score, and rationale (strongest/weakest axes, most compatible member). Stops early if no candidate meets the 0.4 quality threshold.
describe_pool
Section titled “describe_pool”Analyze a pool’s cohesion, coverage, and structure.
| Parameter | Type | Required | Description |
|---|---|---|---|
pool_track_ids |
string[] | Track IDs in the pool | |
playlist_id |
string | Playlist ID to use as the pool | |
master_tempo |
boolean | Master Tempo mode (default: false) |
|
reference_bpm |
number | Reference BPM (default: median) | |
preset |
string | object | Pool weight spec (see below) |
Provide either pool_track_ids or playlist_id.
Returns: cohesion (mean/min pairwise), medoid track, weak members, energy band, BPM center/spread, key neighborhood, dominant genre, analysis coverage. When master_tempo=false, also reports optimal_reference_bpm and key stability comparison.
discover_pools
Section titled “discover_pools”Discover natural track pools in a library subset using Bron-Kerbosch clique enumeration on a thresholded compatibility graph. Returns overlapping pools with core/edge members and bridge tracks.
| Parameter | Type | Required | Description |
|---|---|---|---|
track_ids |
string[] | Specific track IDs to analyze (highest priority selector) | |
playlist_id |
string | Analyze tracks in this playlist | |
max_tracks |
integer | Max tracks to analyze (default: 200) |
|
threshold |
number | Compatibility threshold for graph edges, 0.0–1.0 (default: 0.7). Higher = tighter pools, fewer results |
|
min_pool_size |
integer | Minimum pool size (default: 3, min: 2) |
|
max_pool_size |
integer | Maximum pool size (default: 12) |
|
max_pools |
integer | Max pools to return (default: 10) |
|
master_tempo |
boolean | Master Tempo mode (default: false) |
|
reference_bpm |
number | Reference BPM for key evaluation (default: median) | |
preset |
string | object | Pool weight spec (see below) |
Also accepts all search filter parameters for scoping the input tracks.
Pool weight spec
Section titled “Pool weight spec”The preset parameter on score_pool_compatibility, expand_pool, describe_pool, and discover_pools accepts a flexible PoolWeightSpec with three forms:
Named preset — a built-in or saved preset by name:
"balanced"Built-in presets: "balanced", "timbral".
Preset with per-axis overrides — start from a preset and tweak individual axes (auto-renormalized):
{"preset": "timbral", "overrides": {"timbral": 0.4}}Fully custom weights — specify all axes directly (auto-renormalized to sum to 1.0):
{"bpm": 0.2, "energy": 0.2, "timbral": 0.15, "key": 0.15, "genre": 0.15, "brightness": 0.1, "rhythm": 0.05}Pool axes: bpm, energy, timbral, key, genre, brightness, rhythm (7 axes). All fields are optional in override and custom forms; missing fields inherit from the base preset (or default to 0 in fully custom mode).
Weight Presets
Section titled “Weight Presets”Save, list, and delete custom weight presets that persist across sessions. Built-in presets (balanced, harmonic, energy, genre for transition; balanced, timbral for pool) cannot be overwritten or deleted.
save_weight_preset
Section titled “save_weight_preset”Save a custom weight preset for reuse. Weights are auto-renormalized to sum to 1.0.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
name |
string | yes | Name for the preset (e.g., "deep_techno_pool") |
|
scorer_type |
string | yes | ["pool", "transition"] |
Scorer type |
weights |
object | yes | Weight values. For pool: {bpm, energy, timbral, key, genre, brightness, rhythm}. For transition: {key, bpm, energy, genre, brightness, rhythm} |
list_weight_presets
Section titled “list_weight_presets”List available weight presets (both built-in and custom saved), showing weights for each.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
scorer_type |
string | ["pool", "transition"] |
Filter by scorer type; omit for all |
delete_weight_preset
Section titled “delete_weight_preset”Delete a custom saved weight preset. Cannot delete built-in presets.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
name |
string | yes | Name of the preset to delete | |
scorer_type |
string | yes | ["pool", "transition"] |
Scorer type |