Cubase-MCP-GAJ3T.MusicGen.R.../README.md

785 lines
43 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Riff-Groove-Builder
Local Windows Python MCP server that turns supported text into coordinated
native Riffer/SD3 and Standard MIDI lead, bass, and drum parts. The supported
target subsets are evidence-backed, not application-certified. The amended approved
[plan](prompts/plan.md) is authoritative.
**Current release: 0.2.0 — exact hybrid Counts/Events/Notes/Chords notation,
pitch/voicing interpretation, native/MIDI generation and atomic publication.**
The single version source is `riff_groove_builder.__version__`; package metadata
and MCP initialization both report **0.2.0** after a server restart.
The SDK-backed tools list three target defaults and three explicit standard
fallback profiles, and generate real native files and type-1 `.mid` files
from a deterministic closed grammar.
**Real Riffer XML 2.1 `.griff`/`.briff` writers and independent saved-file
validation support AME 4.0.1 normal/palm-mute/pinch-harmonic and AMR 4.1.0
normal/palm-mute subsets.**
**SD3 3.4.4 now has a real operator-template `.sd3p` song codec and SL-DFH
core three-voice subset.** All codecs are wired to the MCP service.
Application open/play/save/reload and Cubase acceptance remain unrun.
See [native codec API/evidence](docs/formats/agp.md) and
[SD3 codec/results](docs/formats/sdp.md), [current report](prompts/report_16.md).
Step-numbered earlier reports remain historical evidence, not retroactive
claims that earlier releases already supported public hybrid notation.
This is not a general natural-language model.
## Python and dependencies
The declared Python minimum is **3.11**. Selected direct dependencies' published
Python requirements permit that minimum; only **CPython 3.13.13, Windows AMD64**
has actually been tested. Other runtimes are not certified.
Runtime dependencies are the official `mcp` Python SDK (maintained 1.x API line),
Pydantic 2, and Mido. The development extra includes MIDIUtil for independent
synthetic MIDI reference tests, pytest, AnyIO's built-in pytest plugin, Ruff, mypy,
build tooling, and directly declared jsonschema plus its typing stubs for
contract validation. Future asynchronous tests should use `@pytest.mark.anyio`
with an `anyio_backend` fixture selecting `"asyncio"`, as the SDK does;
Trio and pytest-asyncio are not required.
Ranges are bounded compatibility constraints, not a lockfile or a claim that
every allowed version was tested. Exact tested versions are recorded in
[report_1.md](prompts/report_1.md), [report_2.md](prompts/report_2.md), and
[report_3.md](prompts/report_3.md), plus [report_4.md](prompts/report_4.md).
The current tested configuration and separate software/application outcomes are
in the [compatibility matrix](docs/compatibility.md#tested-software-configuration)
and [release report](prompts/report_16.md).
The SDK installs its own transport-related
transitive dependencies; this project adds no HTTP application or audio backend.
## Windows PowerShell setup
Run from the repository root. Set `$Python` to your installed Python >=3.11;
the following is the actual interpreter used for Step 1. No activation or
global package installation is needed. Scratch/build/install files stay inside
the ignored repository-local `.test-artifacts` directory.
```powershell
$Python = 'C:\Users\g3\AppData\Local\Programs\Python\Python313\python.exe'
$scratch = New-Item -ItemType Directory -Force '.test-artifacts\scratch'
$env:TEMP = $scratch.FullName
$env:TMP = $scratch.FullName
$env:TMPDIR = $scratch.FullName
& $Python -m venv .venv
& '.\.venv\Scripts\python.exe' -m pip install --disable-pip-version-check --no-cache-dir -e '.[dev]'
& '.\.venv\Scripts\python.exe' -m pip check
```
Initial dependency installation needs access to the package index (or an
operator-provided local wheelhouse). All subsequent checks below are offline
once those dependencies are installed. Set the scratch environment variables
again in each new shell before running builds.
## Start the MCP stdio service
After installing the package, provision an output directory yourself (or choose
an existing local directory). The server requires this option and pins the root.
Generation writes only under this root; startup does not probe writeability.
For example, in PowerShell:
```powershell
# Operator setup only; omit this if the directory already exists.
New-Item -ItemType Directory -Path 'D:\MusicGenOutput'
& '.\.venv\Scripts\python.exe' -m riff_groove_builder --output-dir 'D:\MusicGenOutput'
# Optional operator-local SD3 template; never supplied through tool arguments:
& '.\.venv\Scripts\python.exe' -m riff_groove_builder --output-dir 'D:\MusicGenOutput' --sd3-template 'C:\Users\g3\Documents\Toontrack\Superior Drummer 3\sd3-demo.sd3p'
```
This is a stdio protocol process, not an interactive console: normally an MCP
client launches it and sends initialization. Closing stdin ends the SDK session;
there is no custom shutdown request. No HTTP transport is provided. Missing,
nonexistent, non-directory, URI, UNC, device, and drive-relative roots are
rejected with stderr diagnostics and a nonzero exit, without protocol stdout.
Local existing relative paths are resolved against the launch working directory.
Root/ancestor links and Windows reparse points, traversal and mapped network
drives are rejected. Existing directory identities are rechecked during generation.
Publication currently requires Windows no-replace directory-rename semantics;
other OSes explicitly fail generation rather than silently weaken collision safety.
See [filesystem guarantees and limitations](docs/architecture.md#implemented-in-step-9).
Use trusted operator-controlled ACLs on the root, ancestors and volume: path
identity/reparse checks are not hostile-race-proof Windows handle confinement.
Failures clean only the verified owned stage; denied/unsafe cleanup is an
explicit error and may leave a stage for inspection. Rename is the commit point:
a crash or client disconnect afterward may leave valid output without a response.
No fsync/power-loss durability or post-publication rollback is promised.
### LM Studio MCP configuration
Following the [official LM Studio MCP setup](https://lmstudio.ai/docs/app/mcp),
the operator opens **Program → Install → Edit mcp.json**.
In LM Studio's MCP configuration, use the top-level **`mcpServers`** object,
not VS Code's `servers` object or its `type` field. The absolute interpreter
path makes this independent of LM Studio's working directory. The configured
output root **must already exist**; this example does not create it:
```json
{
"mcpServers": {
"riff-groove-builder": {
"command": "D:\\_Repos\\Code\\GAJ3T\\MCPs\\MusicGen\\GAJ3T.MusicGen.Riff-Groove-Builder\\.venv\\Scripts\\python.exe",
"args": ["-m", "riff_groove_builder", "--output-dir", "D:\\MusicGenOutput"]
}
}
}
```
Adapt the interpreter and existing root to your installation. VS Code uses a
different `.vscode\mcp.json` shape (`servers` and `type: "stdio"`); do not paste
that shape into LM Studio. This is operator documentation only: no live
LM Studio configuration, active chat, process or DAW is modified or certified.
Automated tests use the official MCP client and real module subprocesses.
For all-native operation append `"--sd3-template", "C:\\Users\\g3\\Documents\\Toontrack\\Superior Drummer 3\\sd3-demo.sd3p"`
to the client `args` array. Use your own SD3 3.4.4 SL-DFH project; no private
project or kit is shipped. It is read-only, validated at startup and pinned by
identity/size/mtime/hash during generation. Absent optional template is known
native unavailability; explicitly supplied missing, corrupt, unsupported or
changed templates are visible errors (never fallback). Source kit/mixer/tracker
and other non-song bytes are preserved in the generated local project.
Exactly two tools publish the reviewed input/output schemas:
- `list_instrument_profiles({})` returns six profiles: three target defaults
and three explicit standard fallbacks (`mapping_kind=standard_midi`).
`native_available` is runtime readiness, not just codec metadata.
SD3 `toontrack.sd3.3.4.4.core.v1` additionally requires a local template;
its mapped MIDI works without a template. Version/library/subset, defaults,
template requirements and unrun application certification appear in limitations.
- `generate_music` validates arguments, resolves text, selects maps, composes,
compiles, writes/reads back every requested available output in one unique stage,
then atomically publishes `<output-root>\<basename>`. Success returns `structuredContent`
matching `GenerationResult`. Every profile-list, generation and domain/validation
error result also includes the complete same public object encoded as JSON in
one `TextContent` block: `json.loads(content[0].text) == structuredContent`.
Text-only MCP clients therefore see real IDs, paths, metadata, warnings and
actionable corrections, not just a summary.
- Omitted/null `formats` means combined MIDI plus each selected part's actual native
target: `<basename>_lead.griff`, `<basename>_bass.briff`,
`<basename>_drums.sd3p`, and `<basename>.mid`.
Explicit `["mid"]` is complete without native preflight or a template.
Native-only requests emit only requested native files when all are available.
Missing template with allowed fallback retains real lead/bass natives plus one
combined MIDI with `fallback_for=["drums"]` and a per-part
`NATIVE_FORMAT_UNAVAILABLE` warning. Fallback disabled fails before staging.
- Requests also accept actual `griff` / `briff` / `sd3p` suffix names for their
corresponding parts; `agp` / `sdp` remain logical aliases. Public profile and
artifact metadata use actual suffixes, never mislabeled `agp` / `sdp` bytes.
Aliases and actual names together are deduplicated by actual part/format.
- Target parts receive `VERIFIED_SUBSET_LIMITS` warnings, even for MIDI-only
output; saved-file validation does not certify every tuning/technique/library.
- All standard-profile parts always receive `STANDARD_MIDI_MAPPING` warnings,
including explicit MIDI-only successes. No vendor compatibility is implied.
- Existing destinations (including empty directories) return `OUTPUT_EXISTS`;
no replacement or merge is allowed. Other IO/serialization/unsupported-technique
failures never become fallback successes.
- Invalid tool inputs return typed `INVALID_REQUEST` errors with safe field/reason/correction
details. Unknown tools and protocol errors retain SDK error behavior rather
than being disguised as domain errors.
For guitar-only output use `parts: ["lead"]` and omit `formats`, or request
`["griff", "mid"]` (`agp` is the lead/bass alias). Bass uses `briff`/`agp`;
drums uses `sd3p`/`sdp`; `mid` works for all. `sd3p` is not a guitar format.
Omit `profiles` for defaults, or call `list_instrument_profiles({})` and copy
exact IDs for the selected parts. Never invent IDs such as `aggressive_rock`.
Do not add CC events (including reverb CC91) unless the user requests them.
Pass musical intent faithfully: the bounded beat-range/triplet/PH-hold grammar and
the [precise hybrid lanes](#hybrid-prose-and-exact-lanes) below are supported;
arbitrary prose melodies and changes/sequences are
unsupported, not invitations to invent a simpler result.
Structured `key` accepts full forms (`E minor`, `E Minor`, `Bb major`) and
conventional minor shorthand (`Em`, `F#m`, `Bbm`), canonicalized to sharp-spelled
pitch classes and lowercase mode. Thus `Em` and both E-minor full forms resolve
to `E minor`; `Bbm` resolves to `A# minor`. Use one optional ASCII `#` or
lowercase `b`; other modes, missing modes/bare letters, double/Unicode accidentals,
tabs and newlines remain invalid in structured keys. Description text also accepts
attached minor shorthand (`Em`, `F#m`, `Bbm`).
After updating an existing LM Studio installation, restart its MCP server and
start a **fresh chat** to refresh cached tool schemas/descriptions; an existing
chat can keep stale tool descriptions and previous wrong-call assumptions.
The operator must do both, then confirm initialization reports version **0.1.1**,
rediscover the two tools and, if selecting explicit profiles, call
`list_instrument_profiles({})` again. Retry the original request verbatim with
the minimal arguments below, not fabricated profiles, a drum format for lead,
or unsolicited CC91. Automated tests launch their own stdio children only;
they do not restart the live LM Studio process or demonstrate live model/UI success.
stdout contains only UTF-8 newline-delimited MCP JSON-RPC. Logs and startup
errors use stderr. SDK malformed-input handling can also send a protocol
`notifications/message` with generic `Internal Server Error`; this is not a raw
stdout log or a parse-error response. See [observed protocol behavior and
privacy boundaries](docs/architecture.md#implemented-in-step-3).
## Deterministic text-to-MIDI generation
Example MCP `generate_music` arguments:
```json
{
"description": "lead bass drums 137.5 BPM 2 bars 7/8 Bb minor quarter rests",
"basename": "example",
"formats": ["mid"],
"profiles": {
"lead": "standard.lead.v1",
"bass": "standard.bass.v1",
"drums": "standard.gm-drums.v1"
},
"seed": 42
}
```
Discover available IDs with `list_instrument_profiles({})` before selecting
`profiles`, for example `{"lead":"standard.lead.v1","bass":"standard.bass.v1",
"drums":"standard.gm-drums.v1"}`. These are explicit standard fallbacks, not defaults.
Defaults are `ample.ame.4.0.1.riffer.v1`, `ample.amr.4.1.0.riffer.v1`,
`toontrack.sd3.3.4.4.core.v1`. IDs must match selected parts.
For all-native generation with the optional template configured:
```json
{
"description": "lead bass drums palm mute 137.5 BPM 2 bars 7/8 Bb minor quarter rests",
"basename": "example_native",
"formats": ["agp", "sdp"],
"seed": 42,
"allow_midi_fallback": false
}
```
Omitting `formats` additionally requests MIDI. Without a template, omit
`allow_midi_fallback=false` to get real lead/bass natives plus drum MIDI fallback.
### Optional exact controller points
`cc_events` defaults to `[]`; omission/empty leaves all existing output unchanged.
Each strict object has only `part`, `beat`, `controller`, `value`. Beats are
nonnegative rational **quarter-note** positions relative to the common musical
start (after any articulation pre-roll), not absolute MIDI ticks or bar numbers.
For example, request lead/bass CC1 points and an explicit musical-end reset:
```json
{
"description": "lead bass 2 bars 7/8 quarter",
"basename": "controlled",
"allow_midi_fallback": false,
"cc_events": [
{"part": "lead", "beat": {"numerator": 0}, "controller": 1, "value": 11},
{"part": "lead", "beat": {"numerator": 1, "denominator": 2}, "controller": 1, "value": 73},
{"part": "lead", "beat": {"numerator": 7}, "controller": 1, "value": 0},
{"part": "bass", "beat": {"numerator": 1}, "controller": 1, "value": 127},
{"part": "bass", "beat": {"numerator": 7}, "controller": 1, "value": 0}
]
}
```
Controller/value are strict integers 0–127 (no booleans, floats, strings or
clamping). The rational numerator/denominator are strict integers; denominator
must be positive. Ratios normalize; duplicate `(part, beat, controller)` points
are rejected even if values agree or fractions differ in spelling. Parts must
be selected after text resolution, points must fit the resolved musical duration
(end resets are valid), and beats must fit the exact 960-PPQ tick grid. Controls,
musical note-ons/offs and articulation switches share the 100,000-event budget.
An explicit point colliding with an articulation-generated controller is an
actionable `INVALID_REQUEST`, not an override. Controls precede note-ons at the
same tick; no implicit reset or controller-to-technique/effect inference exists.
MIDI retains every valid requested controller/channel/tick/value, including
multiple controllers and end resets. The observed Riffer subset preserves only
CC1 stair points on its exact 480-PPQ grid; other controllers or sub-native-grid
timing cannot be silently dropped. The observed SD3 native subset establishes
note triples, **not controller triples**. A legitimate drum CC yields the
precise native preflight reason `sd3_native_controller_not_supported`.
Allowed fallback replaces only the affected native target with combined MIDI;
other valid natives remain. `allow_midi_fallback=false` fails before staging.
Wrong channel/note/role/release, corrupt templates and writer/read-back failures
remain errors, never controller fallback. Explicit `formats: ["mid"]` supports
all valid controls without native preflight or a drum template.
The explicit **standard-profile** MIDI example's shared public payload is shown below;
the 324-byte artifact is independently checked by installed-wheel tests.
The wire result has `isError: false`, this object in `structuredContent`, and
one text block containing a JSON encoding of the entire same object.
Its non-null `profiles` do not create structured musical overrides:
```json
{
"status": "complete",
"resolved": {
"parts": ["lead", "bass", "drums"],
"tempo_bpm": 137.5,
"bars": 2,
"time_signature": {"numerator": 7, "denominator": 8},
"key": "A# minor",
"seed": 42,
"profile_ids": {
"lead": "standard.lead.v1",
"bass": "standard.bass.v1",
"drums": "standard.gm-drums.v1"
},
"assumptions": [
"template: omitted; using rock.",
"technique: omitted; using normal."
],
"overrides": [],
"musical_start_tick": 0,
"musical_end_tick": 6720,
"ticks_per_quarter": 960
},
"artifacts": [
{
"format": "mid",
"parts": ["lead", "bass", "drums"],
"path": "D:\\MusicGenOutput\\example\\example.mid",
"size_bytes": 324,
"profile_ids": ["standard.lead.v1", "standard.bass.v1", "standard.gm-drums.v1"],
"fallback_for": []
}
],
"warnings": [
{"code": "STANDARD_MIDI_MAPPING", "part": "lead", "message": "standard.lead.v1 uses Standard MIDI only; not a verified Eclips/Ray/SD3 mapping or vendor compatibility claim."},
{"code": "STANDARD_MIDI_MAPPING", "part": "bass", "message": "standard.bass.v1 uses Standard MIDI only; not a verified Eclips/Ray/SD3 mapping or vendor compatibility claim."},
{"code": "STANDARD_MIDI_MAPPING", "part": "drums", "message": "standard.gm-drums.v1 uses Standard MIDI only; not a verified Eclips/Ray/SD3 mapping or vendor compatibility claim."}
]
}
```
Explicitly selecting those standard profiles with native formats reports
`status="midi_fallback"`, `fallback_for=["lead","bass","drums"]`
on the single combined artifact, and three additional per-part
`NATIVE_FORMAT_UNAVAILABLE` warnings with `riffer_profile_not_supported` (lead/bass)
or `sdp_profile_not_supported` (standard drums). It returns no native artifact.
For example, `{"description":"drums only","basename":"disabled",
"allow_midi_fallback":false}` returns `isError=true`, text guidance, and:
```json
{
"code": "NATIVE_FORMAT_UNAVAILABLE",
"message": "Request MIDI fallback or select a profile with verified native support.",
"details": {"part": "drums", "format": "sd3p", "reason": "sdp_template_required"}
}
```
That object is both `structuredContent` and the decoded JSON text, not a
JSON-RPC protocol error. No `disabled`
directory is created. The default drum profile is MIDI-capable without a template.
`lead only palm mute` now produces actual PM data with the default target profile;
explicit standard profiles still return `UNSUPPORTED_ARTICULATION`.
The Python service API is
`GenerationService(Path(existing_root), sd3_template=Path(local_sd3p)).generate_music(GenerateMusicRequest(...))`.
The `sd3_template` keyword is optional; `create_server` accepts the same typed keyword.
`list_instrument_profiles()` returns `ProfileListResult`. Service failures use
the existing named domain errors; raw descriptions/file bytes are not results.
Only the final directory is published. No sidecar manifests are generated.
The supported vocabulary is intentionally small. For example:
- `lead only 90 BPM 2 bars in 3/4 D major quarter`
- `bass guitar groove 72.5 BPM 3 bars 6/8 Bb minor eighth`
- `drums only 155 BPM 2 bars 7/8 sixteenth`
- `lead bass drums 137.5 BPM 4 bars F# minor metal eighth with rests`
- `no drums` selects lead and bass, not drums.
Lower-level usage with an **existing** output directory (the writer never creates
directories or overwrites a destination):
```python
from pathlib import Path
from riff_groove_builder.articulations import compile_score
from riff_groove_builder.compose import compose_score
from riff_groove_builder.description import resolve_description
from riff_groove_builder.midi import write_midi
from riff_groove_builder.profiles import load_profile_registry
from riff_groove_builder.schemas import GenerateMusicRequest, ProfileSelection
request = GenerateMusicRequest(
description="bass only 1 bar C major quarter", basename="example", seed=0
)
resolution = resolve_description(request)
profiles = load_profile_registry().select(
resolution.intent.parts, request.profiles or ProfileSelection()
)
score = compose_score(resolution.intent, profiles)
plan = compile_score(score, profiles)
write_midi(Path(r"D:\MusicGenOutput") / f"{request.basename}.mid", plan)
```
`resolution.assumptions` and `.overrides` are explicit string records used by
the service's `ResolvedGeneration`; this lower-level API does not create a result.
Structured tempo/bars/meter/key/parts win, including contradictory text for that
field. Unresolved contradictions and unknown material are named errors.
Defaults: 120 quarter-note BPM, four bars, 4/4, E minor, all three parts,
straight eighth notes, rock template, no rests, normal technique; request seed 0.
`slow` is 80 BPM and `fast` is 160, not a genre-dependent interpretation.
Case/whitespace-insensitive grammar supports decimal `BPM` (20–300), integer-valued
`bar(s)` (1–256; text `4.0 bars` is four bars), one fixed `n/d` meter
(numerator 1–16, denominator 1/2/4/8/16), major/natural-minor keys,
part lists/`only`/exclusions,
`quarter`/`eighth`/`sixteenth` (optional `-note(s)` or ` note(s)`), `rock`/`metal`,
and `rests`/`no rests`. Rests omit the last subdivision slot of **every** bar;
they do not shorten the score. Simple pattern instructions are global, not per-part schedules.
Palm mute applies to selected lead/bass only; in mixed requests drums remain
normal and that applicability is recorded in assumptions. Drum-only palm mute
fails explicitly, never silently disappearing. Part aliases include guitar/riff -> lead, bass guitar
(optionally riff/groove) -> bass, drum/drums -> drums.
Only these filler words are ignored: `please create produce generate make write a an the
some simple music pattern groove for with and at in of on notes note key tempo
meter straight`. This is not arbitrary prose; at least one recognized instruction
or `music`/`pattern`/`groove` is required.
Keys use A–G with optionally one ASCII `#` or `b`, then `major`/`minor` or attached `m`;
structured keys require ASCII spaces and reject other modes/double accidentals.
Enharmonic names normalize to sharp spelling (`Bb minor` → `A# minor`).
Non-null structured tempo/bars/meter/key/parts override text for that field,
including contradictions, and are disclosed in `overrides`; null is unresolved.
They do not authorize unknown vocabulary or changing instructions. Structured
integer fields reject `4.0`, booleans and strings even though text bars accept
integer-valued decimals. Descriptions are 1–4000 nonblank characters;
seed is a structured integer 0–2147483647, default 0, not text syntax.
See the [exact grammar, defaults, registers and template policies](docs/architecture.md#implemented-in-step-6-deterministic-text-and-composition).
### Hybrid prose and exact lanes
`generate_music.description` also accepts the following **public** notation.
Prose sets context; lanes specify exact music, never timing from column width.
The original two-measure E2 request remains byte-identical. This is the exact
description tested through source and the persisted 0.2.0 wheel:
```text
Lead guitar in E minor, 4/4, 120 BPM, 2 bars.
Bar 1:
Counts: 1 & 2 & 3 & [4 trip let]
Events: x x x x x x [x x ^]
Notes: E2 E2 E2 E2 E2 E2 E2 E2 E2
Hold the final E2 through the end of bar 2 without retriggering.
```
### Restart and fresh-chat prompt for 0.2.0
**After this verified update, restart the riff-groove-builder MCP in LM Studio
NOW, then start a NEW chat** to refresh cached tool descriptions and schemas.
The existing configured `.venv\Scripts\python.exe` resolves 0.2.0; no MCP config
edit or config reinstall is required. No live LM Studio/model/DAW interaction
or playback was run.
Copy the following prompt into that fresh chat. The description between the
markers is exactly the description above; markers/instructions are not part
of the tool's `description`. Pick a new unique basename on each later run:
```text
Call generate_music once. Set basename to "em_e2_hybrid_20261020_fresh_chat_01"
and allow_midi_fallback to false. Set description verbatim to the text between
BEGIN DESCRIPTION and END DESCRIPTION below. Omit all other arguments; do not
invent formats, profiles, control changes, programs, effects or an SD3 template.
Return the actual tool result and its output paths, not a claimed playback.
BEGIN DESCRIPTION
Lead guitar in E minor, 4/4, 120 BPM, 2 bars.
Bar 1:
Counts: 1 & 2 & 3 & [4 trip let]
Events: x x x x x x [x x ^]
Notes: E2 E2 E2 E2 E2 E2 E2 E2 E2
Hold the final E2 through the end of bar 2 without retriggering.
END DESCRIPTION
```
Minimal arguments `description` and `basename` alone are also tested; seed
defaults to 0, and lead-only `.mid` plus `.griff` and the target AME profile
resolve without invented IDs. The strict prompt above disables fallback to
require a real native file. It produces eight PM E2 attacks then one PH E2,
with no bar-2 retrigger, no CC/program/effects and no drum template.
For chords plus melody, replace those pitch rows with:
```text
Chords: F#2 F#2 D3 D3 Bb2 Bb2 - - -
Notes: - - - - - - C4 E4 G4
```
Change the hold's pitch to G4. This gives **21 musical tones**: six PM major
chord attacks, PM C4/E4, then one PH G4 through bar 2. D3 is exactly
MIDI50/54/57; explicit **D2** means MIDI38/42/45 and cannot be fingered
simultaneously on the accepted AME tuning. D2 therefore requires allowed
exact-MIDI fallback, or fails before publication when fallback is disabled.
It is never silently transposed to D3.
- Lane labels are case-insensitive; pitch letters remain uppercase A–G,
optional ASCII `#`/`b`, optional octave (**C4=60**). Compact/space/tab forms
are equivalent; `Chords: F#F# D3D3 BbBb ---` resolves omitted octaves visibly.
- Counts use meter-denominator beats: `1&` / `1 &` are eighths,
`1e&a` / `1 E & A` are sixteenths, `[4 trip let]` declares triplets.
Bare `1&a` errors unless `Grid:` / `Subdivision:` is `sixteenths` or
`eighth-triplets`; `eighths` is also supported. Bare numbers always mean
whole denominator beats. With sixteenth grid, `1&a` explicitly omits `e`
and uses offsets 0, 1/2, 3/4 (durations to next position/beat end).
3/4 and other denominator units use exact rational math, not compound grouping.
- `o` is normal/open **articulation**, not open-string fingering; `x` is PM;
`^` is AME lead-only PH; `-` is silence; `~` extends the adjacent prior sound
without a new attack. A tie after silence or carrying new pitches errors.
`/` and `\` in Events are **reserved, not implemented** slides, not normal
notes. They return an actionable origin/destination/timing codec error;
slash/Over in Chords is a separate supported bass-voicing operation.
- `Chords:` supports bare major, `m`/`min`, `(add4)`, octave-qualified roots,
`/` or `Over` bass and `[C3 E3 G3]` simultaneous explicit voicing.
In **Notes** (and Events), brackets group consecutive slots, not a chord.
`Em4OverB2` gives 47/64/67/71; `Em4/B` gives 59/64/67/71 with the bass
octave assumption disclosed. An explicit bass must already be lowest.
- One selected guitar/lead or bass part; Counts/Events are required per bar;
absent Notes/Chords rows are empty. One pitch source per slot; an entirely
unspecified attack source uses the disclosed low tonic nearest MIDI40.
Matching `|` boundaries or ordered `Bar N:` blocks support additional bars.
`Bar 2: hold previous note to bar end` or an all-`~` second bar also sustains
the same original attack and articulation.
- Key is context, never retuning. Contradictory explicit pitch/technique prose,
mismatched rows, ambiguous counts, invalid labels, unknown material, conflicting
rests/holds or incompatible meter/shorter-bar overrides are actionable errors.
Aggressive/tight metal style, low-register chord voicings and bounded velocity
variation do not alter precise notation. Seed policy is one existing bounded
draw per attack, shared by its tones; no unrequested CC/effects.
Complete text JSON and `structuredContent` include identical
`resolved.interpretation`: pitch sets, rational quarter-beat start/duration,
technique, part and held status. `resolved.assumptions` discloses register,
slash-bass and missing-pitch defaults. Prose-only outputs retain their old
musical bytes. No arbitrary natural-language rhythm or slide support is claimed.
Standard profiles realize `normal`/`sustain` only (`sustain` is not CC64).
Recognized `palm mute`, `palm-mute`, `palm muted`, `palm-muted`, `palm muting` fail with
`UnsupportedArticulationError` under those profiles; they are never simulated
by softer notes. Other techniques/instruments/modes, arbitrary triplets, swing,
polyrhythms, tempo changes, sections, vendor-name selection and audio requests
are unsupported. Composition is original bounded templates with local seeded
variation, not a genre engine, audio engine, factory loop or vendor map.
Target normal uses C0/24 with velocities 64–126. Target guitar palm mute uses
D0/26 and native PM; bass uses C0/24 with musical velocity 32–63 and native
**PMP**, not the separate D0 PM mode. Timing/channel/interpolation policy is
documented separately from vendor facts in the profile docs.
### Exact beat-range / triplet / cross-bar PH phrase
The following description works directly, with only a safe `basename`:
> Please produce a 4/4 riff in Em. With Chugging palm muting 8th notes from 1 to 3&;
> and triplets on 4&A with the A as a pinch harmonic that carries over a whole note
> in the 2nd measure.
Minimal executable `generate_music` arguments (the description is verbatim,
including its line breaks):
```json
{
"description": "Please produce a 4/4 riff in Em. With Chugging palm muting 8th notes from 1 to 3&;\nand triplets on 4&A with the A as a pinch harmonic that carries over a whole note\nin the 2nd measure.",
"basename": "phrase-original"
}
```
Omitted `parts`, `formats` and `profiles` resolve to lead only, `.mid` plus
`_lead.griff`, and `ample.ame.4.0.1.riffer.v1`. No drum template is needed.
`allow_midi_fallback` defaults to true; setting it to false is optional and
also succeeds for this evidenced native phrase. Omitted `cc_events` is empty.
This bounded lead-only 4/4 grammar requires both clauses: `[Chugging] palm
mute/muted/muting eighth/8th [notes] from X to Y`, and `triplets on B & A with
the A as a pinch harmonic that carries over a whole note in the second/2nd measure`.
Hyphenated palm-mute/muted/muting and pinch-harmonic also work. X/Y are inclusive
numeric beat labels 1–4, optionally followed by `&`; B is a numeric beat 1–4.
Whitespace around `&` is optional. Numeric ranges are computed, not canned:
`from 2 to 3&` starts at quarter beat 1 instead of 0. Overlapping/reversed
ranges, out-of-bar counts, non-4/4 meter, fewer than two bars, other parts,
extra rhythm/technique instructions and unsupported prose fail explicitly.
Scalar overrides cannot erase scheduled notes. Explicit longer scores keep
the phrase once, with trailing silence, not repeated bars.
Assumptions are returned: unspecified tempo remains **120 BPM**; a hold through
measure 2 implies **two bars**; `A` is the last eighth-triplet **count**, not an
A pitch; all notes use the playable tonic nearest MIDI40 (**E2/MIDI40** for
default Em/AME). There is no invented melody, transposition or CC/effect.
The final PH holds continuously through all of measure 2, without a bar-2 attack.
At MIDI960 the nine onsets are **0,480,960,1440,1920,2400,2880,3200,3520**;
durations are six ×480, two ×320, then **4160**, with final off/EOT **7680**.
AME switches PM=D0/26 then PH=G0/31, with zero lead and positive 30-tick pulse
gates (generator policy). Native480 uses half these times and actual `PM`/`PH`;
PH ends at **3840**. Only AME has evidenced PH support; bass/SD3/standard maps
are not promoted. See [mapping evidence](docs/articulation-profiles.md#eclipse-pinch-harmonic-extension).
The score uses exact quarter-note fractions; MIDI uses 960 ticks/quarter.
Each track spans exactly `bars * numerator * 4 / denominator` beats, including
rests. Simple-template notes may shorten only to fit the common bar boundary;
explicit phrase notes retain their exact cross-bar lengths. MIDI numbering
uses **C4 = 60**; simple-template preferred root anchors are E4 = 64 (lead),
E2 = 40 (bass),
adjusted to actual profile ranges, never clamped. GM kick/snare/hat aliases
resolve through the selected profile; no physical vendor notes are guessed.
Focused offline checks (existing venv):
```powershell
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_description.py tests\unit\test_compose.py tests\integration\test_text_to_midi.py -q
& '.\.venv\Scripts\python.exe' -m ruff check .
& '.\.venv\Scripts\python.exe' -m ruff format --check .
& '.\.venv\Scripts\python.exe' -m mypy --strict src tests
```
The integration checks write/read actual MIDI on disk, assert independent
tempo/meter/duration/pitch/channel/pairing facts, precise bass/drum events,
seeded byte determinism, and measured changes from supported text.
Their UUID-named repository-local workspaces clean themselves on success/failure.
## Explicit event-plan MIDI writer
`riff_groove_builder.midi` exposes typed internal-pipeline APIs:
- `beats_to_ticks(beats, ppq=960)`, `bar_ticks(meter, bars=1, ppq=960)`, and
`quarter_tempo(tempo_bpm)` perform exact rational timing/tempo conversion.
- `validate_event_plan(plan)` checks strict model content, timing/SMF bounds,
channel isolation, and musical/keyswitch note pairing.
- `write_midi(path: Path, plan: EventPlan) -> Path` exclusively creates one SMF
type 1 file, validates it in memory, then reads actual saved bytes with Mido
and compares all tracks/events against the plan. Existing destinations are
never overwritten and parent directories are never created.
- `validate_midi_file(path: Path, plan: EventPlan)` independently reads disk
content for the same expected-content check; it never deletes its input.
Timing uses integer ticks, default 960 ticks/quarter; off-grid fractions are
errors, not rounded approximations. BPM always means quarter notes/minute,
including 6/8. Tracks are Conductor followed by selected parts in resolved order,
with supplied notes/keyswitches/CCs, zero-tick tempo/meter, and one shared EOT.
Pre-roll and release tails are preserved without per-part shifts.
Same-channel/same-pitch overlap is rejected (including musical/keyswitch
collisions); boundary retriggers must release before re-onset according to the
supplied `(tick, priority, sequence)`. Different pitches can be polyphonic.
Distinct parts cannot share any stateful channel; no default drum channel,
program, real articulation map, or lead time is invented.
This writer does not compile logical notes or verify instrument compatibility.
The Step 9 service adds directory confinement checks, atomic artifact-set
publication, requested formats, fallback policy and MCP wiring. See the detailed
[timing and failure policies](docs/architecture.md#implemented-in-step-4).
## Validation
```powershell
# Targeted tests
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_profiles.py tests\unit\test_articulations.py tests\integration\test_articulation_midi.py -q
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_midi.py tests\integration\test_midi_files.py -q
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_server.py tests\integration\test_stdio.py -q
& '.\.venv\Scripts\python.exe' -m pytest tests\integration\test_distribution.py -q -s
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_schemas.py tests\unit\test_errors.py tests\integration\test_contracts.py -q
& '.\.venv\Scripts\python.exe' -m pytest tests\unit -q
& '.\.venv\Scripts\python.exe' -m pytest tests\integration -q -s
# Complete current suite
& '.\.venv\Scripts\python.exe' -m pytest -q -s
# Lint, formatting, and strict types
& '.\.venv\Scripts\python.exe' -m ruff check .
& '.\.venv\Scripts\python.exe' -m ruff format --check .
& '.\.venv\Scripts\python.exe' -m mypy
& '.\.venv\Scripts\python.exe' -m pip check
# Both sdist and wheel; the wheel is built from the sdist by default
& '.\.venv\Scripts\python.exe' -m build --no-isolation
```
If the editor test runner cannot discover these files, use the explicit
`.venv\Scripts\python.exe -m pytest` commands above; editor discovery failure
is not a test pass. Model/schema integration tests are entirely in memory and
make no mapping or file-generation claims. See the implemented
[contract and timing representation](docs/architecture.md#implemented-in-step-2).
The stdio tests launch the editable installed module with isolated imports from
a different working directory, negotiate with the SDK client, and use a small
raw test client for IDs, notifications, malformed input, stderr privacy, and EOF.
Timeouts and process cleanup are enforced; actual generated disk MIDI is inspected.
The MIDI tests create only small synthetic files in unique `.test-artifacts`
workspaces and remove them afterward. They compare real disk read-back and
independent MIDIUtil note/control events in 4/4, 3/4, 6/8, and 7/8, explicitly
accounting for MIDIUtil's release velocities, truncated tempo, conductor layout,
and local EOT conventions. This is SMF evidence, not plugin/application acceptance.
Patch-release acceptance can test the **exact persisted** wheel/sdist rather
than build another pair. With the scratch variables above set and an unused
release directory, build the wheel from the sdist and test that exact pair:
```powershell
& '.\.venv\Scripts\python.exe' -m build --no-isolation --outdir 'dist\lmstudio-fix-20261020'
$env:RIFF_RELEASE_DIST = (Resolve-Path 'dist\lmstudio-fix-20261020').Path
& '.\.venv\Scripts\python.exe' -m pytest -q
Remove-Item Env:\RIFF_RELEASE_DIST
```
Without that variable, distribution tests build their own pair offline.
The configured directory must be under this repository's ignored `dist`
directory and contain exactly one wheel and one sdist. Both modes install
noneditably with `--no-deps`, run the wheel from outside the checkout with
isolated Python, verify module/resource origins and text-only error recovery,
and independently inspect original MIDI/native notes.
The distribution integration tests build both distributions with installed build tools and
`--no-isolation`, then install the wheel in a separate local venv using
`--no-index --no-deps`. They import in isolated Python mode from the existing
parent directory **outside this checkout**, reject editable/source imports,
check the installed module's location, and compare public and metadata versions.
The subprocess venv and build workspace are cleaned even on test failure.
An additional real server acceptance test installs the built wheel offline with
`--no-index --no-deps --no-cache-dir --target <owned-directory>`. An isolated
`-I -B` Python bootstrap explicitly prepends that target, verifies all 16 package/
submodule entry locations and metadata there, and runs the installed `__main__`
from the existing parent directory **outside the checkout**. Runtime dependencies
are reused from the development venv; this is **not a fresh full dependency
installation/certification**. Six JSON resources are compared to real wheel
members and loaded by the installed server. Initialize/two tools/six profiles,
explicit MIDI/default/native-only fallback, schema-checked errors, exact real-disk
MIDI, UTF-8 protocol stdout, separate sanitized diagnostics, clean EOF before/after
initialization and bounded child cleanup are exercised offline.
The installed server also receives `--sd3-template` pointing to an independently
authored original minimal template, generates full default, alias and actual-name
native-only sets plus MIDI-only, and validates all saved outputs against the
requested score. Exact CC1/native stair points, explicit resets, mixed-controller
fallback, absent-template fallback, disabled fallback and no-overwrite errors
are exercised. README JSON examples are also checked against the typed schemas.
The ordinary `.venv` installs all declared dependencies; `pip check`, unit tests,
lint, types, and builds use that environment.
The package's version is authored only in `src\riff_groove_builder\__init__.py`;
setuptools derives distribution metadata from it. Package-data rules already
include the three standard and three native subset `data\profiles\*.json` resources.
Installed-wheel tests also write and independently read original `.griff`,
`.briff` and `.sd3p` files outside the checkout using synthetic original content.
## Profile/compiler mechanics (not production compatibility)
`profiles.load_profile_registry()` uses packaged resources and an explicit
six-resource manifest, not the working directory. Missing selections remain typed,
actionable failures; synthetic test-only profiles are rejected by production
discovery. `articulations.compile_score(score, selected_profiles, ppq=960)`
compiles explicit maps to the reviewed EventPlan/MIDI APIs with exact common
pre-roll, layer selection, stateful switches/CCs, polyphony checks, reset tails,
and a 100,000-event budget. It does not compose text or change the stdio tools.
The explicit standard fallbacks are `standard.lead.v1` (channel 0),
`standard.bass.v1` (1), and `standard.gm-drums.v1` (9), with public
`mapping_kind=standard_midi` and matching provenance. They support only normal/sustain,
no controls, and a documented
linear intensity-to-velocity policy. Pitched notes use the legal 0–127 range;
percussion uses the documented GM Level 1 map, **not an SD3 default map**.
The summary `instrument` field identifies intended routing only; product names
and limitations state **NOT verified Eclips/Ray/SD3 maps**.
See [profile schema, standard sources and policy](docs/articulation-profiles.md)
and [report_5_fix.md](prompts/report_5_fix.md). Synthetic numbers remain excluded.
Application compatibility remains unverified. Step 9 now connects these
APIs to the text-generation tools without changing the mapping evidence gates.
## Evidence gates
See the [architecture](docs/architecture.md),
[compatibility matrix](docs/compatibility.md), and evidence checklists for
[Riffer `.griff`/`.briff`](docs/formats/agp.md) and [SD3 `.sd3p`](docs/formats/sdp.md).
AME 4.0.1 and AMR 4.1.0 identities, Riffer layout and supported subset mappings
are established from local/public evidence. SD3 3.4.4's template-song format and
three core SL-DFH pad aliases are established from local native evidence.
Native service wiring is verified; real application import acceptance remains separate.
Renamed MIDI is not native-format support;
a preset-only container does not prove that generated musical content is stored.
The existing [AGP fix handoff](prompts/step_7_fix.md) and
[SDP fix handoff](prompts/step_8_fix.md) distinguish implemented codecs
from remaining application work. Codecs and service are no longer evidence-blocked.
Software/package acceptance is separate from original full native-project
completion. Cubase/plugin MIDI import and native load/save/reload are **UNRUN**,
not pytest skips or inferred successes from Mido parsing.