7.9 KiB
Step 4: Deterministic MIDI timing, scheduling, and file writer
Objective and prerequisites
Implement only Step 4 of the approved plan. Steps 1-3 are accepted after persistent report review, source inspection, and independent test runs.
Read the approved plan, reports 1-3, current schemas/errors, and installed Mido and MIDIUtil APIs. Implement real Standard MIDI serialization from explicit controlled EventPlan structures. Do not implement text parsing/composition, production instrument maps, native writers, service wiring, or later prompts. Do not delegate or commit.
Owned files
- Create
src/riff_groove_builder/midi.py. - Create
tests/unit/test_midi.py. - Create
tests/integration/test_midi_files.py. - Update
docs/architecture.mdandREADME.mdwith implemented timing/writer behavior and focused verification commands. - Refine
schemas.pyand its directly relevant tests only if a concrete representation issue prevents a correct writer; preserve the MCP contract and explain any tightly coupled change. - Write
prompts/report_4.md.
Generate small controlled test MIDI files in temporary workspaces. Do not add licensed fixtures or check in build/test output.
Implementation details
- Mido is the only production SMF writer. Use integer absolute event ticks and the authoritative EventPlan model, then convert to integer nonnegative delta ticks exactly once after stable sorting.
- Provide small reusable helpers for exact rational beats-to-ticks and bar-duration math where needed. Default PPQ is 960. Reject off-grid fractions rather than accumulating float error or silently rounding.
- Validate MIDI-specific encodability: legal positive non-SMPTE PPQ, finite representable tempo, valid event/tick/delta ranges, supported event payloads, the event budget, and shared timeline. Do not let a low-level struct error masquerade as success or produce corrupt output.
- Write synchronous SMF type 1 with one conductor track followed by selected part tracks in resolved order. Add meaningful track names, conductor tempo and time signature at tick zero, and exactly one end-of-track per track at the shared event-plan end.
- Tempo is quarter-note BPM, independent of the meter denominator. Compare serialized integer microseconds-per-quarter against the correctly rounded target, including fractional BPM tests.
- Preserve note, keyswitch, and CC events in the part track. Do not invent programs, GM drum mappings, real vendor switches, or keyswitch lead times. Step 5 supplies profile-specific compiled controls.
- Respect EventPlan ordering_key (tick, priority, sequence). It is the compiler's explicit causal ordering; do not sort solely by note number or blindly rewrite valid control priorities. At boundaries, verify off/on retrigger ordering actually gives an unambiguous event sequence.
- Validate note pairing by channel/note and distinguish musical and keyswitch roles for diagnostics. Reject orphan releases and dangling notes. Define/test an explicit safe rule for overlapping same-channel/same-pitch note-ons, including collisions between switch and musical notes; do not accidentally release a different active voice or claim ambiguous semantics.
- Require part/channel isolation according to the plan without assuming a default drum channel or hard-coding a real plugin mapping. Distinct parts may not share a stateful MIDI channel. Do not reject polyphonic different pitches merely because they share their own part's channel.
- Preserve the common pre-roll, musical span, and shared control-release tail. No negative events, part-specific shifts, or musical note-ons at/after the musical end. Native alignment remains a later adapter requirement.
- Serialize and validate in memory where useful, then write to the requested file and read the saved file back with Mido. Validate the actual saved header/type/PPQ, conductor data, track names/order, event sequence, channels/payloads, pairing, and shared end. Round-trip validation must compare against expected content, not merely prove that Mido can open a file.
- Expose a small typed writer/validator API ready for the future service. The writer acts only on its supplied file path; output-root confinement, directory publication, requested-format policy, and MCP calls remain Step 9. Do not overwrite an existing file silently. Handle path/IO and serialization failures explicitly with the repository's named errors and safe reason details. Clean up only a newly created file owned by this request on failure.
- Use narrow exception handling for actual expected library/IO failures, not broad silent catches, invalid-input defaults, or MIDI-shaped fallback on corruption. Preserve a useful explicit failure for callers.
- Do not call this a functioning text-to-music server or instrument-compatible file generator yet. The stdio tool remains the reviewed unfinished handler.
Required unit tests
- Exact beat/bar tick math for 4/4, 3/4, 6/8, and an odd meter.
- Straight and triplet subdivisions, invalid fractions, illegal PPQ/delta ranges, strict values, nonzero score starts, and event-budget boundaries as applicable.
- Stable ordering with unsorted input, equal-tick controls, off/on retriggers, and deliberate priority/sequence ordering.
- Musical/keyswitch note pairing, dangling/orphan events, same-pitch overlap policy, and role collisions.
- Valid polyphony within a part and invalid channel sharing between parts.
- Conductor tempo/meter and fractional BPM, part names/order, shared EOT.
- Common pre-roll, exact musical duration, release tails, and empty part tracks.
- No silent overwrite; IO/serialization/read-back mismatch failures surface explicitly and leave no newly published corrupt file.
Required integration tests
- Construct a synthetic three-part Score/EventPlan with musical notes, keyswitches, CCs, pre-roll, and a release tail; write to disk and read back, asserting exact absolute events, durations, channels, and metadata.
- Build an independent MIDIUtil reference for controlled equivalent music and compare normalized musical/control events against production output using Mido. Account explicitly for library-specific conductor layout and harmless end-of-track conventions; do not compare entire byte streams.
- Write/reload cases in more than one meter and fractional tempo.
- Detect a deliberately corrupt/truncated file and a structurally readable file whose content differs from the expected EventPlan.
- Verify deterministic bytes or documented deterministic semantic output for repeated identical input.
- Existing schema/import/protocol tests remain passing.
All mappings used here must be clearly synthetic and test-local. No application compatibility is established by these tests.
Validation and acceptance
Run focused new MIDI tests, directly affected contract regressions, Ruff
lint/format, strict mypy, and relevant existing smoke/protocol tests. The
verified .venv\Scripts\python.exe -m pytest CLI fallback is acceptable.
Escalate to the complete current suite if changes touch shared schemas.
Acceptance: valid deterministic type 1 MIDI from explicit event plans, exact timing and ordering, independent reference/read-back evidence, honest failures, and no regressions. Production mapping/native gates remain open.
Required report
When complete, write your end-of-step report to ./prompts/report_4.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 inside exactly one plain triple-backtick fence. Include owned files/API decisions, exact commands/pass-fail-skip results, MIDIUtil comparison evidence, overlap/channel policies, temporary-file cleanup, and unresolved mapping/native evidence. State whether Step 5 can start and whether its real production-mapping acceptance gate is currently satisfiable.