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

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.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.