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

172 lines
9.5 KiB
Markdown

# 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.
```text
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](../README.md#in-process-standard-midi-generation)
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.