Pool Building

Builds unordered pools of tracks that mix well together in any direction. Unlike Set Building (which produces a fixed sequence), pools are crates for live improvisation — any permutation works.

Paste into your agent:

Build a track pool from my collection.

Pool building is read-only — it discovers compatible groupings and exports them as playlists, never changing your metadata.

Prerequisites

Essentia analysis is strongly recommended — without it you lose the timbral axis (the main discovery axis) and brightness/rhythm scoring
Enrichment caches should be populated — ask the agent to check cache coverage if unsure
Genre classification improves results but isn’t required

How it differs from set building

Pool scoring is symmetric — score(A,B) always equals score(B,A). There are no energy phases, no genre streaks, no BPM drift penalties. The question is “do these tracks belong in the same crate?” not “should B follow A?”

Presets

balanced (default) — BPM and energy lead, with timbral similarity as the discovery axis
timbral — upweights timbral similarity for cross-genre sonic discovery

Master tempo

Pool tools default to master_tempo=false, which accounts for the pitch shift that happens when you adjust BPM without master tempo on. If you play with Rekordbox’s master tempo enabled, set master_tempo=true.

See Pool Discovery for the full scoring model and expansion algorithm.

Constraints

Read-only. Pool building never modifies track metadata. It discovers compatible groupings.
Human controls the result. Agent proposes pools and additions. User approves, removes, or adjusts.
Cache-first. All pool scoring uses cached audio analysis and enrichment. No external API calls.
Master tempo default. Default master_tempo=false — accounts for pitch shift when scoring key compatibility. Override to true only if user confirms they play with master tempo on.
Symmetric scoring. Pool compatibility is symmetric: score(A,B) == score(B,A). No directional context.

Prerequisites

cache_coverage()

All providers must be at 100%. If not, hydrate first (audio analysis, then enrichment). Essentia analysis is especially important — tracks without it lose the timbral axis and brightness/rhythm axes in pool scoring.

Steps

1. Collect seed tracks

Ask user for 2-5 seed tracks that define the pool’s character. Sources:

Specific track IDs the user already has in mind
A playlist the user wants to expand from
Tracks from a recent session (get_sessions, get_session_tracks)
Search results (search_tracks)

Confirm seeds with user before proceeding. Present each seed’s key, BPM, energy, genre.

Alternative: automatic seed discovery. Instead of manual seed selection, discover_pools can find natural track pools using Bron-Kerbosch clique enumeration on a compatibility graph. Filter by genre, BPM, or playlist and adjust threshold (0.3-0.95) to control pool tightness. Discovered pools can be used directly or as seeds for expansion.

2. Expand the pool

expand_pool(
  seed_track_ids=[...],
  additions=5,
  master_tempo=false
)

Adjust parameters based on user goals:

cross_genre=true for timbral discovery across genre boundaries
preset="timbral" to prioritize sonic similarity over metadata matching. The preset parameter accepts a named preset string (e.g., "balanced"), a preset with overrides (e.g., {preset: "timbral", overrides: {timbral: 0.4}}), or fully custom weights with axes: bpm, energy, timbral, key, genre, brightness, rhythm. Custom presets can be saved with save_weight_preset and listed with list_weight_presets for reuse across sessions.
playlist_id to restrict candidates to a specific playlist
Search filters (genre, bpm_min, bpm_max, rating_min) to scope candidates

Present each addition with:

Track info (title, artist, BPM, key, genre)
min_score — worst compatibility with any pool member (the guarantee)
mean_score — average compatibility across the pool
rationale — strongest/weakest axes, most compatible member

If stopped_early=true, explain that either the remaining candidates scored below the quality threshold (0.4) or the candidate pool was exhausted. Suggest widening filters, relaxing cross_genre, or adjusting seeds.

Ask user: “Keep all additions? / remove specific ones / expand further / adjust seeds”

3. Iterate

If user removes tracks or wants more:

expand_pool(
  seed_track_ids=[...all current pool members...],
  additions=3,
  master_tempo=false
)

Use the full current pool as seeds for the next expansion round. This ensures new additions are compatible with everything already approved.

Repeat until user is satisfied with pool size and composition.

4. Describe the pool

describe_pool(
  pool_track_ids=[...],
  master_tempo=false
)

Present the analysis:

Cohesion — mean/min pairwise compatibility scores
Energy band — energy range across the pool
BPM center/spread — tempo characteristics
Key neighborhood — effective keys at reference BPM
Dominant genre — most common genre
Analysis coverage — % of tracks with full Essentia data
Weak members — tracks with low min-compatibility (candidates for removal)
Optimal reference BPM (master_tempo=false only) — the BPM that maximizes key compatibility across the pool

If weak members are flagged, ask user: “Remove weak members? / keep them / see pairwise scores”

If bpm_range_warning appears, explain that the pool spans too wide a BPM range for reliable harmonic evaluation at a single reference BPM.

5. Validate specific pairs (optional)

For tracks the user is uncertain about:

score_pool_compatibility(
  track_a="...",
  track_b="...",
  master_tempo=false
)

Show per-axis scores to help the user understand why tracks do or don’t fit.

6. Lock the pool

Once the user approves the pool, save it as a playlist:

write_xml(playlists=[{"name": "Pool: Deep House 126", "track_ids": [...]}])

Note: write_xml also exports and clears any staged metadata changes. Use preview_changes first if other workflows have pending edits.

Report output path. Remind user: File → Import Collection in Rekordbox.

The pool is now a locked chapter — ready for live performance or further set planning.