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, 160 insertions, 0 deletions

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; }