163 lines
9.5 KiB
Markdown
163 lines
9.5 KiB
Markdown
# 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.
|