Composition Engine — Structure, Transitions, and Form

The composition engine operates three sub-engines: compositional analysis (structure and motifs), transition planning (section-to-section flow), and translation checking (how the mix survives different playback systems). It also provides form-level tools for emotional arc and arrangement planning.

Atlas-first reflex (v1.23.x+, MANDATORY before any creative move)

Before producing ANY creative response, query the user's atlas overlays. The corpus contains 337 entries across 3 namespaces, plus 3,917 parameter-level JSON sidecars — far richer than anything inferable from training data alone.

Query order:

1. `extension_atlas_search(namespace="packs", query=<intent>)` — pack identity, signature workflows, hidden gems, anti-patterns, notable presets with macro deep-data, demo projects
2. `extension_atlas_search(namespace="packs", query=<intent>, entity_type="cross_pack_workflow")` — multi-pack signature recipes (15 entries: dub-techno spectral drone bed, BoC decayed pad, Mica Levi orchestral dread, etc.)
3. `extension_atlas_search(namespace="m4l-devices", query=<sonic descriptor>)` — M4L instrument/effect/midi-effect device catalog (155 entries)
4. `atlas_search(...)` — bundled atlas (Core Library, fallback)

Multi-grain traversal:

When an aesthetic-level query lands a pack-level result, AUTO-DRILL: pack → its notable_presets → those preset macro states → load via load_browser_item. Don't stop at "I found a relevant pack" — drill to the actual preset/parameter level the user can immediately use.

# Example — agent received "evolving polyrhythmic ambient at 120 BPM, build the section arc"
hit = extension_atlas_search(namespace="packs", query="evolving polyrhythmic ambient generative")
# → midi_tools_by_philip_meyer + drone_lab + cross-pack workflows for generative form

workflow = extension_atlas_get("packs", "dub_techno_spectral_drone_bed")
# → reveals signal_flow: HDG → PitchLoop89 cross-feedback → Convolution Reverb

drone_lab = extension_atlas_get("packs", "drone_lab")
# → notable_presets reveals Razor Wire Drone with macros Filter Control=108, Movement=53...

# Now plan the section/transition with concrete preset names + macro values, not vague descriptions

When the user mentions a producer or pack by name:

• "BoC sublime pad" → atlas hit: boc_decayed_pad cross-pack-workflow + inspired_by_nature pack
• "Henke spectral chain" → atlas hit: pitchloop89 + granulator_iii + 2 Henke cross-pack workflows
• "Mica Levi orchestral dread" → atlas hit: mica_levi_orchestral_dread workflow + the orchestral suite packs
• "Drone Lab" → atlas hit: drone_lab pack + 4 Drone Lab demo_project entries

The atlas knows the user's installed library at parameter depth. Producer-anchor queries land specific moves, not vague descriptions.

Anti-pattern surfacing:

Every pack entry has an anti_patterns body field listing "don't reach for this when X." Surface the relevant anti-pattern when proposing a move so the user knows the move's domain. (E.g. "Drone Lab is sustain-only — don't use for percussive content.")

For deliberately rule-breaking creative requests ("eclectic", "ignore the limits", "weird combo", "mix incompatible aesthetics"): enter Eclectic Mode inside this composition loop. Anti-patterns become prompt tension rather than guardrails: keep hard safety and protected-user constraints, then pair one normally-avoided formal idea with one identity-preserving anchor. Do not route to a private or missing skill.

Composition Sub-Engine

Analyze and transform the structural elements of a track.

Analysis Flow

1. Call analyze_composition — runs a full structural pass returning sections, motifs, phrase grid, and form classification
2. Call get_section_graph — returns the section map: intro, verse, chorus, bridge, drop, breakdown, outro with bar ranges
3. Call get_phrase_grid — returns the rhythmic and melodic phrase boundaries within each section
4. Call get_motif_graph — returns detected melodic and rhythmic motifs with their occurrence locations and transformation history

Transformation

Once you understand the structure:

• transform_motif(motif_id, transformation) — apply a transformation to a detected motif. Transformations include: inversion, retrograde, augmentation, diminution, transposition, fragmentation, sequence
• transform_section(section_id, transformation) — apply a structural transformation to an entire section. Transformations include: extend, compress, strip_down, build_up, reharmonize, rhythmic_variation

Always capture before state with get_notes or get_arrangement_notes before transforming. Evaluate the result with evaluate_composition_move.

Motif Work

The motif graph tracks recurring melodic and rhythmic patterns:

• Each motif has an id, pitches, rhythms, first_occurrence, and occurrences list
• Related motifs are linked by transformation edges (e.g., motif_2 is an inversion of motif_1)
• Use the motif graph to ensure thematic coherence — transformations should derive from existing material

Transition Sub-Engine

Plan and execute smooth transitions between sections.

Transition Flow

1. analyze_transition(from_section, to_section) — examine the current transition between two sections. Returns energy delta, timbral shift, harmonic distance, and detected issues
2. plan_transition(from_section, to_section) — generate a transition plan based on detected issues. Returns an ordered list of moves (filter sweeps, risers, drum drops, fills, automation curves)
3. score_transition(from_section, to_section) — rate the current transition quality (0.0-1.0) with breakdown by energy, harmony, rhythm, and timbral continuity
4. Execute the planned moves using appropriate tools (set_clip_automation, add_notes, set_device_parameter, apply_automation_shape)
5. evaluate_composition_move — judge whether the transition improved

See references/transition-archetypes.md for common transition patterns and when to use each.

Transition Principles

• Energy changes should be gradual unless a hard cut is intentional
• Harmonic transitions need a pivot chord or shared tone
• Rhythmic transitions benefit from a fill or break at the boundary
• Timbral shifts should start 1-2 bars before the section change
• The most effective transitions prepare the listener's ear before the change lands

Translation Sub-Engine

Check how the mix translates across playback systems.

Translation Flow

1. check_translation — run translation analysis on the current mix
2. get_translation_issues — return specific problems:

• mono_collapse: elements that disappear or phase-cancel in mono playback
• spectral_consistency: frequency balance shifts between monitoring contexts
• low_end_translation: bass content that may vanish on small speakers
• loudness_consistency: perceived loudness variation across systems

Translation issues feed back into the mix engine — a mono collapse issue becomes a stereo_width critic issue for the mix loop.

Form Sub-Engine

High-level arrangement and emotional arc tools.

Form Flow

1. get_emotional_arc — map the energy/intensity curve across the entire track, identifying peaks, valleys, and plateaus
2. plan_arrangement — generate an arrangement plan based on the current form, suggesting section order, lengths, and energy targets
3. apply_gesture_template — apply a predefined arrangement gesture (build, drop, breakdown, outro_fade, intro_build) to a bar range

See references/form-patterns.md for common song forms and energy curves by genre.

Arrangement Principles

• Every section should have a clear purpose: introduce, develop, contrast, resolve, release
• The energy arc should have at least one clear peak — flat energy across the entire track lacks emotional impact
• Contrast drives interest: loud/quiet, dense/sparse, bright/dark
• Repetition builds familiarity but needs variation to avoid fatigue — transform on repeat, do not copy verbatim
• Transitions are as important as sections — budget time for them in the arrangement

Combining Sub-Engines

A typical compositional improvement session:

1. analyze_composition to understand current structure
2. get_emotional_arc to see the energy shape
3. Identify the weakest section or transition
4. Use the transition sub-engine to fix section boundaries
5. Use motif transformations to add thematic development
6. check_translation to verify the changes survive mono/small speakers
7. evaluate_composition_move after each change

Always work one change at a time. Verify and evaluate before moving to the next intervention.