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

Rate control: rebuilt per-frame, wired in, and gated at zero drift

Browse Source 
FINDINGS 26 stopped the session-5 rate controller before it shipped: it built a
lam-ladder of independent whole-sequence encodes and picked frames off it, so
SKIP blocks referenced reconstructions the decoder never saw -- 111 of 120
frames drifted. The fix is the structural one 26.1 said it had to be.

vq_hybrid is now frame-drivable -- frame_ctx / decide / paint -- and encode() is
a thin loop over it. Rate control drives the same three calls, bisects lam per
frame under the leaky bucket, and feeds back the frame it actually emitted. The
desync has no way to occur, and 09_ratectl_drift.py goes 111/120 -> 0/120. That
test is now part of check.sh, which is ~2 min rather than ~40 s.

Both overshoots on the worst sustained window are closed for under 1 dB, totals
including audio: sasi 137.4 -> 109.5 KB/s (-0.60 dB), scsi 381.6 -> 280.0 KB/s
(-0.91 dB). Zero frames hit the lam=800 cliff, so nothing was destroyed to get
there. Rate control also makes the display path cheaper -- scsi's median drops
53.6% -> 47.1% -- because raising lam moves blocks to SKIP and V1.

Two knobs measured rather than guessed. --rc-floor is worth 0.00 dB on that
window and defaults to the profile lam, so rate control cannot regress content
that already fits. --prefill defaults to 0 and is documented as a trap: it buys
a permission to overshoot of exactly bucket/nframes, and on a 14-frame clip it
disables the controller outright.

FINDINGS 26.5 was wrong in both halves and 27.6 records it. _paint was not the
bottleneck (14% of a frame, though vectorising it was still right at 17.1x) and
the ladder was never "minutes" -- those were k-means in build(). What makes
per-frame rate control affordable is that VQ.assign depends on neither lam nor
prev, so it is cached one frame deep: a 12-step search over 120 frames costs
0.31 s against 49.1 s.

Also caught: fixed-lam sasi was already 5% over target on 00020, the clip
everyone called easy. Nothing noticed because the profile table quotes PSNR and
not bitrate.

check.sh: ALL GREEN.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
This commit is contained in:
prosolis
2026-08-23 14:36:45 -07:00
parent 145753c0bf
commit 497f88b945
9 changed files with 653 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/FINDINGS.md
+143
View File
@@ -1073,3 +1073,146 @@ Each rung is a full-sequence encode and `_paint` is still a Python per-block
loop, so a 5-rung run over 120 frames takes minutes. **Vectorise `_paint`
first** — it is already on the list for the full-disc survey and it makes the
rate-control work practical rather than merely faster.
## 27. Rate control, rebuilt and wired in (session 6)
FINDINGS 26 stopped the session-5 rate controller before it shipped: it picked
frames out of independently-encoded whole-sequence runs, so 111 of 120 frames
referenced reconstructions the decoder would never see. The fix was structural,
as 26.1 said it had to be. It is now wired into `encode.py` and **on by
default** for a profile.
### 27.1 The encoder is frame-drivable, and the drift is zero by construction
`vq_hybrid` now exposes one frame at a time — `frame_ctx(m, f, prev)` /
`decide(ctx, lam)` / `paint(m, ctx, mode)` — and `encode()` is a thin loop over
that API. Rate control drives the same three calls and feeds back **the frame it
actually emitted** as the next frame's `prev`. There is no ladder to pick from,
so the desync has no way to occur.
`tools/analysis/09_ratectl_drift.py`, unchanged in what it asserts:
| | session 5 | session 6 |
|---|---|---|
| frames whose emitted output differs from what the encoder recorded | 111 / 120 | **0 / 120** |
| worst frame | 21,339 px (43.4%) | **0 px** |
| reported PSNR overstatement | 0.36 dB | **0.00 dB** |
This is the harder case for that test on purpose: it runs with `lam_lo=1.0`, so
lam moves on 117 of 119 frame boundaries. Under the old ladder, 67 rung switches
were enough to corrupt 111 frames.
### 27.2 Both overshoots are closed, and they cost under 1 dB
The Singe window (FINDINGS 25.3), which is the worst sustained window on the
disc. Totals include the 7.8 KB/s ADPCM allowance:
| profile | target | fixed lam (session 5) | rate-controlled | quality cost |
|---|---|---|---|---|
| `sasi` | 110 KB/s | 137.4 KB/s (**+25%**) | **109.5 KB/s** | 27.82 → 27.22 dB (−0.60) |
| `scsi` | 280 KB/s | 381.6 KB/s (**+36%**) | **280.0 KB/s** | 30.81 → 29.90 dB (−0.91) |
Zero frames hit the lam=800 cliff at either profile, so nothing was destroyed to
get there (26.2's failure mode did not trigger). `sasi` needed lam to reach 183
at worst against a floor of 60; `scsi` reached 58.7 against 10. The controller
is working an order of magnitude below the cliff, which is where the search
range being capped at 800 rather than 2e5 stops mattering at all — and that is
the point: a range that never needs its top is a range you can trust.
`scsi` still sits **1.43 dB** from the scene palette ceiling of 31.33 dB
(FINDINGS 25.4), against 0.51 dB before. The ceiling, not the codec, is still
what bounds this content.
The percentages differ from 25.3's +18%/+34% because those compared video
payload against the total target; the table above compares like with like
(total against total). The payload figures are unchanged: 129.6 and 373.8 KB/s.
### 27.3 Rate control makes the display path cheaper, not dearer
The decoder-architecture numbers of FINDINGS 25.6 were measured on the
fixed-lam encoder. Re-measured under rate control, on the same window, with the
player picking the cheaper of compose-then-blit and direct-to-GVRAM per frame:
| profile | median display cost | frames above the 70% crossover |
|---|---|---|
| `sasi` fixed → RC | 37.0% → **36.6%** | 30.0% → 26.7% |
| `scsi` fixed → RC | 53.6% → **47.1%** | 53.3% → 35.8% |
Raising lam moves blocks to SKIP and V1, which is fewer blocks to write. The
"implement both paths, pick per frame" conclusion is unaffected and the cap is
still 53.6%.
### 27.4 The quality floor barely matters; the prefill matters, wrongly
Two knobs were measured rather than guessed.
**`--rc-floor`** decides whether a quiet frame may spend more than the fixed-lam
profile would. On the Singe window it is worth nothing — 109.5 vs 110.0 KB/s and
**0.00 dB** — because no frame on that window is quiet enough for the bucket to
saturate. The default is `profile` (never spend more than session 5 would), so
rate control cannot regress content that already fits.
**`--prefill`** models how full the player's buffer is at scene start. It is
tempting and it is a trap, so it defaults to 0:
| clip | prefill 0.0 | 0.5 | 1.0 | target |
|---|---|---|---|---|
| Singe, 120 fr, `sasi` | 109.5 | 112.9 | **116.3** | 110 |
| Singe, 120 fr, `scsi` | 280.0 | 289.1 | **298.2** | 280 |
| 00020, 14 fr, `sasi` | 92.0 | **115.8** | **115.8** | 110 |
| 00020, 14 fr, `scsi` | 224.8 | **255.9** | **255.9** | 280 |
(`scsi` on 00020 is the one cell where prefill looks harmless: the clip fits
under 280 either way. That is the content being easy, not the knob being safe.)
Prefill buys a permission to overshoot of exactly `bucket / nframes`. At 8
frames of bucket over 120 frames that is 6.2% — measured — and on a 14-frame
clip the bucket is larger than the clip, so rate control switches itself off and
reproduces fixed-lam exactly (lam never leaves its floor: min = median = max =
60). **A prefill that makes a target look met has disabled the controller.**
### 27.5 The 00020 undershoot is a clip-length artefact, not a bug
At prefill 0 the 14-frame 00020 clip lands at 92.0 KB/s against a 110 ceiling —
0.66 dB given away for nothing. That is the leaky bucket's startup transient:
the first `bucket_frames` frames cannot draw on a bank they have not accumulated.
It is bounded by `bucket / nframes`, so it is 6% on a 10-second window and 20%
on a 1.2-second one.
The lesson is the one FINDINGS 25.3 already taught in a different costume: **a
1.2-second clip cannot be used to judge rate control.** Real scenes are tens of
seconds. Do not tune the bucket against 00020.
Worth recording separately: fixed-lam `sasi` on 00020 delivers 115.8 KB/s — the
supposedly easy clip was **already 5% over its target**, which nothing had
noticed because the profile table quotes its PSNR and not its bitrate.
### 27.6 FINDINGS 26.5's cost premise was wrong in both halves
26.5 said a rate-control experiment was minutes because `_paint` is a Python
per-block loop, and told the next session to vectorise it first. Vectorising it
was correct and it is **17.1x faster**, but it was never the bottleneck, and the
ladder was never minutes. Measured per frame, 256x192:
| | ms |
|---|---|
| `VQ.assign` x2 — codeword search | **22.83** |
| SKIP error against `prev` | 1.40 |
| `decide` — argmin at one lam | 0.06 |
| `paint`, vectorised | 0.29 |
| `paint`, old per-block loop | 4.93 |
`_paint` was 14% of a frame. A 5-rung ladder over 120 frames was ~18 s of
encoding, not minutes — the "few minutes" in the drift test's docstring was
`H.build`'s k-means (51 s), which no amount of vectorising `_paint` would have
touched.
What actually makes per-frame rate control affordable is that `VQ.assign`'s
output depends on **neither `lam` nor `prev`**, so it is computed once per frame
and a lam search only re-runs the 0.06 ms argmin:
| | |
|---|---|
| 12-step per-frame lam search, 120 frames, symbols cached | **0.31 s** |
| the same search by re-running whole-sequence encodes | 49.10 s |
That is a 158x difference, and it is the reason the controller can afford a real
bisection instead of a 5-rung ladder — which was the actual defect in 26.3.
The cache holds **one frame**. At ~133 KB of intermediates per frame, caching
the sequence would cost 900 MB on a 9.4-minute stream to save nothing: every
caller works a frame at a time.