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.

2 files changed, 187 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()
diff --git a/tools/gbmovie.py b/tools/gbmovie.py
new file mode 100644
index 0000000..dc92989
--- /dev/null
+++ b/tools/gbmovie.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Build TAS-style input movies for the gbc emulator's `input play` replayer.
+
+A movie is a text file of `<frames> [buttons...]` lines: hold the given buttons
+(a b start select up down left right; none/'-' = released) for that many frames.
+Blank lines and `# comments` are ignored. The emulator drives one line's worth
+of joypad state per emulated frame, so replay is deterministic:
+
+    ./gbctl input play /abs/demo.gbmv reset   # reset + replay from boot
+    ./gbctl record start /abs/demo.gbv 2      # (optional) capture video
+    ...
+    ./gbctl record stop
+    python3 tools/gbgif.py demo.gbv demo.gif --scale 3
+
+Use as a library to synthesize demos:
+
+    from gbmovie import Movie
+    m = Movie()
+    m.wait(40)                      # let fastboot settle
+    m.hold("select", 8)             # open the SL0P menu
+    m.wait(16)
+    m.tap("down", repeat=13)        # cursor down to the last item
+    m.hold("a", 6)                  # select it
+    m.wait(600)                     # watch it run
+    m.save("demo.gbmv")
+
+Run this file directly to emit the sample demo above to stdout.
+"""
+from __future__ import annotations
+
+
+def _btns(buttons) -> str:
+    if buttons is None:
+        return ""
+    if isinstance(buttons, str):
+        buttons = buttons.split()
+    return " ".join(buttons)
+
+
+class Movie:
+    def __init__(self):
+        self._lines: list[str] = []
+        self._frames = 0
+
+    def hold(self, buttons, frames: int):
+        """Hold `buttons` (str/list) for `frames` frames."""
+        frames = int(frames)
+        if frames <= 0:
+            return self
+        b = _btns(buttons)
+        self._lines.append(f"{frames} {b}".rstrip())
+        self._frames += frames
+        return self
+
+    def wait(self, frames: int):
+        """Idle (no buttons) for `frames` frames."""
+        return self.hold(None, frames)
+
+    def tap(self, buttons, frames: int = 4, gap: int = 6, repeat: int = 1):
+        """Press `buttons` for `frames`, release for `gap`, `repeat` times.
+
+        The gap matters: the menu's low-sensitivity polling needs the button to
+        be released between presses to register a repeat."""
+        for _ in range(int(repeat)):
+            self.hold(buttons, frames)
+            if gap > 0:
+                self.wait(gap)
+        return self
+
+    def comment(self, text: str):
+        self._lines.append(f"# {text}")
+        return self
+
+    @property
+    def total_frames(self) -> int:
+        return self._frames
+
+    def render(self) -> str:
+        return "\n".join(self._lines) + "\n"
+
+    def save(self, path: str):
+        with open(path, "w") as f:
+            f.write(self.render())
+        return path
+
+
+def _sample() -> Movie:
+    m = Movie()
+    m.comment("SL0P demo: open menu -> last item (SAVER) -> watch it wander")
+    m.wait(340)                     # boot splash + fastboot -> overworld (~307f)
+    m.hold("select", 8)
+    m.wait(16)
+    m.tap("down", repeat=13)
+    m.hold("a", 6)
+    m.wait(600)
+    return m
+
+
+if __name__ == "__main__":
+    import sys
+    m = _sample()
+    if len(sys.argv) > 1:
+        m.save(sys.argv[1])
+        print(f"wrote {sys.argv[1]} ({m.total_frames} frames)")
+    else:
+        sys.stdout.write(m.render())