drwily/Dragon-s-Lair-X68k
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Put sound in the packed container, and find the padding is a rate error

Browse Source 
ROADMAP P6b, FINDINGS 67.  DLXP2: a 64-byte header and then groups -- one
audio lump of A sectors, then F records -- so record i is at
off_frm + i*rec + (i//F)*A*512 and lump k at off_aud + k*(F*rec + A*512).
Still no index and still none needed, which is the packed branch's whole
claim surviving the one change that could have ended it.  The player carries
the third term in six instructions once a frame and zero parsing, and 120 of
120 records are still pixel-exact off a real MB89352 volume with the
interleave in, against a silent control that says no picture byte moved.

The finding is what 65.3 called padding.  A lump is 7,168 B of SPACE; eleven
frames of audio is 7,161.4583... B, so the payload alternates 7,161 and
7,162 and the rest is zero.  A player that fed the chip the whole lump --
which is what "14 sectors every 11 frames" invites -- runs 0.09% fast, and
that is not waste, it is drift: 0.84 ms a group, 1.25 s of lip-sync over the
game's 22.8 minutes.  What a player carries is one accumulator,
acc += 11*15625; n = acc//24; acc %= 24, which is clock.i's shape for
clock.i's reason and the third time this tree has met the pattern.

The four ADPCM axes ride in the header as fields rather than a version
number, and the gate flips each one to prove they earn it: nibble order
-31.99 dB, delta formula -24.86, clamp 0.00, accumulator -0.49.  Nothing
parses a packed container, so the gate partitions the whole file -- 131
spans, no overlap, no gap -- and asserts what a cadence-blind player would
read: exactly records 11..119 wrong, and frames 0..10 identical either way,
which is how an off-by-one like that survives a rig that checks frame 0.

Wire 582.0 + 7.64 = 589.6 KB/s, 65.3's prediction to the tenth.

Green light ALL GREEN before (tmp/check_s35_start.log) and after
(tmp/check_s35_end.log), with the new stage in it.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
This commit is contained in:
prosolis
2026-08-25 11:22:38 -07:00
parent 6dd3fb3597
commit e3778f62b0
13 changed files with 1001 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/encoder/dlxp.py
+259 -14
View File
@@ -35,19 +35,65 @@ The layout, all of it fixed, all of it verified as a picture in FINDINGS 47.2:
chaining from one start (FINDINGS 62). A container that carried the stride
would be 4x the size and would say nothing extra.
header, 32 bytes, big-endian, then zero pad to the first sector:
header, 64 bytes, big-endian, then zero pad to the first sector:
0 'DLXP'
4 u16 version (1)
4 u16 version (2)
6 u16 flags bit 0: a per-frame palette is present
bit 1: the palette is at the END of the record
bit 2: an audio stream is interleaved (DLXP2)
8 u16 width, u16 height
12 u16 fps, u16 nframes
16 u32 record bytes fixed, and a whole number of 512 B sectors
20 u32 palette bytes 512 (256 GRB555+I words), or 0
24 u32 picture bytes 49,152
28 u32 frames offset 512 B, i.e. sector 1
28 u32 frames offset offset of RECORD 0, lump 0 already skipped
-- DLXP2 adds, and every field is zero in a silent container:
32 u32 audio offset offset of LUMP 0, 512 B, i.e. sector 1
36 u32 audio sample Hz 15,625 -- the chip's, not the disc's
40 u32 audio bytes the ADPCM payload, padding NOT counted
44 u16 cadence F frames between one lump and the next
46 u16 cadence A whole sectors in a lump
48 u16 audio format bit 0: LOW nibble first. bit 1: the OKI
datasheet's per-term delta ('terms')
50 u16 audio clamp bits where the accumulator saturates, 10 or 12
52 i16 audio init the accumulator at PLAY, -2 on this chip
54 u16 reserved (0)
56 u32 reserved (0)
60 u32 reserved (0)
then nframes FIXED-SIZE records, each 49,664 B = 97 sectors EXACTLY.
then, from sector 1, GROUPS: one audio lump of A sectors, then F records.
A record is 49,664 B = 97 sectors EXACTLY and a lump is A*512 B EXACTLY, so
record i is at off_frm + i*rec_bytes + (i//F)*A*512
lump k is at off_aud + k*(F*rec_bytes + A*512)
-- still arithmetic, still no index, still nothing walked.
WHY AUDIO IS A CADENCE AND NOT A FIELD IN THE RECORD (FINDINGS 65.3). 15,625
samples a second, two to a byte, is 651.0416... B per 12 fps slot, and the dots
are the whole problem: put slot i's audio in record i and records become
VARIABLE LENGTH, which needs an index, which ends the format. A fixed cadence
of F frames per A sectors keeps `LBA(i)` arithmetic and pays instead in padding,
and the padding is a rational-approximation problem whose answer is not the
obvious cadence: F=1 wastes 57.3% of every audio sector and F=11, A=14 wastes
0.09%.
AND THE PADDING IS NOT WHERE THE BYTES ARE (FINDINGS 67). A lump is A*512 B of
SPACE and it does NOT carry A*512 B of audio: F frames need F*15625/24 B, which
is 7,161.4583... at F=11, so a lump's PAYLOAD alternates 7,161 and 7,162 by the
same remainder arithmetic FINDINGS 54's frame clock carries, and the rest of the
sector is zero. A player that fed the chip the whole lump would be handing it
6.54 B a group it should not have -- 0.09% too much audio, which is not waste,
it is DRIFT: 0.83 ms a group, 1.2 s of lip-sync over the game's 22 minutes. So
`lump_bytes(k)` below is the format, not a convenience, and a player computes it
with one accumulator: `acc += F*aud_hz; n = acc // (2*fps); acc %= 2*fps`.
THE FOUR ADPCM AXES ARE IN THE HEADER BECAUSE GETTING ONE WRONG COSTS 25 dB
(FINDINGS 66). Nibble order, delta formula, clamp width and the accumulator's
value at PLAY are properties of the DECODER, and a container encoded for one
decoder and played on another comes out with the noise louder than the signal.
They are four fields rather than a version number so that a mismatch is legible
in a hexdump rather than inferred from a container's age.
THERE IS NO RECORD INDEX AND NO LENGTH WORD, and that is the difference DLX4's
index was invented for (49.3): a codec record's length is content-dependent, so
@@ -68,12 +114,78 @@ import struct
import numpy as np
MAGIC = b"DLXP"
VERSION = 1
VERSION = 2
SECTOR = 512 # same rule and the same reason as dlx.SECTOR
PAL_BYTES = 512 # 256 entries, one GRB555+I word each
HDR_BYTES = 32
HDR_BYTES = 64
FLAG_PALETTE = 1 << 0
FLAG_PALETTE_LAST = 1 << 1
FLAG_AUDIO = 1 << 2
# The two ADPCM axes that are booleans. The other two -- the clamp width and
# the accumulator at PLAY -- are numbers and get their own fields, because
# encoding them as flags would mean this file deciding which values are legal.
AFMT_ORDER_LOW = 1 << 0
AFMT_VARIANT_TERMS = 1 << 1
# The default cadence, and it is a MEASUREMENT rather than a taste (FINDINGS
# 65.3): the sweep's floor is F=81 and costs 91,136 B more of player RAM for the
# last 0.09 of a point of padding, on a machine where two record buffers already
# want 99,328 B.
CADENCE_F = 11
def audio_format(variant, order, bits, init):
"""adpcm.py's four axes -> the three header fields that carry them.
This file does not import adpcm.py and must not: a container format that
depended on an encoder would be a format that could not be read without one.
What it carries is the DESCRIPTION, and `tools/analysis/34_packed_audio.py`
is what checks the description against the encoder that wrote the bytes.
"""
if variant not in ("shift", "terms") or order not in ("high", "low"):
raise ValueError(f"unknown ADPCM decoder ({variant!r}, {order!r})")
fmt = ((AFMT_ORDER_LOW if order == "low" else 0)
| (AFMT_VARIANT_TERMS if variant == "terms" else 0))
return fmt, int(bits), int(init)
def audio_decoder(fmt, bits, init):
"""The inverse: what a player, or a gate, has to run to hear the bytes."""
return dict(variant="terms" if fmt & AFMT_VARIANT_TERMS else "shift",
order="low" if fmt & AFMT_ORDER_LOW else "high",
bits=int(bits), init=int(init))
def cadence(fps, hz, F=CADENCE_F):
"""(F, A): F frames of audio rounded UP to whole sectors.
A*512 must cover F frames or the chip runs dry, so A is a ceiling and the
excess is padding the wire pays for and nothing plays. Integer arithmetic
throughout: the whole point of 65.3 is that this ratio has a remainder, and
a float here would hide the case where it does not.
"""
num, den = F * hz, 2 * fps # bytes per group = num/den
return F, -(-num // (den * SECTOR))
def lump_bytes(k, F, fps, hz, total=None):
"""The PAYLOAD of lump k -- what is handed to the chip, padding excluded.
Exact, and exactness is the finding (FINDINGS 67): floor((k+1)*F*hz/(2*fps))
- floor(k*F*hz/(2*fps)) alternates 7,161 and 7,162 at F=11, and a player
that fed the chip the whole A*512 B lump instead would run 0.09% fast --
1.2 s of lip-sync over 22 minutes.
"""
den = 2 * fps
n = ((k + 1) * F * hz) // den - (k * F * hz) // den
if total is not None: # the last lump is short, not padded
n = max(0, min(n, total - (k * F * hz) // den))
return n
def n_lumps(nframes, F):
return -(-nframes // F)
def pack_picture(idx):
@@ -111,23 +223,73 @@ def record_bytes(W, H, palette=True):
return n
def write(path, W, H, fps, frames, palette_last=False):
"""`frames` is a sequence of (palette_words_bytes | None, picture_bytes)."""
def write(path, W, H, fps, frames, palette_last=False, audio=None):
"""`frames` is a sequence of (palette_words_bytes | None, picture_bytes).
`audio`, when given, is a dict: `data` the packed ADPCM bytes, `hz` the
chip's sample rate, `variant`/`order`/`bits`/`init` the four axes FINDINGS
66 measured, and optionally `F`. The stream is CUT UP HERE and nowhere
else, by `lump_bytes`, for the same reason `pack_picture` is the one place
the interleave lives: a second copy of a layout rule is a place the layout
can drift.
"""
frames = list(frames)
pal_b = PAL_BYTES if frames and frames[0][0] is not None else 0
pic_b = W * H
rec_b = record_bytes(W, H, palette=bool(pal_b))
flags = ((FLAG_PALETTE if pal_b else 0)
| (FLAG_PALETTE_LAST if palette_last and pal_b else 0))
| (FLAG_PALETTE_LAST if palette_last and pal_b else 0)
| (FLAG_AUDIO if audio else 0))
if audio:
hz = int(audio["hz"])
F, A = cadence(fps, hz, audio.get("F", CADENCE_F))
au = audio["data"]
fmt, bits, init = audio_format(audio["variant"], audio["order"],
audio["bits"], audio["init"])
lumps = []
got = 0
for k in range(n_lumps(len(frames), F)):
n = lump_bytes(k, F, fps, hz, total=len(au))
if n > A * SECTOR:
raise ValueError(f"lump {k} needs {n} B and the cadence gives "
f"{A*SECTOR}")
lumps.append(au[got:got + n].ljust(A * SECTOR, b"\0"))
got += n
# A container whose audio runs out before its pictures do is a container
# that goes silent part way through, which is exactly the failure a
# writer should refuse rather than a player discover.
if got < len(au):
raise ValueError(f"{len(au)-got} B of audio have no lump to ride in "
f"-- {len(frames)} frames hold {got} B")
if got < min(len(au), (len(frames) * hz) // (2 * fps)):
raise ValueError(f"the audio stream is short: {len(au)} B for "
f"{len(frames)} frames at {fps} fps")
off_aud, off_frm = SECTOR, SECTOR + A * SECTOR
atail = struct.pack(">IIIHHHHhHII", off_aud, hz, len(au), F, A,
fmt, bits, init, 0, 0, 0)
else:
F = A = 0
lumps = []
off_aud, off_frm = 0, SECTOR
atail = struct.pack(">IIIHHHHhHII", 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
hdr = (MAGIC + struct.pack(">HHHHHH", VERSION, flags, W, H, fps, len(frames))
+ struct.pack(">III", rec_b, pal_b, pic_b)
+ struct.pack(">I", SECTOR))
+ struct.pack(">IIII", rec_b, pal_b, pic_b, off_frm) + atail)
assert len(hdr) == HDR_BYTES, len(hdr)
with open(path, "wb") as fh:
fh.write(hdr + b"\0" * (SECTOR - HDR_BYTES))
for i, (pw, pic) in enumerate(frames):
if len(pic) != pic_b or (pal_b and len(pw) != pal_b):
raise ValueError(f"frame {i}: record parts are the wrong size")
# The lump goes BEFORE the group it feeds, which is the one place
# this format makes a choice audio forced on it. 65.3's formula put
# it after; a stream is read forwards, so bytes that arrive after
# the slot they belong to are bytes a player has to have fetched
# early anyway. Placing it first makes the fetch order the play
# order and costs one lump of offset in the arithmetic.
if audio and i % F == 0:
fh.write(lumps[i // F])
rec = pic if not pal_b else (pic + pw if palette_last else pw + pic)
fh.write(rec)
return rec_b
@@ -154,6 +316,32 @@ class DLXP:
raise ValueError(f"{path}: DLXP version {self.version}")
self.has_palette = bool(self.flags & FLAG_PALETTE)
self.palette_last = bool(self.flags & FLAG_PALETTE_LAST)
self.has_audio = bool(self.flags & FLAG_AUDIO)
(self.off_aud, self.aud_hz, self.aud_bytes, self.cad_f, self.cad_a,
self.aud_fmt, self.aud_bits, self.aud_init,
_r0, _r1, _r2) = struct.unpack(">IIIHHHHhHII", b[32:64])
if not self.has_audio:
if any((self.off_aud, self.aud_hz, self.aud_bytes, self.cad_f,
self.cad_a, self.aud_fmt, self.aud_bits, self.aud_init)):
raise ValueError(f"{path}: silent container with audio fields set")
else:
if (self.cad_f, self.cad_a) != cadence(self.fps, self.aud_hz,
self.cad_f):
raise ValueError(f"{path}: cadence F={self.cad_f} A={self.cad_a} "
f"does not cover {self.cad_f} frames of "
f"{self.aud_hz} Hz audio at {self.fps} fps")
if self.off_aud != SECTOR or self.off_aud % SECTOR:
raise ValueError(f"{path}: audio starts at {self.off_aud}")
if self.aud_bits not in (10, 12):
raise ValueError(f"{path}: ADPCM clamp is {self.aud_bits} bits")
# The stream has to fill the groups it is cut into, or the last
# frames of the scene play in silence and nothing says so.
want = sum(lump_bytes(k, self.cad_f, self.fps, self.aud_hz)
for k in range(n_lumps(self.nframes, self.cad_f)))
if not (want - self.cad_f * self.aud_hz // (2 * self.fps)
<= self.aud_bytes <= want):
raise ValueError(f"{path}: {self.aud_bytes} B of audio for "
f"{self.nframes} frames, geometry wants {want}")
if self.pic_bytes != self.W * self.H:
raise ValueError(f"{path}: picture is {self.pic_bytes} B for "
f"{self.W}x{self.H} -- the packed layout is 1.0 B/px")
@@ -167,12 +355,56 @@ class DLXP:
if self.off_frm % SECTOR or self.rec_bytes % SECTOR:
raise ValueError(f"{path}: not sector-aligned -- stream at "
f"{self.off_frm}, record {self.rec_bytes}")
want = self.off_frm + self.nframes * self.rec_bytes
if self.off_frm != (SECTOR + (self.cad_a * SECTOR if self.has_audio
else 0)):
raise ValueError(f"{path}: record 0 is at {self.off_frm}, and a "
f"{self.cad_a}-sector lump comes before it")
want = (self.off_frm + self.nframes * self.rec_bytes
+ (n_lumps(self.nframes, self.cad_f) - 1) * self.cad_a * SECTOR
if self.has_audio else
self.off_frm + self.nframes * self.rec_bytes)
if len(b) != want:
raise ValueError(f"{path}: {len(b)} bytes, geometry says {want}")
def record(self, i):
def frame_off(self, i):
"""The arithmetic, and the ONE place it is written on the host side --
src/player/packed.s is the other, in six instructions, and
tools/analysis/34_packed_audio.py is what makes the two agree."""
if not (0 <= i < self.nframes):
raise IndexError(i)
o = self.off_frm + i * self.rec_bytes
return o + (i // self.cad_f) * self.cad_a * SECTOR if self.has_audio else o
def lump_off(self, k):
if not self.has_audio or not (0 <= k < self.n_lumps):
raise IndexError(k)
return self.off_aud + k * (self.cad_f * self.rec_bytes
+ self.cad_a * SECTOR)
@property
def n_lumps(self):
return n_lumps(self.nframes, self.cad_f) if self.has_audio else 0
def lump(self, k, padding=False):
"""Lump k's PAYLOAD -- what the chip is fed. `padding=True` returns the
whole A*512 B sector run instead, which is what the disc moves and what
a player must NOT hand to the chip (FINDINGS 67)."""
o = self.lump_off(k)
if padding:
return self.raw[o:o + self.cad_a * SECTOR]
n = lump_bytes(k, self.cad_f, self.fps, self.aud_hz, total=self.aud_bytes)
return self.raw[o:o + n]
def audio(self):
"""The whole ADPCM stream, reassembled from its lumps."""
return b"".join(self.lump(k) for k in range(self.n_lumps))
def decoder(self):
"""The four axes the bytes were encoded for, as adpcm.decode's kwargs."""
return audio_decoder(self.aud_fmt, self.aud_bits, self.aud_init)
def record(self, i):
o = self.frame_off(i)
return self.raw[o:o + self.rec_bytes]
def _split(self, i):
@@ -214,5 +446,18 @@ class DLXP:
"""(H,W,3) uint8 -- the frame as the display produces it."""
return self.palette_rgb(i)[self.indices(i)]
def video_kbps(self):
"""The picture on the wire. FIXED by geometry -- there is no lever."""
return self.rec_bytes * self.fps / 1024
def audio_kbps(self):
"""What the CADENCE costs, padding included, which is the honest figure:
the disc moves whole sectors and the wire pays for the ones that are
zero as well as the ones that are audio (FINDINGS 65.3)."""
if not self.has_audio:
return 0.0
return self.cad_a * SECTOR / self.cad_f * self.fps / 1024
def kbps(self):
return self.nframes * self.rec_bytes / (self.nframes / self.fps) / 1024
"""Both, over the scene's own duration."""
return self.video_kbps() + self.audio_kbps()