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/PlannedMidiEventtypes into DryWetMIDI types. UseMelanchall.DryWetMidiexactly 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
- Each planned event maps to the exact DryWetMIDI event type/values/channel; note-off is explicit, and unsupported types/ranges fail clearly.
- 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.
- Tempo lower/upper representability, invalid/nonfinite tempo, meter denominator boundary behavior, exact delta at/over 0x0FFFFFFF, checked overflow and mismatched composition/event plan.
- Same-tick ordering for transitions, keyswitch release, CC reset/new value, musical note-off/on, including serialization/read-back.
- Exact End-of-Track positions with trailing rests and final reset tails. Preserve source composition/event plan and deterministic repeated output.
- 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
.midfile -> 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.