Skip to content
reklawdboxreklawdbox

Agent SOP: Chapter Set Planning

Plan a full set from locked chapters with bridge tracks between them.

Agent prompt

Section titled “Agent prompt”

Paste into your agent to start:

Plan a set from my locked chapters.

Constraints

  • Analysis is read-only; export writes XML. Chapter and bridge analysis never modifies track metadata. write_xml creates the approved playlist export without writing the Rekordbox database.
  • Human controls the result. Agent proposes chapter order and bridges. User approves all decisions.
  • Local scoring data. Scoring reads Rekordbox metadata plus cached Stratum and Essentia analysis. It makes no external API calls.
  • Chapters first. This workflow assumes the user has already built and locked chapters (pools saved as playlists) using the Pool Building workflow.

Prerequisites

  • At least 2 locked chapters (playlists) from the Pool Building workflow. Alternatively, discover_pools can find chapter candidates automatically from a library subset using Bron-Kerbosch clique enumeration.
  • User must identify each chapter as sequenced (fixed order) or unordered (improvise order live)
  • Valid bridge candidates and valid pool/set tool parameters.
  • 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. Essentia is recommended for energy, brightness, rhythm, and timbral evidence, but missing optional axes degrade gracefully.

Steps

1. Gather chapters

Ask user for:

  • Chapter playlist IDs (from get_playlists)
  • Whether each chapter is sequenced or unordered
  • Target set duration and overall energy arc preference

2. Analyze each chapter

For each chapter:

describe_pool(
  playlist_id="...",
  master_tempo=false
)

Summarize per chapter:

  • Energy band, BPM center, dominant genre, key neighborhood
  • Cohesion score
  • For unordered chapters: optimal reference BPM

Present a table of all chapters side by side.

3. Propose chapter order

Based on the user’s energy arc preference, propose an ordering that creates a coherent energy progression across the night:

  • Warmup — lowest energy chapters first
  • Build — ascending energy
  • Peak — highest energy chapters
  • Release — descending energy to close

Consider BPM progression — avoid large BPM jumps between adjacent chapters.

Present the proposed order with energy flow visualization. Ask user: “Approve order? / reorder / swap chapters”

4. Find bridge tracks

For each chapter boundary (transition between chapters), find 1-3 bridge tracks that connect them:

Step 4a: Identify boundary tracks

  • For sequenced chapters: the last 2-3 tracks of the outgoing chapter and first 2-3 of the incoming chapter
  • For unordered chapters: all members are potential boundary tracks

Step 4b: Search for bridges

Use expand_pool with seeds from both chapters’ boundary tracks:

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

Tracks compatible with both sets of boundary tracks are natural bridges.

Step 4c: Score bridge candidates

For each candidate, score against both chapters:

score_pool_compatibility(
  track_id="candidate",
  pool_track_ids=[...outgoing_boundary],
  master_tempo=false
)
score_pool_compatibility(
  track_id="candidate",
  pool_track_ids=[...incoming_boundary],
  master_tempo=false
)

Rank by the minimum of the two min-scores (must work with both sides).

Step 4d: Present bridge options

Present 3-5 bridge candidates per boundary with:

  • Compatibility scores to both chapters
  • BPM/energy position relative to the two chapters
  • Why each works (strongest axes)

Ask user: “Pick bridge(s) / skip this boundary / search with different parameters”

5. Sequence unordered chapters

For unordered chapters, propose internal sequence:

build_set(
  track_ids=[...chapter_track_ids],
  target_tracks=N,
  priority="balanced",
  energy_curve="flat",
  master_tempo=false,
  beam_width=3
)

Or use score_transition for pairwise evaluation if the chapter is small (≤5 tracks).

Present ordering options. Ask user: “Pick sequence / keep unordered / adjust”

Weight presets. Use save_weight_preset to save custom transition or pool weights for reuse. list_weight_presets shows all available presets (built-in and custom). delete_weight_preset removes custom presets.

6. Present full set plan

Display the complete set plan:

  • Chapter order with bridge tracks between them
  • Per-chapter: track list, energy band, BPM range
  • Overall energy arc visualization
  • Total track count and estimated duration
  • Any gaps or weak transitions flagged

Ask user: “Approve plan? / swap chapters / change bridges / adjust sequences”

7. Export

Export the full set as a single ordered playlist:

write_xml(playlists=[{
  "name": "Set Plan: Venue Date",
  "track_ids": [...chapter1, ...bridge1, ...chapter2, ...bridge2, ...]
}])

Optionally export each chapter as a separate playlist too.

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.