Skip to content
reklawdboxreklawdbox

Agent SOP: Pool Building

Build unordered pools of mutually compatible tracks for live improvisation.

Agent prompt

Section titled “Agent prompt”

Paste into your agent to start:

Build a track pool from my collection.

Constraints

  • Analysis is read-only; export writes XML. Compatibility analysis never modifies track metadata. write_xml creates the approved playlist export without writing the Rekordbox database.
  • Human controls the result. Agent proposes pools and additions. User approves, removes, or adjusts.
  • Local scoring data. Pool scoring reads Rekordbox metadata plus cached Stratum and Essentia analysis. It makes 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

  • Valid seed or candidate tracks and valid pool-tool parameters are the only hard readiness requirements.
  • Missing BPM, key, or genre degrades the corresponding scoring axis; it does not block the workflow.
  • Built-in Stratum supplies BPM and key evidence when available, with Rekordbox metadata as the complementary source.
  • Essentia is recommended for energy, brightness, rhythm, and timbral axes. Missing optional axes degrade gracefully instead of blocking the pool.

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 the output path, then stop for the user to complete and confirm the playlist handoff:

Use the playlist path in Rekordbox for the exported playlist name and order:

  1. Keep the XML file available — Note the path reported by write_xml. Do not move or delete the file until the imported playlist is verified.
  2. Open the XML browser — If rekordbox xml is hidden, enable it under Preferences → View → Layout → Media Browser. Under Preferences → Advanced → Database → rekordbox xml, set Imported Library to the exported XML file.
  3. Preview the generated playlist — Expand rekordbox xml → Playlists, select only the generated playlist, and check its name and track order before importing it.
  4. Import the playlist — Drag that playlist to the desired location under Rekordbox Playlists. If the current UI offers Playlist → Import Playlist for the selected rekordbox xml playlist, that action can be used instead.
  5. Verify before cleanup — In the imported playlist, confirm the track count, the first and last tracks, and representative transitions through the order. Keep the XML file until these checks pass.

This is not the metadata-import path. rekordbox xml → All Tracks → Import To Collection applies staged track metadata; importing the playlist does not. Complete that separate flow when the XML also contains staged metadata changes.

The XML export is the agent’s stopping point. Report the path, then wait for the user to complete and confirm these Rekordbox steps. Do not say the playlist is installed before that confirmation.

Only after the user confirms the imported playlist and order should the pool be treated as a locked chapter for live performance or further set planning.