Cubase-MCP-GAJ3T.MusicGen.R.../prompts/step_4.md

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.