Cubase-MCP-GAJ3T.MusicGen.R.../prompts/step_5.md

10 KiB

Step 5: Build and verify Standard MIDI file generation

Objective and sequencing

Read the updated plan, the reviewed infrastructure and catalog report, and existing source/tests before editing.

Accepted baseline: .NET 10, DryWetMIDI 8.0.3, generic composition/articulation planning, seven declared instruments, no admitted production mappings, and 566 passing tests.

Implement the actual Standard MIDI writer now. Its prerequisite is the accepted generic Step 4 infrastructure, not verification of every product mapping. Synthetic profiles may prove format generation in tests only. This does not authorize guessed Ample/SD3 profiles, public generation tools or compatibility claims. Native writers and final tool integration remain later work.

Execute only this step; preserve existing work. Do not alter orchestrator prompts/plan, create later prompts, commit or delegate.

Files to create or modify

src\GAJ3T.MusicGen.RiffGrooveBuilder.Generation\
  Midi\MidiEventBuilder.cs
  Midi\MidiFileBuilder.cs
  Midi\MidiFileWriter.cs
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
  Midi\MidiEventBuilderTests.cs
  Midi\MidiFileBuilderTests.cs
  Midi\MidiFileWriterTests.cs
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
  Midi\MidiGenerationPipelineTests.cs
  Articulations\ArticulationPipelineTests.cs
  Support\SyntheticPipelineProfiles.cs
README.md
docs\articulation-mappings.md
docs\format-compatibility.md
docs\text-description-contract.md
prompts\report_5.md

Use small directly necessary typed exception/helper files only where justified. Reuse/extract the existing integration synthetic profile factories rather than copying the same setup into another test suite. Update only docs affected by the new writer. No new projects/packages/version upgrades or raw MIDI encoder.

Implementation requirements

Boundaries and API

  • Core remains independent of DryWetMIDI.
  • Generation translates existing MidiEventPlan/PlannedMidiEvent types into DryWetMIDI types. Use Melanchall.DryWetMidi exactly 8.0.3 for all MIDI construction, manipulation, serialization and read-back validation.
  • Build from a validated composition plus its event plan; preflight null/ invalid composition, role/extent disagreement, event/timing limits and unsupported event types before touching final output.
  • Prefer a small builder/writer API over unused interfaces, new configuration frameworks or generic result wrappers. Invalid arguments/unsupported format values must have actionable exceptions/diagnostics, never success defaults.
  • Do not modify profiles, mark synthetic data verified, bypass profile admission, or change the server's empty production MCP registry.

MIDI structure and metadata

  • Write SMF type 1 at 960 ticks per quarter note.
  • Add one conductor track and one named track for each selected role, with deterministic ordering (Lead, Bass, Drums) and no absent-role tracks.
  • Place tempo and meter metadata at tick zero in the conductor. Convert BPM to integer microseconds/quarter with documented nearest-integer, midpoint-away-from-zero rounding and the existing valid SMF tempo range. Preserve requested meter semantics; verify the pinned library API instead of guessing whether it accepts a denominator or its encoded exponent.
  • Metadata must remain correct with a shared lead-in. Do not shift tempo/meter to the first played note.
  • Preserve every planned pitch, velocity, channel, note-on, explicit note-off and CC number/value. Drums use the configured profile channel; the synthetic standard example uses zero-based 9 (MIDI channel 10). Do not remap channels.
  • Preserve stable same-tick priorities already established by the event plan: old note-offs, initial/release/reset controls, new state/keyswitch actions, musical note-ons. Do not let a high-level helper reorder controls/notes.
  • Add exactly one proper End-of-Track per track at the plan's global EndTick, preserving full declared bars/trailing rests, shared lead-in and later final release/reset pulses. No stuck musical or switch notes.
  • Use checked absolute-to-delta conversion; no negative/wrapped deltas. Validate the SMF four-byte VLQ maximum delta (0x0FFFFFFF) before serialization. Reject unrepresentable gaps explicitly, rather than writing nonstandard five-byte deltas, silently truncating or inserting undocumented musical data.
  • Investigate meter boundaries supported by DryWetMIDI 8.0.3, especially denominators 128 and 256 (Core accepts through 256). If the library cannot represent a valid Core meter, fail clearly and document/test that writer limitation; do not wrap a byte, change meter or narrow Core silently.
  • Read files back through DryWetMIDI; round-trip output must preserve exact semantic content and timing. Do not use a custom byte parser as a substitute.

Stream and filesystem output

  • Support writing to a caller-owned writable stream without closing it. A stream failure propagates; do not report success or hide partial-stream semantics. Document that caller-owned streams are not transactional.
  • Provide actual file output to an explicit absolute destination path, staged in a uniquely named request-owned temporary file in the same directory. Write/close the complete file, then move with no overwrite.
  • Existing files must never be truncated or replaced, including a destination collision occurring between preflight and move. Never rely only on File.Exists.
  • Validate parent/destination inputs with clear failures. Do not interpret paths as shell commands or add CLI/server transport features.
  • On failure/cancellation, clean up only this request's temporary files. Report any cleanup failure explicitly without losing the original error. Never scan/delete unrelated files or remove a pre-existing destination.
  • Propagate cancellation through event-building loops and before/after the library's synchronous serialization and before publication. Document any non-interruptible synchronous write boundary rather than promising immediate cancellation. Do not publish after an observed cancellation.
  • This is single-file staging only; multi-format transactional publication/ fallback orchestration remains Step 8.

Required tests

Unit tests

  1. Each planned event maps to the exact DryWetMIDI event type/values/channel; note-off is explicit, and unsupported types/ranges fail clearly.
  2. Type 1, 960 PPQ, conductor plus selected named tracks, tempo at 120 BPM = 500,000 microseconds/quarter, documented rounding at a nonintegral quotient, and correct 4/4 and non-4/4 metadata after serialization/read-back.
  3. Tempo lower/upper representability, invalid/nonfinite tempo, meter denominator boundary behavior, exact delta at/over 0x0FFFFFFF, checked overflow and mismatched composition/event plan.
  4. Same-tick ordering for transitions, keyswitch release, CC reset/new value, musical note-off/on, including serialization/read-back.
  5. Exact End-of-Track positions with trailing rests and final reset tails. Preserve source composition/event plan and deterministic repeated output.
  6. Writable borrowed stream remains open; invalid/read-only/failing streams fail explicitly. File creation, destination collision/no overwrite, staging cleanup, I/O failure and cancellation produce truthful outcomes.

Integration tests

  • Run real description -> composition -> synthetic profile/event planning -> writer -> actual temporary .mid file -> DryWetMIDI read-back.
  • Full documented example: four bars, 4/4, 120 BPM, 15,360 unshifted ticks; existing synthetic shared lead-in 240 yields musical end 15,600. Inspect all three role tracks and conductor.
  • Assert 32 played lead notes, four bass notes and 48 mapped drum hits, exact pitches/velocities/channels/ticks, switch pulses, CC state transitions, event ordering and complete note-off pairing. Distinguish control notes from musical counts; do not call synthetic numbers real Ample/SD3 mappings.
  • Include role subsets, a supported non-4/4 meter, long repeated patterns without drift, rests and controls extending past musical end.
  • Verify writing from an unrelated cwd using explicit paths, no-overwrite and failure/cancellation cleanup. Tests own isolated directories/resources.
  • Retain existing protocol, catalog and planning tests, including empty production mappings and no premature MCP generation tool.

Documentation and non-goals

Explain the new in-process builder/writer usage, exact output structure, borrowed-stream/file staging semantics, metadata rounding/limits, cancellation boundaries, and the distinction between tested MIDI formatting and still unverified real plugin mappings.

The combined type-1 Cubase arrangement is not automatically a Riffer-import file: the vendor manual requires a single track for Riffer import. Do not add or claim AGP/SDP serialization or a single-track Riffer export in this step. No audio, VST loading/scanning, cloud, HTTP, playback or containers.

Validation and acceptance

Use focused MIDI tests during development, then run:

dotnet build .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-restore
dotnet test .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-build
dotnet restore .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx --locked-mode

The installed SDK is C:\Program Files\dotnet\dotnet.exe; use a process-local PATH when necessary. Editor test discovery has been unavailable; CLI xUnit execution is the known fallback. Do not restore/install new packages merely to inspect the already-pinned MIDI API; use existing package XML/reflection.

Exit: real valid type-1 MIDI files generated/read back with complete mapped event semantics, safe single-file output, passing new and retained tests, and no false claim that production mappings/native writers are finished.

Mandatory worker report

When complete, write your end-of-step report to ./prompts/report_5.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step

Put the entire report in exactly one plain triple-backtick fence. Include files, API and actual pinned-library findings (tempo/meter/delta semantics), exact commands/exit codes/test counts, file/read-back evidence, skipped checks, limits and issues. Distinguish Step 5 format-writer readiness from real mapping, native-format and application acceptance. Stop for orchestrator report review; do not start Step 6 or another profile step.