feat: adaptive raw/zlib/delta frame codec (opt-in, backward compatible)

The binary protocol re-sent the full grid every frame. This adds an opt-in
per-frame codec that picks the smallest of three encodings and tags it in a
1-byte header, without changing the rendered output:

  0 RAW    framebuffer as-is (legacy)
  1 ZLIB   zlib(framebuffer)
  2 DELTA  only the cells changed since the previous frame, patched on top

Clients opt in via /ws?codec=adaptive; omitting it yields the original protocol
byte-for-byte, so existing clients are unaffected. A keyframe is forced
periodically for resync. codec.js is shared by the browser and the Node test,
so the shipped decode path is the tested one.

Optional --quality {lossless,high,balanced,low} enables lossy temporal delta
(conditional replenishment): a colour cell is only re-sent once it drifts past a
tolerance from what the viewer already sees; the character plane stays exact.
Default lossless = bit-exact.

Measured wire savings (mode 5, 200x80): static screen 0.3% of legacy (~375x),
pixel mode 11.6%, high-motion 63% (never worse). Encoder tuned (zlib level 3,
smart candidate selection) to stay well under the frame budget.

Verified bit-exact two independent ways: Python->Node vectors and a live
adaptive-vs-legacy WebSocket diff. (A fuller mutation + Autobahn conformance
harness exists on request.)
This commit is contained in:
Nate 2026-06-13 02:14:42 -04:00
parent 8c60ef12a0
commit e3f282910d
10 changed files with 478 additions and 10 deletions

View file

@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Generate the synthetic test clips the test suite uses (ffmpeg lavfi sources).
# Deterministic and dependency-free so CI and local runs match.
set -eu
cd "$(dirname "$0")/.."
mkdir -p videos
ff(){ ffmpeg -y -loglevel error "$@"; }
ff -f lavfi -i "testsrc2=size=640x360:rate=30" -f lavfi -i "sine=frequency=440:duration=6" \
-t 6 -pix_fmt yuv420p videos/test.mp4
ff -f lavfi -i "mandelbrot=size=640x480:rate=24:end_scale=0.3" -t 5 -pix_fmt yuv420p videos/mandel.mp4
ff -f lavfi -i "life=size=320x240:rate=24:mold=10:ratio=0.1:death_color=#101030:life_color=#30ff80" \
-t 5 -pix_fmt yuv420p videos/life.mp4
ff -f lavfi -i "smptebars=size=640x360:rate=24" \
-vf "drawtext=text='ASCILINE':fontsize=60:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2:box=1:boxcolor=black@0.5" \
-t 4 -pix_fmt yuv420p videos/bars.mp4
echo "generated: $(ls videos/*.mp4 | tr '\n' ' ')"