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.

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.