|
|
||
|---|---|---|
| docs | ||
| prompts | ||
| src/riff_groove_builder | ||
| tests | ||
| .gitignore | ||
| README.md | ||
| pyproject.toml | ||
README.md
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 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 and
SD3 codec/results, current report.
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, report_2.md, and report_3.md, plus report_4.md. The current tested configuration and separate software/application outcomes are in the compatibility matrix and release report. 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.
$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:
# 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. 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,
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:
{
"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_availableis runtime readiness, not just codec metadata. SD3toontrack.sd3.3.4.4.core.v1additionally 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_musicvalidates 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 returnsstructuredContentmatchingGenerationResult. Every profile-list, generation and domain/validation error result also includes the complete same public object encoded as JSON in oneTextContentblock: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
formatsmeans 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 withfallback_for=["drums"]and a per-partNATIVE_FORMAT_UNAVAILABLEwarning. Fallback disabled fails before staging. - Requests also accept actual
griff/briff/sd3psuffix names for their corresponding parts;agp/sdpremain logical aliases. Public profile and artifact metadata use actual suffixes, never mislabeledagp/sdpbytes. Aliases and actual names together are deduplicated by actual part/format. - Target parts receive
VERIFIED_SUBSET_LIMITSwarnings, even for MIDI-only output; saved-file validation does not certify every tuning/technique/library. - All standard-profile parts always receive
STANDARD_MIDI_MAPPINGwarnings, 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_REQUESTerrors 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 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.
Deterministic text-to-MIDI generation
Example MCP generate_music arguments:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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 quarterbass guitar groove 72.5 BPM 3 bars 6/8 Bb minor eighthdrums only 155 BPM 2 bars 7/8 sixteenthlead bass drums 137.5 BPM 4 bars F# minor metal eighth with restsno drumsselects lead and bass, not drums.
Lower-level usage with an existing output directory (the writer never creates directories or overwrites a destination):
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.
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:
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:
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:
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 & Aare sixteenths,[4 trip let]declares triplets. Bare1&aerrors unlessGrid:/Subdivision:issixteenthsoreighth-triplets;eighthsis also supported. Bare numbers always mean whole denominator beats. With sixteenth grid,1&aexplicitly omitseand 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. ois normal/open articulation, not open-string fingering;xis 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,/orOverbass and[C3 E3 G3]simultaneous explicit voicing. In Notes (and Events), brackets group consecutive slots, not a chord.Em4OverB2gives 47/64/67/71;Em4/Bgives 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 orderedBar N:blocks support additional bars.Bar 2: hold previous note to bar endor 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):
{
"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.
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):
& '.\.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), andquarter_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) -> Pathexclusively 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.
Validation
# 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.
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:
& '.\.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
and 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,
compatibility matrix, and evidence checklists for
Riffer .griff/.briff and SD3 .sd3p.
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 and
SDP fix handoff 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.