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

163 lines
9.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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](https://www.toontrack.com/manual/superior-drummer-3/)
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](../../prompts/report_8_fix.md); actual native service/stdio/
installed-wheel evidence is in [report_9_fix.md](../../prompts/report_9_fix.md).
Final persisted-wheel/default/alias/CC and genuine read-only generated evidence
is in [CURRENT report_10.md](../../prompts/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.