control: video frame capture + deterministic input-movie replay

Two socket features for building reproducible showcase clips:

- record start <path> [everyN] / record stop: append the RGB888 framebuffer of
  each produced frame to a flat 'GBCV' capture file (downsample with everyN).
  tools/gbgif.py turns it into a GIF (or PNG frames). Capture is decoupled from
  wall-clock/turbo/frameskip, so timing is always correct.

- input play <path> [reset] / input stop: drive the joypad from a synthesized
  TAS-style movie (text: '<frames> [buttons...]' per line), frame-locked so
  replay is deterministic. 'reset' does an exact power-on (preserve cart
  ROM+SRAM, zero all other state) so a movie replays byte-identically -- verified
  by hashing two runs. tools/gbmovie.py is a Python builder for movies.

1 files changed, 81 insertions, 0 deletions

diff --git a/tools/gbgif.py b/tools/gbgif.py
new file mode 100644
index 0000000..c7c8943
--- /dev/null
+++ b/tools/gbgif.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Turn a gbc `.gbv` frame capture into an animated GIF.
+
+Capture one with the emulator's control socket:
+    ./gbctl record start /abs/path/out.gbv 2     # 2 = capture every 2nd frame (~30fps)
+    ...play...
+    ./gbctl record stop
+
+Then:
+    python3 tools/gbgif.py out.gbv out.gif [--scale 3] [--fps 30] [--start N] [--max N]
+
+The .gbv format is a 10-byte header ("GBCV", u16 width, u16 height, u16
+ms-per-frame, little-endian) followed by raw width*height*3 RGB frames.
+"""
+import argparse, struct, sys
+from PIL import Image
+
+
+def load(path):
+    with open(path, "rb") as f:
+        data = f.read()
+    if data[:4] != b"GBCV":
+        sys.exit("not a GBCV capture (bad magic)")
+    w, h, ms = struct.unpack_from("<HHH", data, 4)
+    off, fsize = 10, w * h * 3
+    while off + fsize <= len(data):
+        yield w, h, ms, memoryview(data)[off:off + fsize]
+        off += fsize
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("output", help="GIF path (or a dir/prefix if --png)")
+    ap.add_argument("--scale", type=int, default=3, help="integer pixel zoom (default 3)")
+    ap.add_argument("--fps", type=float, default=0, help="override playback fps (0=use capture)")
+    ap.add_argument("--start", type=int, default=0, help="skip the first N frames")
+    ap.add_argument("--max", type=int, default=0, help="keep at most N frames (0=all)")
+    ap.add_argument("--stride", type=int, default=1, help="keep 1 of every N frames")
+    ap.add_argument("--png", action="store_true", help="dump PNG frames as <output>NNNN.png instead of a GIF")
+    args = ap.parse_args()
+
+    frames, ms_hdr = [], 17
+    for i, (w, h, ms, buf) in enumerate(load(args.input)):
+        ms_hdr = ms
+        if i < args.start or (i - args.start) % args.stride:
+            continue
+        if args.max and len(frames) >= args.max:
+            break
+        im = Image.frombytes("RGB", (w, h), bytes(buf))
+        if args.scale != 1:
+            im = im.resize((w * args.scale, h * args.scale), Image.NEAREST)
+        frames.append(im)
+    if not frames:
+        sys.exit("no frames matched")
+
+    if args.png:
+        for i, im in enumerate(frames):
+            im.save(f"{args.output}{i:04d}.png")
+        print(f"wrote {len(frames)} PNG frames -> {args.output}NNNN.png")
+        return
+
+    dur = (1000.0 / args.fps) if args.fps > 0 else max(ms_hdr, 1) * args.stride
+    # Build one shared palette from a montage of sampled frames so the GIF
+    # doesn't flicker between per-frame palettes (GB uses few colors anyway).
+    sample = frames[:: max(1, len(frames) // 8)][:8] or frames[:1]
+    fw, fh = frames[0].size
+    montage = Image.new("RGB", (fw, fh * len(sample)))
+    for i, s in enumerate(sample):
+        montage.paste(s, (0, i * fh))
+    pal = montage.quantize(colors=256, method=Image.MEDIANCUT)
+    pframes = [f.quantize(palette=pal, dither=Image.NONE) for f in frames]
+
+    pframes[0].save(args.output, save_all=True, append_images=pframes[1:],
+                    duration=dur, loop=0, disposal=1, optimize=True)
+    print(f"{args.output}: {len(frames)} frames, {fw}x{fh}, {1000.0/dur:.1f} fps")
+
+
+if __name__ == "__main__":
+    main()