785 lines
43 KiB
Markdown
785 lines
43 KiB
Markdown
# 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.
|