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.
62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
# 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.
|