9.5 KiB
Bounded text-to-composition contract (Step 3)
This is a deterministic English subset, not arbitrary English understanding.
The Core API is in-process; Step 8's MCP generate_project reuses it unchanged.
This text contract alone implies no production profile, plugin playability,
drum mapping, audio or native-format compatibility. Generic profile/event
planning and a Standard MIDI writer consume successful models. MCP generation
requires explicit admitted profile IDs: AGLP/AGM/AGT/AME Documented Lead profiles
and ABJ Sustain-only Bass exist. ABJ PalmMute explicitly fails
unsupported_articulation; AMR and all Drums mappings remain unavailable.
Selecting unavailable roles or omitting a selected role's explicit profile fails the complete
request rather than changing the grammar/defaults or dropping those roles.
Grammar
Input is nonempty text of at most 16,384 UTF-16 characters. Keywords are
case-insensitive; ordinary whitespace (including newlines), commas, colons,
semicolons and full stops separate clauses. and can join clauses or numbered
beats. One optional generate may prefix the description. Settings and role
clauses can appear in any order. Punctuation separates tokens; it does not
erase unsupported words or turn decimal numbers into integers.
description = ["generate"] clause { separator clause }
setting = [ "at" ] integer "bpm"
| bar-count ("bar" | "bars")
| [ "in" ] root ("major" | "minor")
| numerator "/" denominator
role = pitched | "drums" | drum-part
pitched = [articulation] [pattern] ("lead guitar" | "lead" | "guitar" | "bass")
| ("lead guitar" | "lead" | "guitar" | "bass") [articulation] [pattern]
pattern = subdivision ["root-note" | "root notes"]
| "sustained" ["root-note" | "root notes"]
subdivision = ("quarter" | "eighth" | "sixteenth") ("note" | "notes")
articulation = "sustain" | "palm-muted" | "palm mute"
drum-part = ("kick" | "snare") "on" ("beat" | "beats") integer
{ "and" integer }
| "closed hi-hat" subdivision
root = A..G [ "#" | "b" | "♯" | "♭" ]
bar-count = integer | "one" | "two" | "three" | "four" | "five" | "six"
| "seven" | "eight" | "nine" | "ten" | "eleven" | "twelve"
| "thirteen" | "fourteen" | "fifteen" | "sixteen"
Hyphens in eighth-note, root-note, palm-muted and hi-hat are
interchangeable with spaces. sustained specifies the full-bar pattern, not a
vendor articulation. Explicit palm mute sustained bass is therefore meaningful.
Role-local modifiers never leak to another role. Patterns cannot straddle a
different clause or be specified both before and after a role.
Integers are unsigned ASCII decimal tokens (no signs, decimals, exponent
notation, mixed digit/word numbers or thousands separators). Only bar counts
also accept the words one through sixteen. Beat lists use and, not commas.
Repeated identical settings/role clauses/parts are accepted once, without
duplicating events; conflicting repetitions and duplicate beats are rejected.
Only one articulation and one pattern are allowed per pitched clause.
No synonyms other than those listed here are promised.
Examples:
Generate 4 bars at 120 BPM in E minor, 4/4: palm-muted eighth-note lead guitar, sustained root-note bass, kick on beats 1 and 3, snare on beats 2 and 4, and closed hi-hat eighth notes.
generate four bars at 120 bpm in F♯ minor: lead guitar palm mute sixteenth notes
3/8, 2 bars: kick on beats 1 and 3, snare on beat 2, closed hi-hat eighth notes
Unsupported meaningful text is an error, including genres, chord progressions,
tuning, melodies, swing, dynamics/velocity instructions, unknown articulations,
open hi-hat and additional drums. heavy metal lead, 120.5 bpm, lead legato,
bass quarter notes and eighth notes and kick on beats 1, 3 do not become
guessed defaults. Failures have stable codes, fields and offending phrases
where applicable, with actionable messages; they expose no partial plan/model.
Defaults and role selection
Every applied default is returned as a field/value pair in DefaultsApplied,
on both the parsed description and successful composition:
| Field | Value when omitted |
|---|---|
tempoBpm |
120 |
bars |
4 |
meter |
4/4 |
key |
E minor |
roles |
lead,bass,drums, only if no role or drum part is mentioned |
lead.pattern |
eighth notes |
bass.pattern |
sustained (one full-bar root note per bar) |
lead.articulation, bass.articulation |
sustain |
lead.rootOctave, bass.rootOctave |
4, 2 (only for selected pitched roles) |
lead.velocity, bass.velocity, drums.velocity |
96 (only for selected roles) |
drums.kick, drums.snare, drums.closedHiHat |
beats 1 and 3; beats 2 and 4; eighth notes |
Any explicit role selects only the mentioned roles. bass produces no lead
or drums; kick on beat 1 selects drums but adds neither snare nor hi-hat.
drums alone (also lead and drums) selects the full default drum pattern
only in 4/4. If any drum part is explicit, only explicit parts are generated,
even if drums also appears. A non-4/4 request selecting drums must provide
one or more explicit drum parts; no 4/4 pattern is silently applied.
Defaults for unselected roles/omitted explicit-subset drum parts are not applied.
C4=60, C2=36; add the normalized root pitch class, so E gives lead 64/bass 40. Enharmonics normalize to pitch classes 0..11 and canonical sharp names (Db -> C#, B# -> C, Cb -> B). Octaves are chosen after normalization; B# lead is C4=60. Key mode is preserved but does not change repeated root patterns. These are musical defaults, not production instrument ranges or mappings.
Exact timing, validation and resource bounds
All positions/durations are normalized signed Int64 rational quarter notes;
denominators must be positive. Default rational zero is 0/1. Arithmetic uses
checked integer intermediates and rejects results outside Int64 representation.
Tick conversion at 960 PPQ must be exact and fit signed Int64.
A bar is numerator * 4 / denominator quarter notes. Human beat 1 is the
start of the bar; beat N is (N-1) * 4 / denominator, not N-1 quarter
notes except in /4 meters. Meter numerator is 1..255; denominator must be a
power of two with an exactly tick-representable denominator beat (1..256).
Quarter/eighth/sixteenth patterns step by 1, 1/2, 1/4 quarter notes.
The subdivision must divide a bar exactly; no partial final note is truncated.
Sustained pitched notes span a full bar. Kick/snare durations are one
denominator beat; hi-hat durations equal its subdivision. Each event starts
at/after zero, has a positive duration and fits within the declared arrangement.
Gaps/rests are allowed: kick on beat 1 does not need a last-bar-end hit.
The model's declared musical extent is always all bars, independently of the
last event's end. No planning lead-in is added.
Bars must be a positive Int32; pitch is 0..127 and sounding velocity 1..127.
Tempo must be positive and finite with 60,000,000 / BPM in the SMF range
1..16,777,215 microseconds per quarter note. That value is rounded to the
nearest integer, midpoint away from zero, as SMF tempo resolution requires;
the requested BPM remains in the model. The parser accepts integer BPM only.
Undefined enum values, empty/duplicate roles, empty selected tracks and
pitched/drum event-kind mismatches are errors.
One fixed internal generated-event limit is 100,000 notes plus hits
combined (not MIDI note-ons/offs or switches). Exactly 100,000 is accepted;
100,001 is rejected with event_limit_exceeded, without expanding patterns.
Counts, arrangement extent and representability are preflighted with checked
arithmetic before allocating event lists. No public limit override, truncation,
randomization or shared mutable result collection exists.
The validator also checks manually constructed models, independent of parsing. Parsing/planning return explicit failure results; only expected numeric, representability and checked-overflow errors are translated to diagnostics. Profile ranges, articulation support and switch/channel validation remain Step 4 and require real evidence, currently absent.
Standard MIDI output boundary (Step 5)
The text parser/planner remains unchanged. After successful composition and
explicit profile/event planning, Generation's in-process
MidiFileWriter.WriteFile(absolutePath, composition, eventPlan, token) writes
SMF type 1 at 960 PPQ; Write(stream, composition, eventPlan, token) borrows a
writable stream. See the MIDI API guide
for exceptions, no-overwrite staging, cleanup and synchronous cancellation limits.
The conductor's tempo/meter stay at zero; every role uses the same planned lead-in and global end marker, including rests and later control tails. The four-bar example's 15,360 unshifted ticks become 15,600 with the integration tests' invented 240-tick lead-in. Its 32/4/48 musical counts exclude keyswitch control notes; those test-only numbers are not vendor mappings.
Requested BPM remains in the model; output metadata rounds the valid quotient
nearest-integer, midpoint away from zero. DryWetMIDI 8.0.3 accepts the actual
meter denominator through 128; Core continues accepting 256, but the
writer rejects /256 with a clear library-limitation exception. Each SMF delta
must be at most 0x0FFFFFFF; the conductor's unsplit end gap also bounds global
EndTick. Long gaps fail, never wrap or acquire filler events. These output
constraints do not silently alter parser/Core validation or musical semantics.