# Step 5: Build and verify Standard MIDI file generation ## Objective and sequencing Read [the updated plan](plan.md), [the reviewed infrastructure and catalog report](report_4.md), 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 ```text 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: ```powershell 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.