198 lines
10 KiB
Markdown
198 lines
10 KiB
Markdown
# 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.
|