887 lines
47 KiB
Markdown
887 lines
47 KiB
Markdown
# Riff-Groove-Builder: Architecture and Phased Implementation Plan
|
|
|
|
Status: Approved. Executable fixes 7/8 implement real Riffer `.griff`/`.briff`
|
|
and SD3 `.sd3p` codecs, original fixtures and independent saved validators.
|
|
Step 9 fix wires them into actual MCP/installed-wheel generation, target defaults,
|
|
operator-local template configuration and atomic multi-artifact publication.
|
|
See CURRENT `report_7_fix.md`, `report_8_fix.md`, `report_9_fix.md`.
|
|
Final native/MIDI/CC software, exact persisted wheel and read-only operator
|
|
template acceptance are recorded CURRENT-first in `report_10.md`; the earlier
|
|
MIDI-only report is preserved there as retracted historical scope.
|
|
The original full native/application definition of done is NOT complete:
|
|
plugin/SD3 open/play/save/reload, audible checks and Cubase import remain UNRUN.
|
|
Native codec/service implementation is no longer absent-evidence BLOCKED.
|
|
Earlier step descriptions below retain historical sequencing, not current readiness.
|
|
|
|
## Continuation decision: functional MIDI fallback
|
|
|
|
### Retraction of interim closure and native-format continuation
|
|
|
|
At the earlier MIDI-only Step 10 checkpoint, independent fallback software was verified,
|
|
including installed-wheel stdio generation, 1,119 passing tests, lint, formatting,
|
|
strict types, dependency checks, and wheel/sdist builds. The final targeted
|
|
native investigation is recorded in `report_7_fix.md`; it did not establish an
|
|
AGP layout or obtain a usable native fixture.
|
|
|
|
The earlier interim closure was an orchestration error, not user approval to
|
|
reduce scope. The original native-output requirement remains active. The user
|
|
explicitly required continued implementation; native capability checks are not
|
|
accepted as native writers.
|
|
|
|
Read-only inspection of the standard local vendor folders subsequently found
|
|
genuine installed evidence that should have been checked earlier:
|
|
|
|
- Ample Metal Eclipse VST3 version 4.0.1; native Riffer guitar `.griff` files.
|
|
- Ample Metal Ray5 VST3 version 4.1.0; native Riffer bass `.briff` files.
|
|
- Both Riffer containers are XML with `Riff` root, layout `Ver="2.1"` and
|
|
`PPQBase="480"`, including actual note, articulation and CC fields.
|
|
- Superior Drummer executable version 3.4.4 and genuine text `.sd3p` projects
|
|
with `PlugVersion 3.4.4`, `SongTrack`, `MidiLoop` and packed `MidiEvents`.
|
|
|
|
The requested `.agp`/`.sdp` suffixes do not match these observed installed native
|
|
examples. A focused format-choice question received an unavailable-user response
|
|
delegating a pragmatic choice. The compatibility-preserving implementation
|
|
decision is to generate the actual `.griff`/`.briff`/`.sd3p` native files and
|
|
retain `agp`/`sdp` as request aliases, explicitly documenting this correction.
|
|
This preserves all three native targets; it is not another MIDI-only deferral
|
|
and does not authorize mislabeled file bytes. No `.strumseq` exporter is added.
|
|
|
|
Local native files remain read-only evidence. No factory musical sequence,
|
|
licensed manual, plugin binary or private template is copied into source/tests
|
|
or uploaded. Tests generate original minimal content. SD3 instrument setup may
|
|
use an operator-local template with its song replaced, never a shipped private
|
|
project. Native codecs, target maps, service wiring and final validation must
|
|
now be implemented and reviewed before full completion is claimed.
|
|
|
|
### Current native integration outcome (Step 9 fix, 2026-10-20)
|
|
|
|
The native implementation continuation above is executed in software:
|
|
all three target subsets are the unambiguous part defaults; standard maps remain
|
|
explicitly selectable fallbacks, never relabeled vendor maps. Default requests
|
|
produce combined MIDI and actual selected native suffixes. `agp`/`sdp` remain
|
|
aliases only. Native-only requests do not force MIDI unless known fallback is
|
|
required. Optional operator `--sd3-template` is not a tool-controlled path;
|
|
bad supplied templates are errors, absent optional template permits drum-only
|
|
fallback while preserving Riffer outputs. Source identity/content is preserved.
|
|
Palm mute is reachable for lead/bass, with native PM/PMP and MIDI switch/velocity
|
|
semantics; mixed-request drums stay normal with disclosed applicability.
|
|
Owned exclusive-create file identities and saved-content hashes cover the complete
|
|
multi-file stage before one Windows no-replace directory rename. Partial writes,
|
|
validation/model/IO/publication faults never become successful fallback.
|
|
Actual stdio and installed-wheel native generation and read-only genuine local
|
|
template acceptance use original generated music; private state stays ignored/local.
|
|
Report 9 fix records exact checks and remaining application-only limits.
|
|
No later prompt, application hosting or commit is part of this fix.
|
|
|
|
### Historical fallback execution clarification (superseded by native fixes above)
|
|
|
|
The plan was approved and Steps 1-4 accepted. Step 5 mechanics passed, while
|
|
real-target mappings and native layouts remained unverified. On the user's
|
|
autonomous-continuation instruction, the following execution clarification
|
|
supersedes earlier clauses that made every subsequent development step depend
|
|
on all vendor maps:
|
|
|
|
- Standard MIDI fallback is already in scope. Ship explicitly labeled standard
|
|
pitched-note/General MIDI percussion fallback profiles, distinguished from
|
|
vendor mappings in public profile metadata and generation warnings.
|
|
- Standard fallback data must be sourced from MIDI facts and documented server
|
|
policy, not relabeled synthetic fixtures or claims of plugin compatibility.
|
|
Unsupported vendor techniques remain explicit errors; never simulate a
|
|
keyswitch by guessing a vendor note.
|
|
- Step 5 fix can accept standard-fallback production mechanics while retaining
|
|
a separately tracked real-target mapping gate. This permits Step 6 text/MIDI
|
|
composition and the Step 9 fallback/service path to become operational.
|
|
- Implement native capability checks and explicit unavailability when layouts
|
|
cannot be established. Missing native evidence is not a completed native
|
|
writer, and MIDI fallback is never reported as native generation.
|
|
- Steps 7/8 real serialization and Step 10 application acceptance remain gated.
|
|
Their blockers must persist in reports and compatibility documentation; they
|
|
must not prevent independent fallback functionality from being completed.
|
|
- Worker prompts and report reviews still occur one at a time, with fix prompts
|
|
for defects. Any skipped/deferred native acceptance is disclosed, not passed.
|
|
|
|
Raw official Ample manual-page HTML, unlike the initial simplified extraction,
|
|
exposes the public Eclipse/Ray5 main-panel manuals and Riffer/Strummer manuals.
|
|
The initial "no usable mapping documentation" finding was incomplete. Their
|
|
technical facts may be used with precise source/limitations; no licensed manual
|
|
or factory song content is copied into the repository. Access to the manuals
|
|
alone does not verify native layouts or the user's installed configuration.
|
|
|
|
## 1. Purpose and scope
|
|
|
|
Build a Python MCP server that converts text descriptions into coordinated lead,
|
|
bass, and drum parts, then generates:
|
|
|
|
- `.agp` content for the user's Ample Guitars Eclips lead instrument.
|
|
- `.agp` content for the user's Ample Ray bass instrument.
|
|
- `.sdp` content for Superior Drummer 3.
|
|
- Standard MIDI `.mid` files, both directly requested and as an explicit fallback.
|
|
|
|
Use the user's instrument names until exact product names, versions, and import
|
|
workflows are verified. Native files are instrument-specific content loaded into
|
|
the relevant plugins in Cubase; they are not Cubase `.cpr` project files.
|
|
Compatibility must be demonstrated, not inferred from an extension.
|
|
|
|
The server uses JSON-RPC over stdio only. No HTTP server, GUI, audio analysis,
|
|
audio rendering, plugin hosting, DAW automation, external language-model service,
|
|
database, or unrelated musical/export formats are included.
|
|
|
|
This document is a design, not a claim that any implementation or compatibility
|
|
test already exists.
|
|
|
|
## 2. Repository findings and evidence gates
|
|
|
|
Initial inspection found an empty Git worktree with `docs`, `prompts`, and `src`
|
|
directories, no tracked files, and no existing Python manifest or tests.
|
|
|
|
Verified from public documentation:
|
|
|
|
- MCP stdio messages are UTF-8 JSON-RPC messages delimited by newlines.
|
|
stdout must contain only protocol messages; diagnostics belong on stderr.
|
|
- MCP requires initialization and capability/protocol negotiation.
|
|
- Mido can write and read Standard MIDI Files, including synchronous type 1
|
|
files, with integer delta times in ticks.
|
|
- MIDIUtil can independently construct multi-track MIDI files.
|
|
|
|
Not verified:
|
|
|
|
- What `.agp` represents in each exact Ample product/version, whether it contains
|
|
the required riff/groove data, and whether guitar and bass share a layout.
|
|
- What `.sdp` represents in the user's Superior Drummer 3 workflow and whether
|
|
it can contain generated song-track MIDI rather than only preset settings.
|
|
- Native file layouts, supported versions, templates, checksums, or serialization.
|
|
- Exact playable ranges, keyswitch numbers, CC semantics, velocity layers, and
|
|
drum maps for the user's instrument versions and presets.
|
|
|
|
The Ample manual URL fetched during planning did not yield usable format
|
|
documentation. The Toontrack manual page required login. Neither is evidence
|
|
that the requested native formats can be generated by writing MIDI with a new
|
|
extension.
|
|
|
|
### Native-format and profile evidence gate
|
|
|
|
Before implementing a native writer, obtain lawfully usable vendor documentation
|
|
or user-provided minimal files produced by the installed application:
|
|
|
|
1. Exact product/version and the application's export/import operation.
|
|
2. Empty, one-note/hit, and multi-note/hit examples.
|
|
3. Controlled examples changing tempo, timing, velocity, and articulation.
|
|
4. A documented native load/save round trip in the target plugin.
|
|
5. Permission to store and redistribute fixtures, or a documented local-only
|
|
fixture procedure when redistribution is not permitted.
|
|
|
|
Record source, version, observed structure, and unresolved fields. Do not upload
|
|
user files, credentials, licensed content, or repository code to third parties.
|
|
Do not bypass vendor authentication or copy licensed manuals into the repository.
|
|
|
|
Use a documented serializer when possible. A template-based serializer is
|
|
acceptable only after its fields, lengths/checksums, version constraints, and
|
|
content ownership are understood and round-trip tests prove the output works.
|
|
Do not patch arbitrary offsets or silently preserve unexplained musical data.
|
|
|
|
If evidence shows the requested extension cannot carry the required content,
|
|
report the contradiction and request a decision. Do not substitute another
|
|
proprietary format or expand scope without approval.
|
|
|
|
Native evidence and MIDI mapping evidence are separate gates: a usable MIDI
|
|
articulation map does not establish a native file layout. MIDI-only development
|
|
can continue without native layouts, but plugin-specific MIDI compatibility and
|
|
articulation claims still require verified instrument mappings.
|
|
|
|
## 3. Technology and dependency decisions
|
|
|
|
- Python with a proposed minimum of 3.11; verify compatibility with the selected
|
|
dependencies during Step 1 before committing the supported-version policy.
|
|
- Official Python MCP SDK for stdio transport, lifecycle, protocol validation,
|
|
tool registration, and JSON-RPC behavior. Do not write a competing transport.
|
|
- Pydantic models and JSON Schema for tool inputs, outputs, musical structures,
|
|
and profile validation, aligned with the selected SDK.
|
|
- `mido` as the single production MIDI event writer and read-back validator.
|
|
It provides explicit control over ticks and event ordering.
|
|
- `MIDIUtil` / `python-midiutil` as an independent test-fixture generator for
|
|
cross-library MIDI interoperability checks, not a second production writer.
|
|
- `pytest`, the MCP SDK's supported asynchronous test approach, Ruff, and one
|
|
type checker, configured in `pyproject.toml`. Avoid redundant test/lint tools.
|
|
- Standard-library JSON, `fractions.Fraction`, `pathlib`, temporary directories,
|
|
and deterministic `random.Random` instances where useful.
|
|
|
|
Select and record compatible dependency versions in Step 1. Do not install
|
|
dependencies merely to produce this plan. No MIDI device, audio backend, Cubase
|
|
installation, or proprietary SDK is required for ordinary unit tests.
|
|
|
|
## 4. Proposed directory structure
|
|
|
|
Only this plan is created in the architecture phase. The remaining files are
|
|
created by their owning worker steps.
|
|
|
|
```text
|
|
.
|
|
|-- pyproject.toml
|
|
|-- README.md
|
|
|-- .gitignore
|
|
|-- src/
|
|
| `-- riff_groove_builder/
|
|
| |-- __init__.py
|
|
| |-- __main__.py
|
|
| |-- server.py
|
|
| |-- schemas.py
|
|
| |-- errors.py
|
|
| |-- description.py
|
|
| |-- compose.py
|
|
| |-- profiles.py
|
|
| |-- articulations.py
|
|
| |-- midi.py
|
|
| |-- service.py
|
|
| |-- formats/
|
|
| | |-- __init__.py
|
|
| | |-- agp.py
|
|
| | `-- sdp.py
|
|
| `-- data/
|
|
| `-- profiles/
|
|
| |-- eclips.<verified-version>.json
|
|
| |-- ray.<verified-version>.json
|
|
| `-- sd3.<verified-map-version>.json
|
|
|-- tests/
|
|
| |-- unit/
|
|
| |-- integration/
|
|
| `-- fixtures/
|
|
| |-- descriptions/
|
|
| |-- profiles/
|
|
| |-- midi/
|
|
| `-- native/
|
|
|-- docs/
|
|
| |-- architecture.md
|
|
| |-- compatibility.md
|
|
| |-- articulation-profiles.md
|
|
| `-- formats/
|
|
| |-- agp.md
|
|
| `-- sdp.md
|
|
`-- prompts/
|
|
|-- plan.md
|
|
|-- step_N.md
|
|
|-- report_N.md
|
|
|-- step_N_fix.md
|
|
`-- report_N_fix.md
|
|
```
|
|
|
|
Angle-bracket version placeholders above are naming examples, not literal file
|
|
names or verified version identifiers. Production profile files are created
|
|
only when their data is supported by evidence. Synthetic test profiles remain
|
|
under test fixtures and are never advertised as real instrument mappings.
|
|
|
|
## 5. Core modules and data flow
|
|
|
|
```text
|
|
MCP client
|
|
-> server: SDK lifecycle, tools/list, tools/call
|
|
-> schemas: strict input validation
|
|
-> description: text -> normalized musical intent
|
|
-> compose: intent -> coordinated logical score
|
|
-> profiles + articulations: score -> instrument-specific event plan
|
|
-> service: output capability checks and requested-format policy
|
|
-> midi / formats.agp / formats.sdp: render into staging directory
|
|
-> independent read-back/structural validation
|
|
-> service: publish the complete artifact directory
|
|
-> server: typed structured result and concise text summary
|
|
```
|
|
|
|
| Module | Responsibility |
|
|
| --- | --- |
|
|
| `__main__.py` | Start the stdio server; accept a required local output-root setting; send startup failures to stderr and exit nonzero. |
|
|
| `server.py` | Register exactly the tools below, expose schemas, translate known domain failures to MCP tool errors, and keep stdout protocol-clean. |
|
|
| `schemas.py` | Define strict request/result models, normalized intent, logical score, scheduled MIDI events, profile capabilities, and artifact metadata. |
|
|
| `errors.py` | Define specific validation, unsupported-description, mapping, native-capability, serialization, and filesystem errors. |
|
|
| `description.py` | Resolve supported natural-language terms and explicit overrides; report contradictions, missing capabilities, and meaningful unsupported instructions. |
|
|
| `compose.py` | Generate deterministic lead/bass/drum patterns on one shared musical timeline, within verified ranges. |
|
|
| `profiles.py` | Load packaged, versioned profile data; validate MIDI ranges, layers, provenance, and native capabilities. |
|
|
| `articulations.py` | Compile logical techniques into note, keyswitch, velocity, and CC events with appropriate state/reset behavior. |
|
|
| `midi.py` | Convert scheduled absolute events to stable type 1 SMF tracks and validate the saved files with Mido. |
|
|
| `formats/agp.py` | Write and validate verified Ample native layouts, with separate target/version handling where required. |
|
|
| `formats/sdp.py` | Write and validate the verified Superior Drummer 3 native layout. |
|
|
| `service.py` | Coordinate the pipeline, enforce fallback policy, stage files, prevent output collisions, publish artifacts, and return actual results. |
|
|
|
|
Keep these as small concrete modules; introduce no generic plugin framework,
|
|
queue, database, persistent job system, or arbitrary exporter-discovery layer.
|
|
The three fixed output formats need only a small internal capability dispatch.
|
|
|
|
## 6. Internal musical representation
|
|
|
|
Separate musical intent from MIDI mechanics and native serialization.
|
|
|
|
- `MusicalIntent`: resolved description, selected parts, tempo, meter, key/mode,
|
|
bar count, supported rhythm/technique terms, and deterministic seed.
|
|
- `Score`: one shared tempo, meter, musical start, and end; ordered lead, bass,
|
|
and/or drum tracks.
|
|
- `LogicalNote`: part, pitch or drum voice, rational start/duration in
|
|
quarter-note beats, intensity, and normalized articulation name.
|
|
- `EventPlan`: absolute integer ticks, MIDI channel, event type, payload,
|
|
event role such as musical note or keyswitch, and stable ordering information.
|
|
- `InstrumentProfile`: exact instrument/map version, playable range, channel,
|
|
drum voice map if applicable, articulation definitions, evidence metadata,
|
|
and independently verified MIDI/native capabilities.
|
|
|
|
Use exact rational beat arithmetic until quantization. Proposed resolution is
|
|
960 ticks per quarter note. A bar lasts `numerator * 4 / denominator` quarter
|
|
notes, not always four beats. Reject unsupported subdivisions rather than
|
|
accumulating floating-point drift.
|
|
|
|
Do not model keyswitches as ordinary generated musical pitches. Preserve the
|
|
logical score as well as the compiled event plan so a native adapter can use
|
|
whichever representation its verified format actually requires.
|
|
|
|
## 7. MCP contract
|
|
|
|
Use the SDK's supported protocol negotiation; the 2025-11-25 specification is
|
|
the planning reference, not a license to hard-code an unsupported SDK version.
|
|
Advertise tools only, plus mandatory SDK protocol behavior. No sampling,
|
|
resources, prompts, HTTP, or remote requests are needed.
|
|
|
|
Both tools publish input and output JSON Schemas. Reject unknown input fields,
|
|
booleans masquerading as numeric values, non-finite numbers, duplicate list
|
|
items, and invalid cross-field combinations. Tool handlers call the same service
|
|
functions exercised by integration tests.
|
|
|
|
### Tool 1: `list_instrument_profiles`
|
|
|
|
Purpose: discover real instrument mappings, supported techniques, and format
|
|
availability before generation.
|
|
|
|
Parameters: an empty object; no additional properties.
|
|
|
|
Return type:
|
|
|
|
```text
|
|
ProfileListResult {
|
|
profiles: ProfileSummary[]
|
|
}
|
|
|
|
ProfileSummary {
|
|
id: string,
|
|
part: "lead" | "bass" | "drums",
|
|
instrument: "eclips" | "ray" | "sd3",
|
|
product_name: string,
|
|
product_version: string,
|
|
mapping_version: string,
|
|
midi_available: boolean,
|
|
native_format: "agp" | "sdp",
|
|
native_available: boolean,
|
|
supported_articulations: string[],
|
|
limitations: string[]
|
|
}
|
|
```
|
|
|
|
An empty registry is returned honestly as an empty list. Unavailable capabilities
|
|
may be listed with explicit limitations; synthetic fixtures are excluded.
|
|
No absolute private fixture paths or licensed manual contents are exposed.
|
|
|
|
### Tool 2: `generate_music`
|
|
|
|
Purpose: create coordinated musical content from a description and export the
|
|
requested native files and/or MIDI.
|
|
|
|
| Parameter | Type | Required/default | Meaning |
|
|
| --- | --- | --- | --- |
|
|
| `description` | string, 1-4000 nonblank characters | Required | Natural-language musical request within the documented supported vocabulary. |
|
|
| `basename` | string matching `[A-Za-z0-9][A-Za-z0-9_-]{0,63}` | Required | Safe artifact-directory/file stem; Windows reserved names are also rejected. |
|
|
| `parts` | unique nonempty array of `lead`, `bass`, `drums` | Optional | If absent, infer explicit part-selection language; otherwise default to all three and report that assumption. |
|
|
| `formats` | unique nonempty array of `mid`, `agp`, `sdp` | Optional | If absent, request MIDI and the native format relevant to each selected part. |
|
|
| `tempo_bpm` | finite number, 20-300 | Optional | Explicit tempo override. |
|
|
| `bars` | integer, 1-256 | Optional | Explicit length override. |
|
|
| `time_signature` | object `{numerator: integer 1-16, denominator: 1|2|4|8|16}` | Optional | Explicit meter override. |
|
|
| `key` | string from documented pitch-class plus `major`/`minor` grammar | Optional | Explicit tonality override. |
|
|
| `profiles` | object with optional `lead`, `bass`, `drums` profile-ID strings | Optional | Select verified versions; entries must refer to selected parts. |
|
|
| `seed` | integer, 0-2147483647 | Default `0` | Local deterministic variation; never use global random state. |
|
|
| `allow_midi_fallback` | boolean | Default `true` | Permit explicitly reported MIDI substitution for unavailable requested native capabilities. |
|
|
|
|
The limits are proposed bounded-generation defaults, subject to plan review.
|
|
Also enforce a documented generated-event budget, initially 100,000 events,
|
|
before serialization. These are resource safeguards, not extra musical features.
|
|
|
|
Rules:
|
|
|
|
- Explicit structured overrides win over text and are disclosed in the result.
|
|
Contradictory text without an override is an error with actionable details.
|
|
- Unspecified musical defaults are 120 BPM, four bars, 4/4, and E minor; return
|
|
the assumptions. Do not invent unrequested song sections or tempo changes.
|
|
- Eclips is lead, Ray is bass, SD3 is drums. Select a default profile only when
|
|
the registry declares an unambiguous verified default; otherwise return a
|
|
profile-selection error identifying the available choices.
|
|
- Explicit `agp` requires at least one selected lead/bass part; explicit `sdp`
|
|
requires drums. Apply a format only to its relevant selected parts.
|
|
- One combined `.mid` contains every selected part when MIDI is requested.
|
|
- An allowed native fallback also emits one combined `.mid` containing all
|
|
selected parts, even if `mid` was not explicitly listed. Explain which native
|
|
targets it substitutes for. Emit it only once.
|
|
- Unknown or unverifiable plugin mappings are not repaired by guessed MIDI
|
|
events. MIDI fallback for a target requires a verified map for the requested
|
|
notes/techniques; otherwise fail explicitly.
|
|
|
|
Success return type:
|
|
|
|
```text
|
|
GenerationResult {
|
|
status: "complete" | "midi_fallback",
|
|
resolved: {
|
|
parts: ("lead" | "bass" | "drums")[],
|
|
tempo_bpm: number,
|
|
bars: integer,
|
|
time_signature: {numerator: integer, denominator: integer},
|
|
key: string,
|
|
seed: integer,
|
|
profile_ids: object,
|
|
assumptions: string[],
|
|
overrides: string[],
|
|
musical_start_tick: integer,
|
|
musical_end_tick: integer,
|
|
ticks_per_quarter: integer
|
|
},
|
|
artifacts: [{
|
|
format: "mid" | "agp" | "sdp",
|
|
parts: ("lead" | "bass" | "drums")[],
|
|
path: string,
|
|
size_bytes: integer,
|
|
profile_ids: string[],
|
|
fallback_for: ("lead" | "bass" | "drums")[]
|
|
}],
|
|
warnings: [{code: string, part: string | null, message: string}]
|
|
}
|
|
```
|
|
|
|
`path` is the resolved absolute local path to an actually published file, not
|
|
encoded file bytes. No MCP resource endpoint or on-disk sidecar is introduced.
|
|
Native artifacts each identify one part; the MIDI artifact identifies all its
|
|
included tracks. `complete` means every requested applicable output was made.
|
|
`midi_fallback` means native output was unavailable and an allowed substitution
|
|
was made; it must include explicit warnings, not success-shaped silence.
|
|
|
|
Use MCP `structuredContent` with a concise text content summary for successful
|
|
results. For domain failures, return `isError: true` and a structured
|
|
`GenerationError {code, message, details}` branch declared in the tool's output
|
|
schema, subject to the selected SDK's schema facilities. Protocol-level malformed
|
|
requests remain SDK JSON-RPC errors; do not mislabel every error as a parse error.
|
|
|
|
Expected error codes include `INVALID_REQUEST`, `UNSUPPORTED_DESCRIPTION`,
|
|
`PROFILE_REQUIRED`, `UNSUPPORTED_ARTICULATION`, `NATIVE_FORMAT_UNAVAILABLE`,
|
|
`OUTPUT_EXISTS`, `OUTPUT_IO_ERROR`, and `SERIALIZATION_ERROR`.
|
|
|
|
## 8. Text interpretation and composition strategy
|
|
|
|
Start with a documented, deterministic local vocabulary rather than adding a
|
|
model provider. Support explicit note/key names, tempo, meter, bar length,
|
|
part selection, note subdivisions, rests, and verified articulation aliases.
|
|
Small rhythm templates implement riff, lead, bass groove, and drum-pattern
|
|
requests; each template shares the same grid and key.
|
|
|
|
Translate supported qualitative terms through documented rules, such as a
|
|
specific tempo for "slow" when no numeric tempo is provided. Freeze those rules
|
|
in tests. Descriptive filler may be ignored, but materially unsupported musical
|
|
instructions must produce an actionable error, not an unrelated generic loop.
|
|
Support more text vocabulary only when necessary for this scoped generation.
|
|
|
|
Lead and bass use the resolved key and verified playable ranges. Drums use the
|
|
selected SD3 map, never an assumed General MIDI map disguised as an SD3 map.
|
|
Requested lead/bass/drum parts align over exactly the resolved bar count.
|
|
Any optional variation is seeded, bounded, and cannot move notes outside the
|
|
range, timeline, or supported articulation semantics.
|
|
|
|
## 9. Articulation mapping and event scheduling
|
|
|
|
Profiles are declarative, versioned JSON data validated at load time. For each
|
|
articulation store the applicable combination of:
|
|
|
|
- Canonical name and supported text aliases.
|
|
- Keyswitch note number, velocity, gate length, lead time, and channel.
|
|
- Whether switching is latched or momentary, and required reset/release actions.
|
|
- CC number/value actions, their channel and timing, and any reset value.
|
|
- Verified velocity-layer ranges and intensity-to-layer behavior.
|
|
- Playable note range or percussion voice mapping and overlap restrictions.
|
|
- Source/version provenance and limitations.
|
|
|
|
For example, text "palm mute" normalizes to `palm_mute`. The selected verified
|
|
Eclips or Ray profile supplies the actual keyswitch/CC/layer values; the compiler
|
|
emits those controls before the associated musical note and releases/resets
|
|
them according to the profile. This plan intentionally specifies no unverified
|
|
vendor note number. Tests may use clearly labeled synthetic values.
|
|
|
|
MIDI numbers are authoritative; octave labels alone are insufficient because
|
|
applications label octaves differently. Musical note-on velocity is 1-127;
|
|
controller values and note-off velocities are 0-127. Layer boundaries must be
|
|
valid, non-overlapping, and tested at both ends. Never silently clamp an invalid
|
|
profile or intensity into a plausible output.
|
|
|
|
The scheduler must:
|
|
|
|
1. Resolve profile state independently per part/channel; lead, bass, and drums
|
|
use separate channels, with the drum channel documented by its profile.
|
|
2. Emit selection controls only when needed, unless a momentary technique
|
|
requires per-note triggers.
|
|
3. Reject overlapping notes requiring incompatible latched articulations on
|
|
the same channel unless the verified profile supplies a supported mechanism.
|
|
4. Never emit negative ticks. For required pre-note lead time at song start,
|
|
calculate one common pre-roll for all parts and all applicable native
|
|
adapters. Report the musical-start tick; never independently shift one part.
|
|
If a native format cannot preserve that relationship, mark that native
|
|
capability unavailable rather than misaligning outputs.
|
|
5. Apply profile lead times explicitly. At equal ticks, finish applicable
|
|
releases/note-offs, then selection/reset controls as dictated by state
|
|
transitions, then note-ons; use stable tie-breaking. Do not let a generic
|
|
sort undo a profile's required causal ordering.
|
|
6. Pair every musical note and keyswitch note with a release, handle repeated
|
|
same-pitch notes, and restore momentary CC/keyswitch state appropriately.
|
|
7. Preserve control events in the same part track as affected notes so a
|
|
single Cubase part import does not lose its switches.
|
|
|
|
Standard MIDI fallback retains the verified target's articulation events.
|
|
It does not guarantee that arbitrary General MIDI synthesizers will reproduce
|
|
plugin articulations.
|
|
|
|
## 10. File generation and publication
|
|
|
|
### Standard MIDI
|
|
|
|
- Produce synchronous SMF type 1 with a conductor track plus selected part
|
|
tracks, shared resolution, tempo, time signature, and meaningful track names.
|
|
- Quantize exact beat positions to the documented tick grid, stable-sort
|
|
absolute events, and convert to nonnegative integer delta times once.
|
|
- Include valid end-of-track events at the shared end boundary, accounting for
|
|
pre-roll and necessary control releases. Distinguish musical end from any
|
|
documented release tail.
|
|
- Mido reads each saved file back. Validate header/type, track layout, timing,
|
|
channels, tempo/meter, note pairing, CC payloads, and expected duration.
|
|
- Use MIDIUtil-generated reference files in tests to compare normalized musical
|
|
events. Do not require byte equality across libraries.
|
|
|
|
### Ample `.agp`
|
|
|
|
- Lead and bass get separate artifacts, normally `<basename>_lead.agp` and
|
|
`<basename>_bass.agp`.
|
|
- Support only layouts/versions established by the native evidence gate.
|
|
- Determine whether the native format stores notes, patterns, articulation
|
|
identifiers, MIDI events, preset state, or references. Serialize the correct
|
|
representation; do not assume it is a MIDI container.
|
|
- Reuse shared score/event structures, but share guitar/bass serialization only
|
|
if evidence proves compatibility.
|
|
- Validate structure and supported round trips automatically. Require an actual
|
|
Eclips/Ray import test before claiming each instrument/version compatible.
|
|
|
|
### Superior Drummer 3 `.sdp`
|
|
|
|
- Normally emit `<basename>_drums.sdp`.
|
|
- Verify whether the extension supports the generated groove/song data.
|
|
Preset-only support does not satisfy a drum-song writer.
|
|
- Preserve the selected verified drum map, event timing, velocity, and supported
|
|
articulation controls in the representation the real format requires.
|
|
- Validate structure/round trips and require a real SD3 import test before a
|
|
compatibility claim.
|
|
|
|
### Fallback and filesystem behavior
|
|
|
|
Check known native capabilities before writing. If a requested native capability
|
|
is unavailable and fallback is allowed, retain available requested native outputs
|
|
and emit the combined MIDI plus explicit `NATIVE_FORMAT_UNAVAILABLE` warnings.
|
|
If fallback is disabled, fail without publishing any files.
|
|
|
|
Fallback applies only to known capability limitations. Unexpected serialization
|
|
errors, corrupt templates, invalid profiles, permission errors, and disk errors
|
|
must fail visibly; do not hide them by returning a MIDI-only success.
|
|
|
|
The startup output root is local and configured by the operator. Tool requests
|
|
cannot supply arbitrary output paths. Resolve and validate it, reject unsafe
|
|
basenames and Windows reserved names, and prevent path traversal or escaping
|
|
through links/reparse points.
|
|
|
|
Stage the complete validated artifact set in a unique directory under that root.
|
|
Publish it as `<output-root>/<basename>` with a same-volume directory rename,
|
|
rejecting any existing destination rather than overwriting. A competing request
|
|
for the same basename must fail explicitly; do not overwrite or merge directories.
|
|
Return paths only after publication succeeds. On failure, clean up only this
|
|
request's temporary files. Keep all behavior testable with temporary directories.
|
|
|
|
No manifests, project databases, audio files, or extra output formats are needed.
|
|
|
|
## 11. Testing and compatibility strategy
|
|
|
|
### Unit tests
|
|
|
|
- Strict schemas: valid bounds, invalid numeric types/values, unknown fields,
|
|
conflicting parts/formats/profiles, and safe basenames.
|
|
- Text parsing: supported phrases, aliases, structured override precedence,
|
|
defaults, contradictions, and materially unsupported requests.
|
|
- Musical generation: exact bar lengths in different meters, aligned parts,
|
|
key/range constraints, deterministic seeds, and event-budget rejection.
|
|
- Profiles: provenance/capability fields, corrupt JSON, MIDI ranges, layer
|
|
boundaries, drum maps, and exclusion of synthetic production mappings.
|
|
- Articulations: keyswitch ordering/lead times, latching, momentary release,
|
|
CC reset, velocity layers, channel isolation, retriggers, and incompatible
|
|
overlapping articulations.
|
|
- MIDI: integer nonnegative deltas, note pairing, conductor data, pre-roll,
|
|
shared endings, and deterministic semantic output.
|
|
- Native adapters: verified structure/version behavior, known fixtures,
|
|
corrupted/truncated inputs, and explicit capability failures.
|
|
- Service: fallback enabled/disabled, honest warnings/status, no false native
|
|
artifacts, no publication after failure, and output-collision handling.
|
|
|
|
### Automated integration tests
|
|
|
|
- Description -> score -> mapped MIDI -> disk -> Mido read-back.
|
|
- MIDIUtil reference file -> Mido normalization, compared with production
|
|
output for the same controlled musical events.
|
|
- Request native and MIDI together; verify output names, actual signatures,
|
|
artifact metadata, exact musical events, and fallback policy.
|
|
- Use real verified native fixtures/validators when available; fake adapters
|
|
may test service plumbing but never establish native compatibility.
|
|
- Launch the installed Python module as a subprocess and exercise initialize,
|
|
initialized notification, tools/list, and tools/call over real stdio.
|
|
- Check parse/invalid-parameter/unknown-method handling supported by the SDK,
|
|
request-ID preservation, notification behavior, protocol-clean stdout, and
|
|
clean EOF shutdown. Do not invent a JSON-RPC `shutdown` method.
|
|
- Run from a different working directory and from the built distribution to
|
|
prove packaged profiles and imports work outside the repository.
|
|
- Check temporary-root confinement, unsafe paths, same-name collisions,
|
|
permission/serialization failures, and cleanup without deleting other files.
|
|
|
|
### Manual application acceptance
|
|
|
|
Keep a versioned matrix in `docs/compatibility.md` covering:
|
|
|
|
1. Import the MIDI into Cubase; confirm tempo/meter, track alignment, duration,
|
|
instrument routing, switches/CC, and usable musical content.
|
|
2. Load lead `.agp` into the exact Eclips version and bass `.agp` into Ray;
|
|
verify notes, timing, velocity, articulation, and subsequent save/reload.
|
|
3. Load `.sdp` into the exact SD3 version and verify drum song/groove content,
|
|
mapping, timing, dynamics, and save/reload.
|
|
4. Confirm native and MIDI variants represent the same requested musical parts.
|
|
5. Record application versions, fixture identifiers, expected/observed results,
|
|
and limitations without publishing licensed user data.
|
|
|
|
Pure-Python CI cannot replace these application checks. A missing application
|
|
or private fixture is a named blocker, not a passed test. Separate public tests
|
|
from private compatibility tests and disclose any skips in every report.
|
|
|
|
Use targeted tests during development, plus the complete suite, configured
|
|
lint/type checks, and package-build checks at final acceptance. No benchmarks,
|
|
coverage threshold, or unrelated CI platform is required by this scope.
|
|
|
|
## 12. Phased worker sequence
|
|
|
|
Every row becomes exactly one detailed worker prompt only when its turn is
|
|
approved. File lists identify the main owned surfaces; each prompt will specify
|
|
the exact test files and documentation changes after inspecting prior work.
|
|
Later workers reuse reviewed contracts rather than replacing working modules.
|
|
|
|
### Step 1: Foundation and compatibility evidence inventory
|
|
|
|
- Objective: establish packaging, test/lint/type commands, the package skeleton,
|
|
and an honest product/format/profile evidence inventory.
|
|
- Files: `pyproject.toml`, `.gitignore`, `README.md`, package `__init__.py`,
|
|
initial test scaffold, `docs/architecture.md`, `docs/compatibility.md`,
|
|
`docs/formats/agp.md`, and `docs/formats/sdp.md`.
|
|
- Implementation: select supported dependencies/Python policy, establish `src`
|
|
layout, record lawful fixture sources and exact instrument/version questions,
|
|
and document native/mapping gates without inventing implementations.
|
|
- Unit tests: package import/version smoke tests.
|
|
- Integration tests: build/install into a test environment and import from
|
|
outside the repository; run the configured checks.
|
|
- Acceptance: reproducible foundation and explicit evidence/blocker inventory.
|
|
An inventory can be complete while native evidence remains unresolved;
|
|
that does not certify a writer or permit bypassing its later gate.
|
|
|
|
### Step 2: Typed domain models and MCP tool contracts
|
|
|
|
- Depends on: Step 1.
|
|
- Files: `schemas.py`, `errors.py`, schema/domain tests, related contract docs.
|
|
- Implementation: strict request/result models, profile summaries, musical
|
|
intent/score/event models, validation rules, errors, and JSON Schemas.
|
|
- Unit tests: parameter bounds, default resolution boundaries, unknown fields,
|
|
incompatible combinations, event validity, and result/error schemas.
|
|
- Integration tests: representative requests/results round-trip through models
|
|
and published schemas, including all parts and formats.
|
|
- Acceptance: one authoritative typed contract with no duplicated validation.
|
|
|
|
### Step 3: MCP stdio server skeleton
|
|
|
|
- Depends on: Steps 1 and 2.
|
|
- Files: `server.py`, `__main__.py`, package entry point configuration,
|
|
protocol integration tests, startup usage documentation.
|
|
- Implementation: SDK stdio lifecycle, two tool registrations, output-root
|
|
configuration, stderr logging, and explicit unfinished-service errors.
|
|
Temporary unfinished errors are development-only and removed in Step 9.
|
|
- Unit tests: handler argument/result/error translation and root validation.
|
|
- Integration tests: real subprocess initialization, listing tools/schemas,
|
|
notification behavior, malformed requests, stdout cleanliness, and EOF.
|
|
- Acceptance: valid MCP skeleton; unfinished generation never claims success.
|
|
|
|
### Step 4: MIDI timing, scheduling, and file writer
|
|
|
|
- Depends on: Step 2.
|
|
- Files: `midi.py`, event-model refinements if needed, MIDI unit/integration
|
|
tests, lawful MIDI fixtures, timing documentation.
|
|
- Implementation: exact timeline math, deterministic event ordering, SMF type 1
|
|
writing, conductor/part tracks, and post-write validation.
|
|
- Unit tests: multiple meters, boundaries, repeated pitches, channels, event
|
|
ordering, pre-roll, release tails, note pairing, and invalid event rejection.
|
|
- Integration tests: multi-part files read back with Mido and independently
|
|
generated MIDIUtil reference-event comparisons.
|
|
- Acceptance: valid deterministic MIDI from explicit controlled event plans;
|
|
no unverified instrument-specific claims.
|
|
|
|
### Step 5: Instrument profiles and articulation compiler
|
|
|
|
- Depends on: Steps 2 and 4; verified mapping evidence for production targets.
|
|
- Files: `profiles.py`, `articulations.py`, verified profile JSON files,
|
|
synthetic profile fixtures, profile/compiler tests,
|
|
`docs/articulation-profiles.md`.
|
|
- Implementation: versioned mappings, real playable/drum ranges, keyswitch/CC
|
|
actions, layer selection, state transitions, and overlap restrictions.
|
|
- Unit tests: layer boundaries, aliases, latched/momentary switches, resets,
|
|
profile rejection, and channel/state isolation.
|
|
- Integration tests: logical palm-muted lead/bass and articulated drums compiled
|
|
to MIDI; assert exact events using documented profile values.
|
|
- Acceptance: real mappings have evidence. Synthetic tests can prove compiler
|
|
mechanics but cannot close a missing production-profile gate.
|
|
|
|
### Step 6: Text interpretation and coordinated composition
|
|
|
|
- Depends on: Steps 2, 4, and 5.
|
|
- Files: `description.py`, `compose.py`, description fixtures, parser/composer
|
|
unit tests, full text-to-MIDI integration tests, supported-text usage docs.
|
|
- Implementation: supported vocabulary, defaults/overrides, seeded bounded
|
|
patterns, aligned parts, key/range validation, and event-budget enforcement.
|
|
- Unit tests: parsing contradictions/unknown instructions, exact meter/bar
|
|
lengths, seed reproducibility, range compliance, and articulation selection.
|
|
- Integration tests: representative descriptions covering lead-only,
|
|
bass-only, drums-only, and combined parts, verified after MIDI read-back.
|
|
- Acceptance: genuinely text-driven content; no silent unrelated default loop.
|
|
|
|
### Step 7: Verified Ample `.agp` generation
|
|
|
|
- Depends on: Steps 4-6 and the Ample native evidence gate.
|
|
- Files: `formats/__init__.py`, `formats/agp.py`, lawful native fixtures,
|
|
Ample unit/integration tests, `docs/formats/agp.md`, compatibility matrix.
|
|
- Implementation: supported layout/version serialization for Eclips and Ray;
|
|
preserve exact rhythm, dynamics, and required articulation semantics.
|
|
- Unit tests: native fields, version checks, invalid data, fixture round trips,
|
|
and distinct guitar/bass behavior where necessary.
|
|
- Integration tests: generated native files structurally validated against
|
|
evidence; actual Eclips/Ray import and save/reload recorded separately.
|
|
- Acceptance: both targets verified. An unavailable adapter or renamed MIDI is
|
|
not completion. If blocked, issue an evidence/fix prompt and seek the needed
|
|
files/decision rather than pretending this step passed.
|
|
|
|
### Step 8: Verified Superior Drummer 3 `.sdp` generation
|
|
|
|
- Depends on: Steps 4-6 and the SD3 native evidence gate.
|
|
- Files: `formats/sdp.py`, lawful SD3 fixtures, SD3 unit/integration tests,
|
|
`docs/formats/sdp.md`, compatibility matrix.
|
|
- Implementation: the confirmed SD3 container/content representation with
|
|
generated drum events, mapping, timing, and dynamics.
|
|
- Unit tests: supported fields/versions, corrupt/truncated data, fixture
|
|
round trips, and mapping/articulation preservation.
|
|
- Integration tests: structural validation plus real SD3 import/save/reload.
|
|
- Acceptance: actual drum content loads correctly; a preset-only file or
|
|
metadata stub does not satisfy the requested generation.
|
|
|
|
### Step 9: Generation service, fallback, and complete MCP wiring
|
|
|
|
- Depends on: Steps 3-8.
|
|
- Files: `service.py`, `server.py`, result/error integration, service and
|
|
end-to-end stdio tests, final output/fallback usage documentation.
|
|
- Implementation: connect the full pipeline, profiles tool, capability policy,
|
|
all requested artifacts, atomic publication, structured results, and explicit
|
|
operational failures. Remove development-only unfinished handlers.
|
|
- Unit tests: output planning, fallback policy, error translation, safe names,
|
|
collision handling, and exact artifact/result metadata.
|
|
- Integration tests: real stdio generation in all formats; injected unavailable
|
|
capabilities with fallback on/off; serialization/IO failures; no partial
|
|
publication; concurrent same-basename requests.
|
|
- Acceptance: externally usable tools with honest results and no silent failures.
|
|
|
|
### Step 10: Compatibility acceptance and release readiness
|
|
|
|
- Depends on: Steps 1-9.
|
|
- Files: end-to-end/regression tests, packaging metadata as needed, `README.md`,
|
|
architecture/format/profile docs, and compatibility matrix.
|
|
- Implementation: close task-caused defects, verify installed distribution
|
|
behavior, and document MCP client configuration and Cubase/plugin imports.
|
|
Do not add unrelated capabilities during final hardening.
|
|
- Unit tests: complete suite with regressions for any fixes.
|
|
- Integration tests: installed-package stdio workflow, representative combined
|
|
exports, validated native fixtures, and final application acceptance matrix.
|
|
- Acceptance: configured lint/type checks, build, full automated suite, and
|
|
required manual compatibility evidence pass; all skips/blockers disclosed.
|
|
|
|
Although some dependencies are technically independent, execution is deliberately
|
|
one worker prompt at a time in the listed order. If a blocker requires reordering
|
|
independent work, the orchestrator must first record the proposed adjustment and
|
|
obtain review; it must not silently skip a failed or unreviewed step.
|
|
|
|
## 13. Worker prompt and report protocol
|
|
|
|
After this plan is reviewed:
|
|
|
|
1. Create only `prompts/step_1.md`; do not generate the later prompts in bulk.
|
|
2. Each prompt contains the objective, prerequisites/evidence gates, exact
|
|
files, implementation constraints, unit tests, integration tests, validation
|
|
commands, and measurable acceptance criteria.
|
|
3. Include this exact instruction, substituting the current step number for N:
|
|
|
|
> When complete, write your end-of-step report to ./prompts/report_N.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
|
|
|
|
4. Also require changed-file summaries, exact commands and outcomes, skipped
|
|
tests with reasons, compatibility evidence where relevant, and unresolved
|
|
blockers. Require the entire report inside one plain triple-backtick fence,
|
|
with no content outside it.
|
|
5. Hand off that prompt and wait. Do not implement the worker's task in parallel
|
|
or assume that creating a prompt means its task is complete.
|
|
6. Read `prompts/report_N.md`, inspect relevant implementation/evidence, and
|
|
evaluate acceptance critically. A report alone is not proof: run focused
|
|
checks where needed; native claims require real application evidence.
|
|
7. If defects, failed tests, undisclosed skips, or blockers remain, create
|
|
`prompts/step_N_fix.md` instead of the next step. Require
|
|
`prompts/report_N_fix.md`; read and evaluate it before advancing. If further
|
|
corrections are needed, revise the fix prompt and require a fresh report,
|
|
preserving prior outcomes in the report's history.
|
|
8. Ask for missing user-owned evidence or decisions when a blocker cannot be
|
|
resolved locally. Do not manufacture fixtures, maps, or passing results.
|
|
9. Create `prompts/step_(N+1).md` only after the current step is accepted.
|
|
|
|
Historical planning decision: no worker was launched and no first worker prompt
|
|
was created during the initial architecture-only request. User approval and the
|
|
continuation decision above subsequently authorized implementation; the initial
|
|
awaiting-review state is no longer current. Prior step reports remain historical.
|
|
|
|
## 14. Final definition of done
|
|
|
|
- A packaged Python server implements the reviewed MCP stdio contracts.
|
|
- Supported text descriptions generate aligned lead, bass, and drum content.
|
|
- Verified keyswitch, velocity-layer, and CC behavior survives export.
|
|
- Standard MIDI files validate and import into Cubase.
|
|
- Actual `.griff` / `.briff` files load into Eclipse 4.0.1 / Ray5 4.1.0;
|
|
`agp` is retained as a request alias, not a mislabeled file suffix.
|
|
- Actual `.sd3p` files load the generated drum content into SD3 3.4.4/SL-DFH;
|
|
`sdp` remains a request alias. Software serialization is verified, while
|
|
application load/play/save/reload remains UNRUN.
|
|
- Native fallback is explicit, test-covered, and never masks data/IO failures.
|
|
- No false file extensions, fabricated mappings, partial published requests,
|
|
protocol-noisy stdout, or unreported compatibility gaps remain.
|
|
- Tests, packaging checks, documentation, and required application evidence are
|
|
complete. MIDI-only support is useful interim progress, not completion of the
|
|
full requested scope.
|
|
|
|
## 15. Planning references
|
|
|
|
Public documentation consulted during architecture planning:
|
|
|
|
- [MCP stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
|
|
- [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
|
|
- [MCP tools and schemas](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
|
|
- [Mido Standard MIDI Files](https://mido.readthedocs.io/en/stable/files/midi.html)
|
|
- [MIDIUtil documentation](https://midiutil.readthedocs.io/en/1.2.1/)
|
|
- [Ample manual entry point](https://www.amplesound.net/en/manual.asp):
|
|
attempted; no usable format specification obtained.
|
|
- [Superior Drummer 3 manual entry point](https://www.toontrack.com/manual/superior-drummer-3/):
|
|
login required; no native layout verified.
|
|
|
|
Vendor references above identify evidence still needed; they do not establish
|
|
that `.agp` or `.sdp` serialization has been verified.
|