dm2-music: name INST volume (inferred) + document SONG/INST field analysis #160

Merged
jqueuniet merged 0 commits from refs/pull/160/head into main 2026-07-03 16:06:53 +02:00
Owner

Follow-up to the SONG/INST decoders: interprets the field_NN placeholder
bytes as far as the fixture honestly allows, and tidies three deferred nits.
No byte-layout or behavior change — names and prose only.

What lands

  • Empirical field analysis in the docs (docs/formats/mac-resources.md).
    A new "Empirical field analysis" subsection records, per field, the observed
    value distribution and a confidence-tagged hypothesis, plus two structural
    findings: loop data lives in the 'snd ' sample header (not the 'INST'),
    and 'SONG' field_09 == 2 × field_0b across all 28 records.
  • One defensible rename: Inst.field_05 → Inst.volume (probable
    per-instrument level — always a multiple of 0x20, 0xC0 default). Applied
    in sync across the struct, formats/dm2_inst.ksy, and both doc tables, and
    guarded by a new volume % 0x20 == 0 assertion over all 136 records. The
    name is marked inferred everywhere it appears.
  • Everything else stays field_NN. The remaining fields are too
    low-confidence to name into a public API; they're documented as hypotheses
    instead.
  • Three cleanups: consolidate a mid-file use in sms.rs, comment the
    SONG arm in extract.rs, and add the <rfork> positional to a ROADMAP
    command.

Why so conservative

Profiling one port's data yields at most a moderate-confidence read for a
single field. Committing speculative names to a public struct is worse than
leaving them neutral, so this documents the analysis and renames only what's
defensible — deferring the rest until an external SoundMusicSys reference or an
engine disassembly raises confidence.

Test plan

  • cargo test --workspace --locked — green (round-trip stays byte-exact; new
    volume % 0x20 assertion holds for all 136 INST records).
  • cargo fmt --all -- --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo doc … -D warnings — all clean.
  • ksc compiles dm2_inst.ksy/dm2_song.ksy; all 136 INST parse with
    .volume present.
Follow-up to the SONG/INST decoders: interprets the `field_NN` placeholder bytes as far as the fixture honestly allows, and tidies three deferred nits. No byte-layout or behavior change — names and prose only. ## What lands - **Empirical field analysis in the docs** (`docs/formats/mac-resources.md`). A new "Empirical field analysis" subsection records, per field, the observed value distribution and a confidence-tagged hypothesis, plus two structural findings: loop data lives in the `'snd '` sample header (not the `'INST'`), and `'SONG'` `field_09 == 2 × field_0b` across all 28 records. - **One defensible rename:** `Inst.field_05` → `Inst.volume` (probable per-instrument level — always a multiple of `0x20`, `0xC0` default). Applied in sync across the struct, `formats/dm2_inst.ksy`, and both doc tables, and guarded by a new `volume % 0x20 == 0` assertion over all 136 records. The name is marked **inferred** everywhere it appears. - **Everything else stays `field_NN`.** The remaining fields are too low-confidence to name into a public API; they're documented as hypotheses instead. - **Three cleanups:** consolidate a mid-file `use` in `sms.rs`, comment the SONG arm in `extract.rs`, and add the `<rfork>` positional to a ROADMAP command. ## Why so conservative Profiling one port's data yields at most a moderate-confidence read for a single field. Committing speculative names to a public struct is worse than leaving them neutral, so this documents the analysis and renames only what's defensible — deferring the rest until an external SoundMusicSys reference or an engine disassembly raises confidence. ## Test plan - `cargo test --workspace --locked` — green (round-trip stays byte-exact; new `volume % 0x20` assertion holds for all 136 INST records). - `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets --locked -- -D warnings`, `cargo doc … -D warnings` — all clean. - `ksc` compiles `dm2_inst.ksy`/`dm2_song.ksy`; all 136 INST parse with `.volume` present.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools!160
No description provided.