# 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 `\`. 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: `_lead.griff`, `_bass.briff`, `_drums.sd3p`, and `.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 `. 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.