feat(packer): encode self-contained mixed-codec audio banks
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

Pack and validate SoundBanks and MusicBanks with PCM16 and IMA ADPCM samples, instruments and native sequences. Keep the existing Studio asset creation catalog limited to supported UI families.
This commit is contained in:
2026-11-20 22:15:24 +00:00
parent 666a36d133
commit 304321a6e4
29 changed files with 704 additions and 119 deletions
@@ -0,0 +1,61 @@
# Audio bank packing
Domain: packer. Function: normative.
The existing packer emits SoundBank (`sound_bank`, `SOUND/bank_v1`) and
MusicBank (`music_bank`, `MUSIC/bank_v1`) assets. Runtime authority is
`runtime/docs/specs/runtime/05a-audio-bank-format.md` in the enclosing workspace.
There are 16 maximum resident slots for each audio type. Outer codec is NONE;
sample codecs are PCM16_LE or IMA_ADPCM_WAV4, independently selected.
An audio asset contains one selected JSON composition manifest. SoundBank
manifests list samples; MusicBank manifests additionally declare song timing,
instrument zones and events. WAV source paths are relative to the asset root;
reject absolute/path-escaping and missing inputs. Inputs may be mono or stereo;
preserve channel count. Import WAV PCM16 little endian and normalize permitted
production inputs explicitly; runtime receives bank bytes, never a WAV container.
The manifest declares samples in stable index order, each with file, codec,
optional loop_start/loop_end in decoded frames, and playback defaults. MusicBank
adds ppq=960, tempo_us_per_quarter, duration_ticks, optional loop_start_tick,
track_count, instruments and events. Instrument/event field names match the
runtime table, except ADSR authoring uses attack_ms, decay_ms and release_ms
(converted to unsigned microseconds with nearest rounding); absent defaults are
deterministic. WAV PCM8/16/24/32 and IEEE float32 are converted to PCM16, with
finite-value validation and saturation; no runtime WAV decoder is needed. Events retain authored order
within equal ticks. The bank is complete; no reference resolves to another bank.
Packing constructs SBNK/MBNK version 1 tables and payloads exactly as specified
by runtime, with checked lengths, reserved zero bytes and deterministic output.
IMA encoding uses complete blocks, a first-sample/index header per channel,
low-nibble-first codes and four-byte stereo channel groups. The default block
size is 256 bytes per channel. Report encoded payload and canonical decoded size
separately. Validate ranges, references, zones, loops, timing/density and codec
metadata before publishing the artifact. An invalid asset produces a diagnostic,
not a partial bank or a silently substituted waveform.
Sound/MusicBank packing is implemented in the existing API/v1 modules and
workspace artifact builder. It does not add an audio editor, tracker, preview,
compiler feature or new UI/import integration. Existing glyph/palette/scene
formats remain outside this change. Conformance fixtures must be consumed by the
Rust decoder, including PCM-only, IMA-only, mixed, stereo, malformed and complete
music banks. Encoder choices are explicit and source WAVs are not runtime assets.
The packing snapshot includes the selected JSON and every referenced WAV, with
individual fingerprints. A changed WAV invalidates its source fingerprint even
when the JSON is unchanged. Packing reads these frozen bytes, validates the bank
and emits the same deterministic payload. Runtime metadata contains version=1;
tooling metadata reports pcm_bytes, cartridge_bytes, decoded_size and ratio.
Example asset.json selection:
```json
{"schema_version":1,"asset_uuid":"stage-01","name":"stage_01",
"type":"music_bank","output":{"format":"MUSIC/bank_v1","codec":"NONE"},
"artifacts":[{"file":"song.json","index":0}],"preload":{"enabled":false}}
```
A complete composition example with PCM/IMA mono/stereo WAV sources and exact
binary fixtures lives in the existing packer v1 test resources under
fixtures/audio. The workspace packer emits the regular assets.pa envelope with
SOUNDS or MUSIC entries; preload slots are counted independently by bank type.