music-composition

name	music-composition
description	Use when composing music with the music-server MCP tools. Covers note syntax, tool workflow, and composition patterns.

Music Composition with music-server

You have 47 MCP tools for building compositions from scratch. This skill covers the syntax, tool flow, and patterns.

First Step: Preload All Tool Schemas

Before doing anything else, load all music-server schemas in one batch ToolSearch call:

ToolSearch: "mcp music-server"  (max_results=50)

Do this once at the start of the session. MCP tool schemas are deferred — calling any tool without loading its schema first causes an error and forces a mid-composition round-trip.

Note Sequence Syntax

Notes are whitespace-separated tokens: pitch/duration

Pitch: standard name + optional accidental + octave: C4, F#3, Bb5, Eb4

Rests: r/q, r/h, r/e etc.

Chords: angle brackets around space-separated pitches, followed by /duration:

<C4 E4 G4>/q       → C major triad, quarter note
<Eb3 G3 Bb3>/h     → Eb major triad, half note
<D3 F3 A3 C4>/q    → Dm7 chord, quarter note

Use chords for pad stabs, gospel organ, jazz voicings — any simultaneous pitches.

Duration codes:

Code	Value
w	whole
h	half
q	quarter
e	eighth
s	sixteenth
dh	dotted half
dq	dotted quarter
de	dotted eighth
h3	half-note triplet (= 1/3 whole)
q3	quarter-note triplet (= 1/6 whole)
e3	eighth-note triplet (= 1/12 whole)
s3	sixteenth-note triplet (= 1/24 whole)

Ties — append ~tie to hold a note into the next note of the same pitch (extends sound across bar lines):

C4/h~tie C4/q     → C4 sounds for a dotted half total
G4/q~tie G4/e     → G4 quarter + eighth tied together

Ties are rendered as ~ in LilyPond and extend NOTE_OFF in MIDI. Use for notes that cross bar lines or need durations not expressible as a single rhythmic value.

Per-note velocity — append ~vel:N (0–127) to override the voice-level dynamic for a single note:

C4/q~vel:100 D4/q E4/q~vel:40   # loud C, default D, quiet E
G4/h~vel:120~tie G4/q            # very loud tied note

Useful for shaping phrases: push peak notes, pull back resolutions, accent approach tones. Takes precedence over voice.set_dynamics.

Articulations — append ~code after the duration:

Suffix	Articulation	LilyPond mark	MIDI effect
~stac	staccato	-.	50% duration
~acc	accent	->	normal duration
~ten	tenuto	--	full duration
~marc	marcato	-^	75% duration
~leg	legato	(none)	full duration

C4/q~stac D4/q E4/h     # staccato C, normal D and E
<C4 E4 G4>/q~acc         # accented chord stab

Use voice.set_articulation to apply an articulation to an entire voice at once.

Ornaments — append ~code after the duration (combinable with articulations and ~vel:N):

Suffix	Ornament	LilyPond glyph	MIDI approximation
~roll	roll (Irish/folk)	\trill	main–upper–main–lower–main
~trill	trill	\trill	rapid main–upper alternation
~mord	mordent (lower)	\mordent	main–lower–main
~prall	pralltriller	\prall	main–upper–main

A4/e~roll      # rolled A eighth — classic Irish jig ornament
B4/q~trill     # trilled B quarter
G4/e~mord      # mordent on G eighth

MIDI uses semitone neighbors as pitch approximation (upper = +2, lower = −1). For accurate neighbor pitches, use explicit grace notes instead.

Grace notes — prefix {pitch ...} before the main note token. Pitches are space-separated; use standard pitch notation:

{G4}A4/q        # single grace note G before A quarter
{G4 A4}B4/e     # two grace notes before B eighth

Grace notes steal time from the front of the main note's sounding duration (~32nd note each). They appear as \grace { ... } in LilyPond.

Control Change (CC) events — point-in-time MIDI controller values placed inline in a voice sequence. Zero duration; do not advance time. MIDI only — invisible to LilyPond/MusicXML.

cc:pan:64          → center pan (CC 10, value 64)
cc:pan:20          → hard left
cc:pan:110         → hard right
cc:expr:100        → high expression (CC 11)
cc:expr:40         → low expression — fade down a phrase
cc:reverb:60       → medium reverb send (CC 91)
cc:mod:80          → modulation / vibrato depth (CC 1)
cc:sustain:127     → sustain pedal down (CC 64)
cc:sustain:0       → sustain pedal up
cc:11:80           → numeric form — same as cc:expr:80

Named aliases: mod (1), vol (7), pan (10), expr (11), sustain (64), reverb (91), chorus (93).

Expression CC (11) is how you shape dynamics on strings and brass — velocity sets the attack, expr shapes the phrase arc. Pan places instruments in the stereo field. Place CC events immediately before the note they should affect:

voice.create "strings" "cc:pan:30 cc:expr:60 C4/h cc:expr:90 E4/h cc:expr:70 G4/w"

Program Change events — mid-score instrument change within a voice. Zero duration. Use for switching patches (e.g. arco to pizzicato).

pc:45    → switch to Pizzicato Strings (0-indexed GM program; GM tables list this as #46)
pc:40    → switch back to Violin (0-indexed GM program; GM tables list this as #41)

voice.create "strings" "C4/h D4/h pc:45 E4/q F4/q G4/h"

Examples:

C4/q D4/q E4/q F4/q              # four quarter notes
E4/e F#4/e G4/q r/q              # eighths, quarter, rest
C4/dq D4/e E4/h                  # dotted quarter + eighth + half
<Eb3 G3 Bb3>/q <Ab3 C4 Eb4>/q   # two chord stabs
C4/q~stac D4/q~stac r/e E4/e F4/q  # staccato melody

Tools by Category

Composition state

• score.set_metadata — set title, tempo (BPM), time signature ("4/4", "3/4")
• score.set_swing — enable swing quantization: ratio="2/3" (standard jazz), "3/5" (light), "0" to disable
• score.set_tempo_change — gradual ritardando or accelerando across a bar span: start_bar, end_bar, to_bpm, optional curve="linear" (default) or "exponential" (more natural for rit.). Affects both MIDI playback and LilyPond notation.
• score.describe — inspect full composition state (voices, dynamics, articulations, instruments)
• score.assign_instrument — assign a voice to a GM instrument (see list below)
• score.clear — wipe everything and start fresh

Voices

• voice.create — create a named voice from a note sequence
• voice.append — append more notes to an existing voice
• voice.list — list all voices with bar counts, event counts, and duration
• voice.measure_count — return the number of complete bars in a single voice
• voice.set_dynamics — set volume for a voice: ppp pp p mp mf f ff fff (default: mf)
• voice.set_articulation — set articulation for a voice: staccato accent tenuto marcato legato. Optional from_bar / to_bar to scope to a bar range (e.g. make only the final phrase tenuto).
• voice.add_expression_curve — add a gradual CC 11 expression curve to a voice. Parameters: voice, start_bar, end_bar, from_value (0–127), to_value (0–127), curve (linear or exponential). Emits one CC 11 event per bar between start_bar and end_bar, interpolated from from_value to to_value. Use for crescendos, decrescendos, and phrase swells. Multiple curves on the same voice are additive. Example: voice.add_expression_curve voice=melody start_bar=9 end_bar=16 from_value=30 to_value=110 curve=exponential.
• voice.from_motif — Advanced: create a voice from a saved motif, optionally transformed
• voice.delete — remove a voice from the composition

Voice editing (write-back — modifies the voice in place)

• voice.trim — truncate a voice to N bars, discarding everything after
• voice.set_bar — replace one bar's content: bar=N notes="C4/q D4/q E4/q F4/q". Use query.voice to inspect before editing.
• voice.replace_range — replace bars from_bar–to_bar (inclusive) with a new note sequence. The replacement doesn't have to fill the same number of bars.
• voice.replace_note — surgical fix: find the first note in bar N whose pitch matches old, replace it with new. Both old and new are full note tokens including duration, e.g. old="C4/q" new="D4/q". Use query.voice to inspect bar content first.

Query

• query.voice — show the note sequence of a voice
• query.motif — show the note sequence of a motif

Transforms (all create a new voice, leaving the original intact)

• transform.transpose — transpose by interval (e.g. "P5", "m3", "M2", "P8"), direction "up"/"down"
• transform.invert — Advanced: mirror pitches around an axis pitch (e.g. "C4")
• transform.retrograde — Advanced: reverse temporal order
• transform.augment — Advanced: scale all durations by a factor ("2/1"=double, "1/2"=halve)

Motifs

• motif.save — save a slice of a voice as a named motif (start/end are 0-based note indices)

Voice operations (all produce a new voice)

• voice.concat — concatenate multiple voices sequentially (voice_names: comma list, target_voice)
• voice.repeat — repeat a voice N times — great for ostinatos and drum loops
• voice.slice — Advanced: extract measures startMeasure–endMeasure (exclusive) from a voice
• voice.pad_to_measure — Advanced: prepend rests so the voice starts at the given measure number

Harmony

• harmony.set_key — set the composition key, e.g. "F major", "D minor", "Bb major"
• harmony.chord_progression — set a Roman-numeral progression, e.g. "I IV V I", "ii V I", "I V vi IV"
• harmony.set_bars — declare per-bar chord changes as concrete chord symbols: "1:Cm7 2:F7 3:Bbmaj7 4:Eb"
• harmony.harmonize — generate a chord-root voice from the current key + progression (target_voice, optional octave)
• harmony.walking_bass — generate a walking bass line over chords; adapts to time signature: 4/4 = root-fifth-third-approach, 3/4 = root-fifth-fifth, 6/8 = root-fifth (dotted-quarters), 2/4 = root-approach. Uses harmony.set_bars if set, else falls back to progression. Optional: velocity (ppp–fff, default mf), approach (chromatic [default, 1–2 semitones below], diatonic [scale step below], none [use chord root])
• harmony.comp — generate a comping (chord accompaniment) voice; adapts to time signature. Style options: quarter_stabs (default), on_beat, eighth_pump, shell_voicings, charleston (4/4 only). Optional: velocity (ppp–fff, default mf)
• harmony.suggest_harmony — suggest chord harmonizations measure-by-measure for a given voice (advisory)
• harmony.detect_key — Advanced: run pitch-class analysis on a voice and report the most likely key
• harmony.diatonic_transpose — transpose a voice by N diatonic scale steps within the current key

Drums

• drums.preset — load a named drum pattern for N bars; creates drums_kick, drums_snare, etc. voices on channel 9
  • house_4on4 — four-on-the-floor kick every beat + clap on 2 & 4 + closed 8th hi-hats; the EDM/dance foundation. Use at 120–130 BPM.
  • rock_8th — driving 8th hi-hat, snare on 2 & 4, kick on 1 & 3; heavier and faster than rock_basic. Use at 130–180 BPM.
  • rock_basic — standard rock backbeat: quarter hi-hat, snare on 2 & 4, kick on 1 & 3; backbone of rock and pop-rock. Use at 100–160 BPM.
  • swing — jazz ride cymbal pattern, hi-hat on 2 & 4, snare on 2 & 4; pair with score.set_swing "2/3" for authentic jazz feel. Use at 120–220 BPM.
  • waltz — simple 3/4: kick on beat 1, snare on beats 2 & 3; works for classical, folk, or pop waltzes. Use at 100–160 BPM.
  • waltz_jazz (3/4) — kick + hi-hat on beat 1, soft brushed snare (MP) on beats 2 & 3; more idiomatic than waltz for jazz waltz contexts. Pair with score.set_swing "2/3".
  • bossa_nova — defining rhythm is the tresillo clave (3+3+2 eighths, i.e., dq+dq+q); creates drums_kick, drums_rim, drums_hihat (eighth hi-hat), drums_clave. Do NOT add swing — the clave replaces swing feel.
  • afrohouse — syncopated (not 4-on-the-floor) kick + open hi-hat on upbeats + hand percussion; creates drums_kick (beat 1, and-of-2, beat 3), drums_clap (2&4), drums_hihat (8ths + open on upbeats), drums_congas (hi/low alternating), drums_maracas (running eighths, velocity P). After loading: set drums_maracas to p or pp and drums_congas to mp.

Rules / validation

• rules.check — run voice-leading and meter rules; percussion voices (channel 9) are automatically skipped
• rules.check_range — check all notes in a voice against a named instrument's written range

Instruments

• instrument.info — get written range, comfortable range, MIDI program, clef, and articulations for a named instrument

Form

• form.create_section — capture the current voices (or a subset) as a named section. measures is optional — inferred from the longest voice if omitted; a warning is added if explicit measures differs from the inferred count.
• form.repeat_section — append a repeat of a previously defined section (optionally with a new label)
• form.set_ending — attach a 1st/2nd volta ending to a section: section (the repeated section), pass (1 or 2), ending_section (a separately created section with the alternate tail bars). LilyPond renders \repeat volta + \alternative blocks; MIDI plays the correct ending per pass.
• form.build — assemble sections into a full score; replaces per-section voices with the full assembled versions
• form.describe — show the current formal plan (e.g. "A(8) → B(8) → A(8), total: 24 measures")

Export

• export.all — preferred — creates a folder with .mid, .ly, .json, and PDF (if LilyPond installed). The server auto-prepends a sequential number to the folder name (e.g. folder="sunlit_yard" → 25_sunlit_yard). Do NOT include a number yourself — it will double-prefix (e.g. 25_25_sunlit_yard).
• export.midi — write a .mid file to the current directory
• export.lilypond — write a .ly file (and engrave PDF if LilyPond is installed)
• export.musicxml — write a MusicXML 4.0 file (.musicxml). Opens in MuseScore, Dorico, Sibelius, Finale, and most DAWs.

Session persistence

• score.save — save the full composition state to a JSON snapshot under generated_tracks/ (voices, motifs, metadata, key, swing, bar chords, tempo changes). Use to checkpoint work in progress.
• score.load — restore a previously saved snapshot, replacing all current state.
• score.load_midi — import a MIDI file as voices (voice-0, voice-1, …) and set tempo from the file. Existing voices are preserved; call score.clear first for a clean slate. Black keys come back as sharps — re-spell with transform.transpose if needed. path is absolute or relative to the server working directory.
• score.load_abc — parse an ABC notation string into one or more voices. Headers T: (title), L: (default note length), M: (meter), Q: (tempo), K: (key) are all read. Multi-voice files (V: body headers) produce one voice per V: section, named by the voice ID (e.g. V:soprano → voice soprano, V:1 → voice 1). Single-voice files produce one voice named after the T: field (lowercased, spaces → underscores). Key-signature accidentals apply automatically and persist within each measure; explicit accidentals (^, _, =) override for the remainder of the bar. Octave markers ' (raise) and , (lower) are supported. Tied notes (-) are merged into one longer note. Chord events ([CEG]) are imported as simultaneous pitches. Tuplets ((3, (p:q:r) are duration-scaled correctly (e.g. triplet eighth = 1/12 whole). Use to load folk tunes from The Session (thesession.org) or any ABC corpus. Existing voices are preserved; call score.clear first for a clean slate.

Available Instruments

Keyboards: piano, bright_piano, honky_tonk (detuned upright), electric_piano (Rhodes), rhodes, harpsichord, organ, accordion

Tuned percussion: vibraphone, marimba

Guitar / bass: guitar, electric_guitar, electric_bass, synth_bass

Strings: violin, viola, cello, strings, synth_strings

Choir: choir

Brass / winds: trumpet, trombone, tuba, french_horn, brass, saxophone, clarinet, flute, oboe, bassoon

Synth: synth_lead (sawtooth — classic house/trance lead), synth_pad (warm pad — chord stabs)

Drums: drums — automatically assigned to MIDI channel 9 (GM percussion). Notes in the voice are treated as GM drum sound numbers. For the full note-to-sound map, read skills/music-composition/drum-note-map.md. Common notes: C2 kick, D2 snare, F#2 closed hi-hat, Bb2 open hi-hat, Eb2 clap, Eb3 ride.

Typical Workflow

1. score.set_metadata       — title, tempo, time sig
2. harmony.set_key          — optional; required for harmony.* and diatonic_transpose
3. drums.preset             — optional; quick drum pattern for N bars
4. voice.create             — one call per voice, with full note sequence
   voice.append             — add more bars if needed
   voice.set_dynamics           — set volume per voice (f for lead, mp for pads, etc.)
   voice.set_articulation       — set articulation per voice (staccato for stabs, etc.)
   voice.add_expression_curve   — add a CC 11 crescendo/decrescendo curve (from_value→to_value over bar range)
5. transform.transpose      — derive harmony voices (parallel thirds, octave doublings)
   voice.repeat             — extend loops to full length
   voice.concat             — join sections manually if not using form tools
6. harmony.harmonize        — generate an accompaniment voice (needs harmony.set_key first)
7. rules.check              — validate voice leading and meter (percussion skipped automatically)
8. form.create_section      — snapshot current voices as a named section (A, B, etc.)
   form.repeat_section      — plan repeats (ABA, AABA, etc.)
   form.build               — assemble sections; voices replaced with full-length assembled versions
9. score.assign_instrument  — one call per voice (instrument assignments survive form.build, so either order works)
10. score.describe          — sanity check before export
11. export.all              — or export.midi / export.lilypond

Patterns

House track with chord stabs:

harmony.set_key "Eb major"
voice.create "chords" "<Eb3 G3 Bb3>/q r/q <Ab3 C4 Eb4>/q r/q"
voice.set_dynamics "chords" "mp"
voice.set_articulation "chords" "staccato"
score.assign_instrument "chords" "synth_pad"

Walking bass line (manual):

harmony.set_key "F major"
voice.create "bass" "F2/q A2/q C3/q E3/q | D2/q F2/q A2/q C3/q"
voice.set_dynamics "bass" "f"
score.assign_instrument "bass" "electric_bass"

Diatonic harmony in thirds:

harmony.set_key "G major"
transform.transpose "melody" "M3" "up" target_voice="melody_thirds"
# Now melody_thirds is a parallel major-third above melody (chromatic, not diatonic)
# For diatonic thirds use harmony.diatonic_transpose "melody" steps=2

Structural form (ABA):

# Build A section voices, then:
form.create_section "A" measures=8
# Build B section voices (can be completely different), then:
form.create_section "B" measures=8
form.repeat_section "A"
form.build          # assembles A(8) + B(8) + A(8) = 24 measures
# After form.build, all voices are replaced with full 24-bar assembled versions

Volta endings (1st/2nd ending brackets):

# Build main A section (7 bars), then create two 1-bar endings:
form.create_section "A" measures=8       # full 8-bar snapshot
# Build "A_end1" voices (1-bar turnaround back to A):
form.create_section "A_end1" measures=1
# Build "A_end2" voices (1-bar final cadence):
form.create_section "A_end2" measures=1
# Attach endings — pass 1 uses A_end1, pass 2 uses A_end2:
form.set_ending section="A" pass=1 ending_section="A_end1"
form.set_ending section="A" pass=2 ending_section="A_end2"
form.repeat_section "A"
form.build   # LilyPond: \repeat volta 2 + \alternative; MIDI: correct ending per pass

Multi-section form with different voices per section (AABB, AABA, etc.):

# Each section gets its own voices. The pattern: build → snapshot → delete → rebuild → snapshot.
# harmony.set_bars must be reset per section; it is section-local.

# --- A section ---
harmony.set_key "D major"
harmony.set_bars "1:D 2:G 3:D 4:A 5:D 6:G 7:A 8:D"
voice.create "melody" "..."          # 8 bars
harmony.comp target_voice="chords" style="on_beat" octave=3
voice.create "bodhran_bar" "G2/q G2/q G2/q G2/q"
voice.repeat "bodhran_bar" times=8 target_voice="bodhran"
voice.delete "bodhran_bar"
score.assign_instrument "melody" "flute"
score.assign_instrument "chords" "accordion"
score.assign_instrument "bodhran" "drums"

form.create_section "A" measures=8
form.repeat_section "A"              # AABB: queue the second A now

# --- Transition: delete only the voices that change; keep shared ones (e.g. bodhran) ---
voice.delete "melody"
voice.delete "chords"

# --- B section ---
harmony.set_bars "1:G 2:D 3:G 4:A 5:G 6:Em 7:A 8:D"
voice.create "melody" "..."          # 8 bars of new material
harmony.comp target_voice="chords" style="on_beat" octave=3
score.assign_instrument "melody" "flute"
score.assign_instrument "chords" "accordion"
# bodhran is still in scope — captured in B section too

form.create_section "B" measures=8
form.repeat_section "B"              # AABB: queue the second B

form.build   # assembles A(8) + A(8) + B(8) + B(8) = 32 bars
# All voices (melody, chords, bodhran) replaced with full 32-bar assembled versions

Key rules: delete only voices that change between sections; shared voices (drums, bass ostinato) stay in scope and are captured in every section automatically. harmony.set_bars is reset per section — form.build offsets and merges them into the final score.

Ritardando on final bars:

# Assume 24-bar piece at 120 BPM — slow to 60 over the last 3 bars:
score.set_tempo_change start_bar=22 end_bar=24 to_bpm=60 curve="exponential"
# exponential feels more natural than linear for a rit.

Canon at the octave:

voice.create "subject" "C4/q D4/q E4/q G4/q E4/q F4/q G4/q C5/q"
voice.pad_to_measure "subject" start_measure=3 target_voice="answer"
transform.transpose "answer" "P8" "down" target_voice="answer_low"

Motivic development (build a piece from a short cell):

# 1. Define a 4-note cell and save it as a motif
voice.create "cell" "C4/q E4/q G4/q B4/q"
motif.save "cell" startNote=0 endNote=4

# 2. Derive transformed variants — each becomes its own voice
voice.from_motif "cell_inv"   motif="cell" transform="invert"     axis="C4"
voice.from_motif "cell_retro" motif="cell" transform="retrograde"
voice.from_motif "cell_up5"   motif="cell" transform="transpose"  interval="P5"

# 3. Augment for a slower countermelody (double all durations)
transform.augment "cell" factor="2/1" target_voice="cell_slow"

# 4. Build voices by repeating cells — stagger entry for canon/imitation effect
voice.repeat "cell"     times=4 target_voice="subject"
voice.repeat "cell_inv" times=4 target_voice="counter"
voice.pad_to_measure "counter" start_measure=2   # answer enters 1 bar later

# 5. B section uses retrograde or transposed variant as new material
voice.repeat "cell_retro" times=4 target_voice="b_melody"
voice.repeat "cell_up5"   times=4 target_voice="b_counter"

# 6. Assemble into form
form.create_section "A" measures=4
# (swap in B voices here)
form.create_section "B" measures=4
form.repeat_section "A"
form.build   # A(4) + B(4) + A(4) = 12 bars, all derived from the original cell

# Clean up ALL scratch voices before form.create_section or export
# Any voice still in scope will become a staff in the PDF
voice.delete "cell"
voice.delete "cell_inv"
voice.delete "cell_retro"
voice.delete "cell_up5"
voice.delete "cell_slow"

The key idea: one cell generates all the material. The transforms (invert, retrograde, transpose, augment) are the compositional engine — not just decoration.

Genre Scaffolding

For genre-specific scaffolding (Jazz, Bossa Nova, House, Reggae, Blues, Hip-Hop, Afrohouse, Traditional Irish), read skills/music-composition/genre-reference.md.

Tips

• Swing only affects eighth notes in MIDI output. Quarter notes, dotted values, and triplets are unswung. Write swing melodies using straight e eighths — the renderer adds the lilt.
• Walking bass uses harmony.set_bars chords if set, otherwise falls back to harmony.chord_progression. Always set the key before calling walking_bass (needed for approach notes).
• Chord names in LilyPond PDF — if harmony.set_bars has been called, chord symbols are automatically rendered above the staves as a \new ChordNames staff. No extra step needed; just export after setting bar chords.
• Per-section chord maps with form.build — call harmony.set_bars separately for each section before calling form.create_section. form.build automatically merges and offsets each section's chord map to the correct absolute bar numbers in the assembled score. You do not need to manually re-number bars across sections.
• harmony.comp styles: quarter_stabs (beats 2&4 — jazz default), on_beat (all beats — rock/gospel), eighth_pump (8 per bar — funk), shell_voicings (root+7th on 2&4 — sparse jazz), charleston (dotted-quarter+eighth+quarter+rest — classic jazz). Use octave 3 for piano/Rhodes, octave 4 for guitar.
• Ties (~tie) are for notes that span bar lines or durations not expressible as a single value. The tied notes must have the same pitch; MIDI renders them as a single sustained note.
• harmony.set_bars chord symbols use the same quality syntax as ChordSymbol.parse: Cm7, F7, Ebmaj7, Am7b5, Ddim7. Bare root (e.g. Eb) means major.
• target_voice on all transforms is optional — omit to get {name}_transposed etc.
• Rests pass through all transforms unchanged (no pitch to operate on).
• Chords: transform.transpose transposes all pitches in the chord; transform.augment scales the chord's duration. transform.invert does not invert chord pitches — chords pass through unchanged.
• score.assign_instrument "kick" "drums" forces channel 9 automatically.
• harmony.set_key must be called before harmony.harmonize, harmony.diatonic_transpose.
• form.build rest-fills missing voices automatically — if "bass" exists in A but not B, B gets whole-note rests.
• After form.build, voices are replaced in-place — no _form suffix, no stale originals.
• rules.check is advisory — violations are warnings/suggestions, never blockers. Percussion voices are skipped.
• Key signature is reflected in both LilyPond output and the MIDI file (key signature meta event 0x59) — call harmony.set_key before exporting for correct notation and DAW display.
• MIDI metadata emitted automatically — no extra steps needed: track names (voice names appear in DAW track headers), key signature (when harmony.set_key is set), and section markers (when form.build is used — DAW timeline shows "intro", "verse", "chorus" etc. at the correct bar positions).
• CC/PC events are MIDI-only — they are silently skipped in LilyPond and MusicXML export. Don't rely on them for notation; use them purely for MIDI playback quality.
• Expression CC (11) is the most impactful CC for realism on strings, brass, and winds. Place cc:expr:N events at phrase peaks and valleys rather than only at the start of a voice.
• voice.add_expression_curve is bar-absolute — bar numbers are relative to the final assembled score, not the section. In a form.build workflow, add curves after form.build using the assembled bar positions (e.g., if section B starts at bar 9, set start_bar=9). Curves added before form.build keep their original bar numbers, which is correct for section A but wrong for a repeated section B.
• Staggered expression peaks across voices — give each voice a different peak bar to create a rolling swell through the ensemble rather than a single unison climax. Example: flute peaks at bar 8 (from_value=20 to_value=90 curve=exponential), strings at bar 10, cello at bar 12. The exponential shape (quadratic ease-in: slow start, fast finish) suits crescendos; combine with a second curve going back down for a complete swell arc.
• CC events pass through all transforms unchanged — transpose, augment, retrograde, invert all leave CC/PC events in place. This is correct behavior: a pan setting should survive a pitch transform.