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

43 KiB
Raw Permalink Blame History

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_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 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 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):

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 & 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):

{
  "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), 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.

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.