Cubase-MCP-GAJ3T.MusicGen.R.../docs/text-description-contract.md

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.