Music payload (BGM/*.stx → PCM): converter-step spec
Completes “Music”. Checked with a struct block walker on all 127 files (H for the layout; the result has not been listened to yet). Container credit as in “Music”.
- Block 0 (header block): its
data_offsetis 0x800 andbytes_per_channel0: no audio. Channel records of 0x40 bytes from 0x20:u32 sample_rate,u8 volume(0x7F on music; lower on the tutorial voice files), then send bytes. Channel 0 has 0x7F in send 0, channel 1 in send 1: channel 0 = left, channel 1 = right. - Data blocks 1..block_count
− 1: header 0x20 bytes,
data_offset0x20,next_block= index + 1.bytes_per_channelis 1008 (0x3F0) in a full block and smaller in a short one. - Payload: 16-bit signed little-endian
PCM, planar inside each block. Channel
c’s samples start at 0x20 + c × 0x3F0 — a fixed
stride, also in short blocks (checked by sample
continuity across block borders; reading short
blocks as packed breaks it) — and
bytes_per_channelbytes of each region are valid. 504 samples per channel per full block. - Sample rate: as stored: 44100, or 44099 in the 35 looping files. Play both as 44100.
- Loop:
loop_start/loop_endare repeated in every block. 0xFFFF / 0xFFFF = plays once (92 files). Otherwiseloop_startis the index of the data block where the loop begins andloop_endequalsblock_count(the loop runs to the end) in all 35 files. Loop start in samples = Σ bytes_per_channel / 2 over blocks 1..loop_start − 1. In 34 of the 35 files the block before the loop start is a short one, i.e. the encoder cut the block so the loop begins on a block border. The last block is short too. - Worked example, track 01: 13,302 blocks; short blocks 963 (540 bytes per channel) and 13,301 (396); 6,703,164 samples = 152.0 s; loop start sample 485,118 (11.0 s); loop end = end of file.
.w10files are the same container (shorter variants of the tutorial voice files).
Implementation notes for the rebuild
- Converter step (runs next to the dump;
output is the player’s own data, never in a
repo): walk the blocks, append
bytes_per_channelbytes of each channel region, interleave to stereo, write WAV or Ogg Vorbis with loop start = the sample count above and loop end = end. Struct reader for the 0x20 header and the 0x40 channel record, no offsets. - Godot:
AudioStreamWAVloop_begin /AudioStreamOggVorbisloop_offset (seconds = samples / the track’s rate; see “Compressed set for the Deck” below). - Track volume: channel record volume / 127, times the music volume option (“Music”).
- First check to make when built: listen to track 01 across its loop point. (Audio run: built, not yet listened to by ear. A continuity check, the sample step at each candidate seam within ±7 blocks of the decoded one, had the decoded block as the smoothest candidate in 18 of the 35 looping files; chance would give about 1 in 7.)
Compressed
set for the Deck: Ogg Vorbis
(pdmusic_ogg.py) (musicogg run,
11-13)
- Post-step on pdmusic.py’s output:
pdmusic_ogg.py <music in> <music out> [--quality 6] [--encoder oggenc|ffmpeg] [--drop-wav]. Each track entry keeps every field and gets"file": "NN.ogg","codec": "ogg"(nocodec= WAV); the index top level gets"encoder": {"tool", "quality"}. Format and version staypd-music1. - Sample-exact: Vorbis keeps the sample rate
(44099 / 44100 as decoded) and the last page’s
granule position trims the tail, so the decoded
length equals the WAV’s. Checked on all 39
tracks (decoded frame count = index
samples, 0 difference each). The loop numbers stay in samples; PdMusic setsloop_offset = loop_start / rate. - Size: 39 tracks, 176 MB at quality 6 (the WAV set: 1.3 GB).
- Godot’s Ogg loop lands on the same seam: track 1 mixed through the loop point from both formats lines up at lag 0 before and after the seam (tests/test_music_ogg.gd; a loop offset 8 samples off shows as lag -8).