172 lines
9.5 KiB
Markdown
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.
|