138 lines
7.9 KiB
Markdown
138 lines
7.9 KiB
Markdown
# 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.md` and `README.md` with implemented timing/writer
|
|
behavior and focused verification commands.
|
|
- Refine `schemas.py` and 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
|
|
|
|
1. 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.
|
|
2. 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.
|
|
3. 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.
|
|
4. 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.
|
|
5. 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.
|
|
6. 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.
|
|
7. 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.
|
|
8. 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.
|
|
9. 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.
|
|
10. 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.
|
|
11. 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.
|
|
12. 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.
|
|
13. 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.
|
|
14. 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.
|