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.

6 files changed, 405 insertions, 0 deletions

diff --git a/README.md b/README.md
index 80151c4..b93446d 100644
--- a/README.md
+++ b/README.md
@@ -153,9 +153,57 @@ or decimal; **memory bytes are hex** (so `read` output feeds straight back into
 | `delete <0xaddr\|#idx\|all>` | remove a breakpoint                               |
 | `watch <addr>`              | value-change watchpoint on a byte (no arg lists)   |
 | `unwatch <0xaddr\|#idx\|all>`| remove a watchpoint                               |
+| `record start <path> [everyN]` | capture frames to `<path>` (1 of every N); build a GIF with `tools/gbgif.py` |
+| `record stop`               | finish the capture (replies with the frame count)  |
+| `record` (`status`)         | report whether a capture is active                 |
+| `input play <path> [reset]` | replay a synthesized input movie (frame-locked); `reset` = replay from a clean power-on |
+| `input stop`                | stop movie playback (releases all buttons)         |
+| `input` (`status`)          | report movie playback state                        |
 | `quit`                      | shut the emulator down                             |
 | *(any button tokens)*       | same vocabulary as the FIFO (tap/hold/release)     |
 
+### Video capture & input replay (demo GIFs)
+
+Capture the RGB framebuffer to a flat file and turn it into a GIF:
+
+```
+./gbctl record start /abs/out.gbv 2   # capture 1 of every 2 frames (~30fps)
+...
+./gbctl record stop
+python3 tools/gbgif.py out.gbv out.gif --scale 3
+```
+
+Drive the ROM from a **synthesized input movie** instead of live input, for
+reproducible demos. A movie is a text file of `<frames> [buttons...]` lines
+(`a b start select up down left right`; none/`-` = released); the emulator
+applies one line's worth of joypad state per emulated frame, so replay is
+deterministic. Build one by hand or with `tools/gbmovie.py`:
+
+```python
+from gbmovie import Movie
+m = Movie()
+m.wait(340)                 # boot splash + fastboot -> overworld
+m.hold("select", 8)         # open the SL0P menu
+m.tap("down", repeat=13)    # cursor to the last item
+m.hold("a", 6); m.wait(600)
+m.save("demo.gbmv")
+```
+
+`input play <path> reset` gives a clean, repeatable power-on (keeps cart
+ROM+SRAM, zeroes all other state), so a movie replays byte-identically every
+time. For a frame-exact demo GIF, arm both while paused so they start on the
+same frame:
+
+```
+./gbctl pause
+./gbctl input play /abs/demo.gbmv reset
+./gbctl record start /abs/demo.gbv 2
+./gbctl continue
+...                                   # let the movie play
+./gbctl record stop
+python3 tools/gbgif.py demo.gbv demo.gif --scale 3 --start 172
+```
+
 When free-running (`continue`) hits a breakpoint or watchpoint, every connected
 client receives an async line and the machine pauses:
 
diff --git a/src/control.c b/src/control.c
index 5cea4e0..0ace343 100644
--- a/src/control.c
+++ b/src/control.c
@@ -56,6 +56,28 @@ static u8   wp_last[MAX_WP];
 // fired can still recover it via the `stopinfo` command.
 static char last_stop[64] = "none";
 
+// ---- frame recording ----
+// Dump the RGB888 framebuffer of each *produced* frame to a flat capture file:
+// a 10-byte header ("GBCV", u16 width, u16 height, u16 ms-per-frame, all LE)
+// followed by raw width*height*3 byte frames. tools/gbgif.py turns it into a
+// GIF. Downsample with everyN (capture 1 of every N frames) for smaller files.
+static FILE *rec_fp = NULL;
+static u32   rec_every = 1;
+static u32   rec_phase = 0;
+static u64   rec_written = 0;
+static char  rec_path[512];
+
+// ---- input replay (TAS-style movie playback) ----
+// A movie is a text file of `<frames> [buttons...]` lines (see input_btn_bit);
+// while playing, each emulated frame's joypad state is driven from the movie
+// instead of live input, so a synthesized demo replays deterministically. Pair
+// with `record` (and a reset) to produce reproducible showcase GIFs.
+static FILE *movie_fp = NULL;
+static int   movie_hold = 0;    // frames left to hold the current mask
+static u8    movie_mask = 0;
+static u64   movie_frame = 0;
+static char  movie_path[512];
+
 // ---------------------------------------------------------------------------
 // small helpers
 // ---------------------------------------------------------------------------
@@ -239,6 +261,33 @@ static int parse_byte_hex(const char *s) {
 
 // Dispatch one command line from client `fd`. `orig` is the untouched line
 // (used for the button-command fallback); `line` is a mutable copy.
+// movie button name -> our pressed-state bit (see gb.h BTN_*). Anything else
+// ("-", "none", "idle", unknown) contributes nothing = released.
+static u8 input_btn_bit(const char *s) {
+    if (!strcasecmp(s, "a"))      return BTN_A;
+    if (!strcasecmp(s, "b"))      return BTN_B;
+    if (!strcasecmp(s, "start"))  return BTN_START;
+    if (!strcasecmp(s, "select")) return BTN_SELECT;
+    if (!strcasecmp(s, "up"))     return BTN_UP;
+    if (!strcasecmp(s, "down"))   return BTN_DOWN;
+    if (!strcasecmp(s, "left"))   return BTN_LEFT;
+    if (!strcasecmp(s, "right"))  return BTN_RIGHT;
+    return 0;
+}
+
+// Exact, repeatable power-on state so a movie replays identically every time.
+// Startup is calloc(zero) -> cart_load -> gb_reset, so we reproduce it: preserve
+// the loaded cart (ROM + SRAM, so the save is intact), zero *all* other emulator
+// state, then the normal post-boot reset. Zeroing only some RAM (and leaving
+// e.g. double-speed / timer / DMA residue from the prior session) makes the boot
+// diverge run to run -- this wipes the lot.
+static void replay_reset(GB *gb) {
+    Cart cart = gb->cart;            // struct of pointers into the loaded ROM/SRAM
+    memset(gb, 0, sizeof(*gb));
+    gb->cart = cart;
+    gb_reset(gb);
+}
+
 static void dispatch(GB *gb, int fd, const char *orig, char *line) {
     // tokenize (whitespace); keep argv for structured commands
     char *argv[68];
@@ -451,6 +500,74 @@ static void dispatch(GB *gb, int fd, const char *orig, char *line) {
         return;
     }
 
+    if (!strcasecmp(v, "record") || !strcasecmp(v, "rec")) {
+        const char *sub = argc >= 2 ? argv[1] : "status";
+        if (!strcasecmp(sub, "start")) {
+            if (argc < 3) { reply(fd, "err record start <path> [everyN]"); return; }
+            if (rec_fp) { fclose(rec_fp); rec_fp = NULL; }
+            u32 every = 1;
+            if (argc >= 4) { bool ok; long n = parse_num(argv[3], &ok);
+                             if (ok && n > 0) every = (u32)n; }
+            FILE *f = fopen(argv[2], "wb");
+            if (!f) { reply(fd, "err cannot open '%s'", argv[2]); return; }
+            u16 w = SCREEN_W, h = SCREEN_H;
+            // playback interval per captured frame (the GB runs ~59.73 fps)
+            u16 ms = (u16)(1000.0 * every / 59.73 + 0.5);
+            u8 hdr[10] = { 'G','B','C','V',
+                           (u8)(w & 0xff), (u8)(w >> 8),
+                           (u8)(h & 0xff), (u8)(h >> 8),
+                           (u8)(ms & 0xff), (u8)(ms >> 8) };
+            fwrite(hdr, 1, sizeof(hdr), f);
+            rec_fp = f; rec_every = every; rec_phase = 0; rec_written = 0;
+            snprintf(rec_path, sizeof(rec_path), "%s", argv[2]);
+            reply(fd, "ok record start %s every=%u", rec_path, (unsigned)every);
+            return;
+        }
+        if (!strcasecmp(sub, "stop")) {
+            if (!rec_fp) { reply(fd, "err not recording"); return; }
+            fclose(rec_fp); rec_fp = NULL;
+            reply(fd, "ok record stop %s frames=%llu",
+                  rec_path, (unsigned long long)rec_written);
+            return;
+        }
+        // status
+        if (rec_fp) reply(fd, "ok record active %s frames=%llu every=%u",
+                          rec_path, (unsigned long long)rec_written,
+                          (unsigned)rec_every);
+        else reply(fd, "ok record inactive");
+        return;
+    }
+
+    if (!strcasecmp(v, "input") || !strcasecmp(v, "movie") ||
+        !strcasecmp(v, "play")) {
+        const char *sub = argc >= 2 ? argv[1] : "status";
+        if (!strcasecmp(sub, "play") || !strcasecmp(sub, "load")) {
+            if (argc < 3) { reply(fd, "err input play <path> [reset]"); return; }
+            if (movie_fp) { fclose(movie_fp); movie_fp = NULL; }
+            FILE *f = fopen(argv[2], "r");
+            if (!f) { reply(fd, "err cannot open '%s'", argv[2]); return; }
+            bool do_reset = (argc >= 4 && !strcasecmp(argv[3], "reset"));
+            if (do_reset) replay_reset(gb);
+            movie_fp = f; movie_hold = 0; movie_mask = 0; movie_frame = 0;
+            snprintf(movie_path, sizeof movie_path, "%s", argv[2]);
+            reply(fd, "ok input play %s%s", movie_path,
+                  do_reset ? " reset" : "");
+            return;
+        }
+        if (!strcasecmp(sub, "stop")) {
+            if (!movie_fp) { reply(fd, "err not playing"); return; }
+            fclose(movie_fp); movie_fp = NULL; movie_hold = 0;
+            gb->buttons = 0;
+            reply(fd, "ok input stop %s frame=%llu", movie_path,
+                  (unsigned long long)movie_frame);
+            return;
+        }
+        if (movie_fp) reply(fd, "ok input playing %s frame=%llu", movie_path,
+                            (unsigned long long)movie_frame);
+        else reply(fd, "ok input idle");
+        return;
+    }
+
     // fallback: treat the whole line as button-command tokens (legacy FIFO
     // vocabulary). Reply ok so scripted callers can synchronize.
     input_handle_command(orig);
@@ -537,6 +654,8 @@ void control_open(const char *path) {
 }
 
 void control_close(void) {
+    if (rec_fp) { fclose(rec_fp); rec_fp = NULL; }
+    if (movie_fp) { fclose(movie_fp); movie_fp = NULL; }
     if (!active) return;
     for (int i = 0; i < MAX_CLIENTS; i++) drop_client(i);
     if (listen_fd >= 0) { close(listen_fd); listen_fd = -1; }
@@ -544,6 +663,47 @@ void control_close(void) {
     active = false;
 }
 
+// Called once per main-loop iteration, right after control_run_frame(). Appends
+// the just-produced frame to the capture file (honoring the everyN downsample).
+// Gated on frame_ready so a paused/stepping machine doesn't re-record a still.
+void control_record_frame(GB *gb) {
+    if (!rec_fp || !gb->ppu.frame_ready) return;
+    gb->ppu.frame_ready = false;   // consume: don't re-capture while paused
+    if ((rec_phase++ % rec_every) != 0) return;
+    fwrite(gb->ppu.fb, 1, sizeof(gb->ppu.fb), rec_fp);
+    rec_written++;
+}
+
+// Called once per main-loop iteration BEFORE control_run_frame(): if a movie is
+// playing, drive this frame's joypad state from it (overriding live input).
+// Frame-locked, so a synthesized demo replays deterministically. No-op (live
+// input passes through) when idle or while the debugger holds execution.
+void control_input_frame(GB *gb) {
+    if (!movie_fp || run_state == PAUSED) return;
+    while (movie_hold <= 0) {
+        char buf[256];
+        if (!fgets(buf, sizeof buf, movie_fp)) {   // end of movie
+            fclose(movie_fp); movie_fp = NULL;
+            gb->buttons = 0;                       // release everything
+            return;
+        }
+        char *hash = strchr(buf, '#');
+        if (hash) *hash = 0;
+        char *tok = strtok(buf, " \t\r\n");
+        if (!tok) continue;                        // blank / comment-only line
+        bool ok; long n = parse_num(tok, &ok);
+        if (!ok || n <= 0) continue;               // need a positive frame count
+        u8 mask = 0;
+        for (char *t = strtok(NULL, " \t\r\n"); t; t = strtok(NULL, " \t\r\n"))
+            mask |= input_btn_bit(t);
+        movie_hold = (int)n;
+        movie_mask = mask;
+    }
+    gb->buttons = movie_mask;
+    movie_hold--;
+    movie_frame++;
+}
+
 bool control_active(void) { return active; }
 bool control_paused(void) { return active && run_state == PAUSED; }
 
diff --git a/src/control.h b/src/control.h
index a625853..db5ee93 100644
--- a/src/control.h
+++ b/src/control.h
@@ -33,4 +33,12 @@ bool control_paused(void);
 // is inactive this simply runs a full frame like the plain emulator loop.
 void control_run_frame(GB *gb);
 
+// If a recording is active (see the `record` command), append the frame just
+// produced by control_run_frame() to the capture file. No-op otherwise.
+void control_record_frame(GB *gb);
+
+// If a movie is playing (see the `input play` command), set this frame's joypad
+// state from it. Call once per loop iteration *before* control_run_frame().
+void control_input_frame(GB *gb);
+
 #endif
diff --git a/src/main.c b/src/main.c
index 541ce44..ecd818e 100644
--- a/src/main.c
+++ b/src/main.c
@@ -137,7 +137,9 @@ int main(int argc, char **argv) {
 
         // Emulate a full frame, honoring debugger pause/step/breakpoints when
         // the control socket is active (otherwise a plain full frame).
+        control_input_frame(gb);    // drive input from a replay movie if playing
         control_run_frame(gb);
+        control_record_frame(gb);   // append to the video capture if recording
 
         // decide whether to draw this frame
         bool do_render = (since_render >= frameskip);
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())