Cubase-MCP-GAJ3T.MusicGen.R.../docs/formats/sdp.md

9.5 KiB
Raw Blame History

Superior Drummer 3 .sd3p template song codec

Implemented: bounded native SD3 3.4.4 parser, operator-template song writer, preflight and independent saved-file validator, wired to actual MCP generation. SD3 application load/save/reload and Cubase acceptance remain UNRUN. sdp is a request/API alias; actual native artifacts require .sd3p.

Evidence and ownership

Read-only local evidence establishes installed standalone ProductVersion 3.4.4, five native UTF-8 projects with PlugVersion 3.4.4, SAMPLER/HQ library SL-DFH, actual pad aliases and SongTrack/MidiLoop/MidiEvents fields. Safe provenance ID: LOCAL-SD3-344-DFH-PADS-20261019. No factory music, private project, manual or executable is bundled.

The installed “Operation Manual.pdf” is a one-page link sheet, not the complete manual. Its official manual link still requires login (checked 2026-10-20); no login was attempted. Core mapping facts therefore come from actual local native pad/alias declarations, not an invented public-manual citation or the GM table.

The default toontrack.sd3.3.4.4.core.v1 resource supports just:

Voice Native pad MIDI pitch
kick kickR 36
snare snareR 38
closed_hat hatsTP 42

Aliases must resolve uniquely to these actual defined pads in xpad 0 SL-DFH; the template's main library must match. Active sampler MIDI-learn overrides and incompatible input-channel filtering are rejected. Kit choice, mic/mixer state and all other non-song state stay operator-owned.

Python APIs

  • parse_sdp_project(raw: bytes) -> SdpProject: bounded structural parser; exposes exact non_song_bytes, parsed source note triples and SHA-256.
  • inspect_sdp_template(path: Path) -> SdpTemplateInfo: read-only filesystem, version, structure, pad-map and input-channel preflight.
  • check_sdp_capability(part, profile, *, template: Path | None = None).
  • require_sdp_capability(part, profile, *, template: Path | None = None).
  • write_sdp(path, plan, part, profile, *, template: Path | None = None) -> Path.
  • validate_sdp_file(path, plan, part, profile, *, template=None) -> SdpReadback. write_sd3p / validate_sd3p_file alias the same real codec.
  • preflight_sdp(plan, part, profile) runs event/precision checks without output IO. Writers additionally accept optional on_created(fstat) for exact service-owned partial-file identity tracking immediately after exclusive open.

The CLI exposes optional operator --sd3-template <local-project.sd3p>, threaded as sd3_template: Path | None through create_server/GenerationService. No tool-controlled arbitrary path is allowed. The service pins and checks source identity/size/mtime/hash; explicit template failures remain visible even when fallback is allowed. Missing optional template permits only drum native fallback, preserving available Riffer natives and one combined MIDI.

Check/require defensively revalidate mutable profiles and reject wrong parts. Without an explicitly supplied template they do no IO. Standard GM or mapping-only profiles return sdp_profile_not_supported. The supported target without optional template returns sdp_template_required, a named capability limitation. With a valid supplied template it returns available, reason sd3_3_4_4_template_song. Stored summary.native_available describes a real codec; the service's listing reports actual runtime readiness after template preflight, with version/library/subset and application-limit disclosures.

Explicitly supplied missing/unreadable paths are OUTPUT_IO_ERROR, not unavailability. Wrong suffix, corrupt UTF-8/state/events, unsupported version, ambiguous tracks or mismatched mapping are SERIALIZATION_ERROR. Invalid requests/profiles remain their existing named errors. Never silently fall back on these errors. There is no template scripting, subprocess or code evaluation.

Native representation and replacement

Native text has balanced, newline-delimited blocks. Quoted/escaped text, braces inside quotes, UTF-8, LF/CRLF and the observed single terminal NUL are handled without decoding/re-encoding opaque payload contents. Boundaries: 16 MiB per file, nesting 64, one million tokens, 100,000 note triples, 1–32 contiguous source tracks, numerical positions no greater than 16,384 quarter-note beats. Invalid/unbalanced/duplicate core state is rejected.

MidiEvents/Events contains repeating packed integer, start beat, end beat triples. Packing is status | (pitch << 8) | (velocity << 16) where status is 0x90 | channel. Read-back extracts all three bytes independently. Genuine 8332944 == 0x7f2690 decodes to channel 0, pitch 38, velocity 127. It does not encode release velocity. Only note-on messages with explicit positive duration are supported; CC, note-off and other status semantics are rejected, never interpreted as notes. Drumtracker/Track/trackstuff and tempoMap are unrelated tracker state, not the song MIDI.

The writer replaces every active top-level SongTrack record and the current-track selection with one original track, one clip, common zero start, requested end/tempo/meter, zero offset and neutral clip transforms. Original grooves, additional clips/tracks, source MIDI/database paths, humanize/KP transforms, velocities, loop/playhead settings inside the old song are removed. ClearTracksFirst, SAMPLER, mixer, tracker and every unrelated character remain byte-for-byte identical. No template is written or copied into fixtures.

The selected score part is independently recompiled and compared to all compiled note/switch events, including velocities and channels. Pre-roll/tails, nonzero note-off velocity, switch semantics, mismatched score/event plan, empty music and unrepresentable timing are errors before output creation. Explicit request cc_events remain valid MIDI; only an otherwise exact drum plan with valid controller routing returns sd3_native_controller_not_supported. No native controller-triple encoding has been established. This precise reason permits only the affected drum native to fall back, when allowed, while combined MIDI retains every controller point. Channel/note/role/release corruption is checked before this reason and cannot become successful fallback. Disabled fallback fails before staging; MIDI-only requests require no native preflight. Quarter-note timing must be an exact finite decimal with at most six fractional places; no rounding/truncation is performed (e.g. 1/3 and 1/128 are rejected). Absolute score starts are normalized to the common score-relative zero, not retained as clip offsets. Key metadata is neutral percussion metadata; pitched key semantics are not an SD3 drum feature claimed by this codec.

Only the supplied staged .sd3p path is exclusively created (xb), flushed, fsynced, bounded and independently read back. No parent/sibling/publication directory is created. Existing output/template paths are never overwritten. Saved validation checks structure, exact note multiset, boundaries, metadata, all supported neutral controls, absence of extra fields/references/tracks, and exact non-song bytes against the template. Template hash stability is checked during writes. Serialization/IO failure may leave the caller-owned failed staging file; it must not be published as successful.

Tests and local evidence

tests/fixtures/sd3/original-template.sd3p and original-score.json are newly authored minimal original fixtures, not stripped private/factory exports. The template contains original sentinel state and a deliberately replaceable original source clip; it is a parser fixture, not a playable redistributed kit. Unit tests cover packing boundaries, corruption, nesting/quoting, multiple tracks, precise timing, controls, state preservation and exclusive IO. Integration retains generated originals under .test-artifacts/native-sd3-evidence-v1. Installed-wheel acceptance generates its own minimal original template and actual .sd3p outside the checkout.

To additionally test an operator-local template, set RIFF_SD3_TEMPLATE to its absolute .sd3p path and run:

.\.venv\Scripts\python.exe -m pytest tests\integration\test_sd3p_files.py -q -s

The test asserts source inode/size/mtime/hash stability, replaces all source notes, compares exact non-song bytes and independently validates new original notes. Local outputs retain private kit state: keep them local and ignored, never publish them as distributable fixtures. Normal tests need no plugin, private template, network or application. Full results are in report_8_fix.md; actual native service/stdio/ installed-wheel evidence is in report_9_fix.md. Final persisted-wheel/default/alias/CC and genuine read-only generated evidence is in CURRENT report_10.md. Run tests\integration\test_native_service.py with the same environment variable for genuine read-only service acceptance, or without it for portable original fixtures.

Remaining readiness gates

CLI/template configuration, native service registration and target defaults are implemented and software-verified. Application behavior remains outside this task. SyncToHost, receiver mute/routing and all other non-song operator settings are preserved; host synchronization may override project tempo during playback. Actual SD3 open/inspect/play/save/close/reload must verify the saved notes, tempo/meter, dynamics, selected kit and mapping; Cubase routing/import needs a separate recorded version/configuration test. Structural native read-back is not an audible application-compatibility claim.