gemba 0.1.1 → 0.2.1

data/lib/gemba/event_bus.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+
+module Gemba
+  # Publish/subscribe event bus for decoupled communication.
+  #
+  # Emitters fire named events, subscribers listen — no intermediaries.
+  #
+  # Lives at Gemba.bus (module-level). Player creates it at startup;
+  # any class does Gemba.bus.emit / Gemba.bus.on. For tests, replace
+  # with Gemba.bus = EventBus.new (or a mock).
+  #
+  # @example
+  #   Gemba.bus.on(:scale_changed) { |val| apply_scale(val) }
+  #   Gemba.bus.emit(:scale_changed, 3)
+  class EventBus
+    def initialize
+      @listeners = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Subscribe to a named event.
+    # @param event [Symbol]
+    # @return [Proc] the block (for later #off)
+    def on(event, &block)
+      @listeners[event] << block
+      block
+    end
+
+    # Emit a named event to all subscribers.
+    # @param event [Symbol]
+    def emit(event, *args, **kwargs)
+      Gemba.log(:debug) { "bus: #{event}(#{[*args, *kwargs.map { |k,v| "#{k}: #{v}" }].join(', ')})" }
+      if kwargs.empty?
+        @listeners[event].each { |cb| cb.call(*args) }
+      else
+        @listeners[event].each { |cb| cb.call(*args, **kwargs) }
+      end
+    end
+
+    # Unsubscribe a specific block.
+    # @param event [Symbol]
+    # @param block [Proc] the block returned by #on
+    def off(event, block)
+      @listeners[event].delete(block)
+    end
+  end
+
+end

data/lib/gemba/frame_stack.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Push/pop stack for content frames inside the main window.
+  #
+  # Mirrors the ModalStack pattern. When a new frame is pushed, the
+  # previous frame is hidden and the new one is shown. Popping reverses
+  # the transition.
+  #
+  # Frames must implement the FrameStack protocol:
+  #   show     — pack/display the frame
+  #   hide     — unpack/remove the frame from view
+  #   cleanup  — release resources (SDL2, etc.)
+  #
+  # @example
+  #   stack = FrameStack.new
+  #   stack.push(:picker, game_picker_frame)
+  #   stack.push(:emulator, emulator_frame)  # picker auto-hidden
+  #   stack.pop  # emulator hidden, picker re-shown
+  class FrameStack
+    Entry = Data.define(:name, :frame)
+
+    def initialize
+      @stack = []
+    end
+
+    # @return [Boolean] true if any frame is on the stack
+    def active? = !@stack.empty?
+
+    # @return [Symbol, nil] name of the topmost frame
+    def current = @stack.last&.name
+
+    # @return [Object, nil] the topmost frame object
+    def current_frame = @stack.last&.frame
+
+    # @return [Integer] number of frames on the stack
+    def size = @stack.length
+
+    # Push a frame onto the stack.
+    #
+    # The previous frame (if any) is hidden before the new one is shown.
+    #
+    # @param name [Symbol] identifier (e.g. :picker, :emulator)
+    # @param frame [#show, #hide] the frame object
+    def push(name, frame)
+      @stack.last&.frame&.hide
+      @stack.push(Entry.new(name: name, frame: frame))
+      frame.show
+    end
+
+    # Replace the current frame in-place without changing the stack depth.
+    #
+    # The existing frame is hidden; the new one is shown under the same name.
+    def replace_current(frame)
+      return unless (entry = @stack.last)
+      entry.frame.hide
+      @stack[-1] = Entry.new(name: entry.name, frame: frame)
+      frame.show
+    end
+
+    # Pop the current frame off the stack.
+    #
+    # The popped frame is hidden. If there's a previous frame, it is re-shown.
+    def pop
+      return unless (entry = @stack.pop)
+      entry.frame.hide
+      @stack.last&.frame&.show
+    end
+  end
+end

data/lib/gemba/game_index.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gemba
+  # Lookup table mapping ROM serial codes to canonical game names.
+  #
+  # Data is pre-baked from No-Intro DAT files via script/bake_game_index.rb
+  # and stored as JSON in lib/gemba/data/{platform}_games.json.
+  #
+  # Loaded lazily on first lookup per platform.
+  #
+  #   GameIndex.lookup("AGB-AXVE")  # => "Pokemon - Ruby Version (USA)"
+  #   GameIndex.lookup("CGB-BYTE")  # => nil (unknown)
+  #
+  class GameIndex
+    DATA_DIR = File.expand_path("data", __dir__)
+
+    PLATFORM_FILES = {
+      "AGB" => "gba_games.json",
+      "CGB" => "gbc_games.json",
+      "DMG" => "gb_games.json",
+    }.freeze
+
+    MD5_FILES = {
+      "AGB" => "gba_md5.json",
+      "CGB" => "gbc_md5.json",
+      "DMG" => "gb_md5.json",
+    }.freeze
+
+    # Maps RomLibrary platform short names → GameIndex prefixes
+    PLATFORM_PREFIX = { "gba" => "AGB", "gbc" => "CGB", "gb" => "DMG" }.freeze
+
+    class << self
+      # Look up a canonical game name by serial code.
+      # @param game_code [String] e.g. "AGB-AXVE", "CGB-BYTE", "DMG-XXXX"
+      # @return [String, nil] canonical name or nil if not found
+      def lookup(game_code)
+        return nil unless game_code && !game_code.empty?
+
+        platform = game_code.split("-", 2).first
+        index = index_for(platform, PLATFORM_FILES)
+        return nil unless index
+
+        index[game_code]
+      end
+
+      # Look up a canonical game name by MD5 hex digest.
+      # @param md5      [String] hex MD5 of ROM content (any case)
+      # @param platform [String] short name from RomLibrary — "gba", "gbc", or "gb"
+      # @return [String, nil]
+      def lookup_by_md5(md5, platform)
+        return nil unless md5 && !md5.empty?
+
+        prefix = PLATFORM_PREFIX[platform.to_s.downcase]
+        return nil unless prefix
+
+        idx = index_for(prefix, MD5_FILES)
+        idx&.[](md5.downcase)
+      end
+
+      # Force-reload all indexes (useful after re-baking).
+      def reset!
+        @indexes = {}
+      end
+
+      private
+
+      def index_for(platform, files)
+        @indexes ||= {}
+        key = "#{platform}:#{files.object_id}"
+        return @indexes[key] if @indexes.key?(key)
+
+        file = files[platform]
+        return(@indexes[key] = nil) unless file
+
+        path = File.join(DATA_DIR, file)
+        return(@indexes[key] = nil) unless File.exist?(path)
+
+        @indexes[key] = JSON.parse(File.read(path))
+      end
+    end
+  end
+end

data/lib/gemba/game_picker_frame.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+
+module Gemba
+  # Startup frame showing a 4×4 grid of ROM cards.
+  #
+  # Each card displays box art (if available), ROM title, and platform.
+  # Clicking a populated card emits :rom_selected on the bus.
+  # Right-clicking a populated card shows a context menu (Play / Set Boxart).
+  # Pure Tk — no SDL2.
+  class GamePickerFrame
+    include BusEmitter
+    include Locale::Translatable
+
+    COLS          = 4
+    ROWS          = 4
+    SLOTS         = COLS * ROWS
+    IMG_SUBSAMPLE    = 4   # 512px ÷ 4 = 128px per card
+    IMG_SIZE         = 128 # height/width of the scaled image in pixels
+    PLACEHOLDER_PNG  = File.expand_path("../../assets/placeholder_boxart.png", __dir__)
+
+    # Aspect ratio for wm aspect lock when picker is visible (width:height).
+    # 3:4 gives enough vertical room for image + title + platform label.
+    PICKER_ASPECT_W = 3
+    PICKER_ASPECT_H = 4
+
+    # Default and minimum picker window dimensions (must satisfy PICKER_ASPECT ratio)
+    PICKER_DEFAULT_W = 768
+    PICKER_DEFAULT_H = 1024  # 768 * 4/3
+    PICKER_MIN_W     = 576
+    PICKER_MIN_H     = 768
+
+    def default_geometry = [PICKER_DEFAULT_W, PICKER_DEFAULT_H]
+    def min_geometry     = [PICKER_MIN_W,     PICKER_MIN_H]
+
+    def initialize(app:, rom_library:, boxart_fetcher: nil, rom_overrides: nil)
+      @app      = app
+      @rom_library = rom_library
+      @fetcher  = boxart_fetcher
+      @overrides = rom_overrides
+      @built    = false
+      @cards    = {}   # index => { frame:, image:, title:, platform:, photo: }
+      @photos   = {}   # key => Tk image name (kept alive to prevent GC)
+    end
+
+    def show
+      build_ui unless @built
+      refresh
+      @app.command(:pack, @outer, fill: :both, expand: 1)
+    end
+
+    def hide
+      @app.command(:pack, :forget, @outer) rescue nil
+    end
+
+    def cleanup
+      @photos&.each_value { |name| @app.command(:image, :delete, name) rescue nil }
+      @photos&.clear
+    end
+
+    def receive(event, **args)
+      case event
+      when :refresh then refresh
+      end
+    end
+
+    def aspect_ratio = [PICKER_ASPECT_W, PICKER_ASPECT_H]
+    def rom_loaded? = false
+    def sdl2_ready? = false
+    def paused? = false
+
+    private
+
+    def build_ui
+      @outer = '.game_picker'
+      @app.command('ttk::frame', @outer, padding: 0)
+
+      @cards_frame = "#{@outer}.cards"
+      @app.command('ttk::frame', @cards_frame, padding: 16)
+      @app.command(:pack, @cards_frame, fill: :both, expand: 1)
+
+      # Capture the system window background color so hollow cards blend in
+      # rather than appearing as stark black rectangles.
+      @empty_bg = @app.tcl_eval(". cget -background")
+
+      # Load a transparent 128×128 placeholder once — gives all image labels
+      # a fixed pixel size whether or not box art has been fetched yet.
+      @app.command(:image, :create, :photo, 'boxart_placeholder', file: PLACEHOLDER_PNG)
+
+      SLOTS.times do |i|
+        row = i / COLS
+        col = i % COLS
+
+        cell = "#{@cards_frame}.card#{i}"
+        @app.command(:frame, cell, relief: :groove, borderwidth: 1,
+          padx: 4, pady: 4, bg: '#2a2a2a')
+        @app.command(:grid, cell, row: row, column: col, padx: 6, pady: 6, sticky: :nsew)
+
+        img_lbl = "#{cell}.img"
+        @app.command(:label, img_lbl, bg: '#2a2a2a', anchor: :center, image: 'boxart_placeholder')
+        @app.command(:pack, img_lbl, fill: :x)
+
+        title_lbl = "#{cell}.title"
+        @app.command(:label, title_lbl, text: '', anchor: :center,
+          bg: '#2a2a2a', fg: '#cccccc',
+          font: '{TkDefaultFont} 10',
+          justify: :center, wraplength: IMG_SIZE)
+        @app.command(:bind, title_lbl, '<Configure>', proc {
+          w = @app.tcl_eval("winfo width #{title_lbl}").to_i
+          @app.command(title_lbl, :configure, wraplength: w - 8) if w > 8
+        })
+        @app.command(:pack, title_lbl, fill: :x, pady: [4, 2])
+
+        plat_lbl = "#{cell}.plat"
+        @app.command(:label, plat_lbl, text: '', anchor: :center,
+          bg: '#2a2a2a', fg: '#888888',
+          font: '{TkDefaultFont} 8')
+        @app.command(:pack, plat_lbl, fill: :x, pady: [0, 4])
+
+        @cards[i] = { frame: cell, image: img_lbl, title: title_lbl, platform: plat_lbl }
+      end
+
+      # Make columns and rows expand evenly
+      COLS.times { |c| @app.command(:grid, :columnconfigure, @cards_frame, c, weight: 1) }
+      ROWS.times { |r| @app.command(:grid, :rowconfigure, @cards_frame, r, weight: 1) }
+
+      build_toolbar
+
+      @built = true
+    end
+
+    def build_toolbar
+      sep = "#{@outer}.sep"
+      @app.command('ttk::separator', sep, orient: :horizontal)
+      @app.command(:pack, sep, fill: :x)
+
+      toolbar = "#{@outer}.toolbar"
+      @app.command('ttk::frame', toolbar, padding: [4, 2])
+      @app.command(:pack, toolbar, fill: :x)
+
+      gear_btn = "#{toolbar}.gear"
+      gear_menu = "#{toolbar}.gearmenu"
+      @app.command('ttk::button', gear_btn, text: "\u2699", width: 1,
+        command: proc { post_view_menu(gear_menu, gear_btn) })
+      @app.command(:pack, gear_btn, side: :right)
+    end
+
+    def post_view_menu(menu, btn)
+      @app.command(:menu, menu, tearoff: 0) unless @app.tcl_eval("winfo exists #{menu}") == '1'
+      @app.command(menu, :delete, 0, :end)
+      current = Gemba.user_config.picker_view
+      @app.command(menu, :add, :command,
+        label: "#{current == 'grid' ? "\u2713 " : '  '}#{translate('picker.toolbar.boxart_view')}",
+        command: proc { emit(:picker_view_changed, view: 'grid') })
+      @app.command(menu, :add, :command,
+        label: "#{current == 'list' ? "\u2713 " : '  '}#{translate('picker.toolbar.list_view')}",
+        command: proc { emit(:picker_view_changed, view: 'list') })
+      x = @app.tcl_eval("winfo rootx #{btn}").to_i
+      y = @app.tcl_eval("winfo rooty #{btn}").to_i
+      h = @app.tcl_eval("winfo height #{btn}").to_i
+      @app.tcl_eval("tk_popup #{menu} #{x} #{y + h}")
+    end
+
+    def refresh
+      roms = @rom_library.all.first(SLOTS)
+
+      SLOTS.times do |i|
+        card = @cards[i]
+        rom  = roms[i]
+
+        if rom
+          rom_info = RomInfo.from_rom(rom, fetcher: @fetcher, overrides: @overrides)
+          populate_card(card, rom_info)
+        else
+          hollow_card(card)
+        end
+      end
+    end
+
+    def populate_card(card, rom_info)
+      @app.command(card[:image],    :configure, bg: '#2a2a2a')
+      @app.command(card[:title],    :configure, text: rom_info.title,    fg: '#cccccc', bg: '#2a2a2a')
+      @app.command(card[:platform], :configure, text: rom_info.platform, fg: '#888888', bg: '#2a2a2a')
+      @app.command(card[:frame],    :configure, relief: :groove, bg: '#2a2a2a')
+
+      # Determine which image to show
+      key = rom_info.rom_id || rom_info.game_code
+
+      if rom_info.boxart_path
+        # Custom override or cached art — load immediately
+        if @photos.key?(key)
+          @app.command(card[:image], :configure, image: @photos[key])
+        else
+          set_card_image(card, key, rom_info.boxart_path)
+        end
+      elsif rom_info.has_official_entry && @fetcher && rom_info.game_code
+        # No art yet but libretro has an entry — kick off async fetch
+        @app.command(card[:image], :configure, image: 'boxart_placeholder')
+        @fetcher.fetch(rom_info.game_code) { |path| set_card_image(card, key, path) }
+      else
+        @app.command(card[:image], :configure, image: 'boxart_placeholder')
+      end
+
+      # Left-click → play
+      click = proc { emit(:rom_selected, rom_info.path) }
+      @app.command(:bind, card[:frame],    '<Button-1>', click)
+      @app.command(:bind, card[:image],    '<Button-1>', click)
+      @app.command(:bind, card[:title],    '<Button-1>', click)
+      @app.command(:bind, card[:platform], '<Button-1>', click)
+
+      # Right-click → context menu
+      bind_context_menu(card, rom_info)
+    end
+
+    def hollow_card(card)
+      @app.command(card[:image],    :configure, image: 'boxart_placeholder', bg: @empty_bg)
+      @app.command(card[:title],    :configure, text: '', fg: @empty_bg,     bg: @empty_bg)
+      @app.command(card[:platform], :configure, text: '',                    bg: @empty_bg)
+      @app.command(card[:frame],    :configure, relief: :ridge,              bg: @empty_bg)
+
+      [:frame, :image, :title, :platform].each do |k|
+        @app.command(:bind, card[k], '<Button-1>', '')
+        @app.command(:bind, card[k], '<Button-3>', '')
+      end
+    end
+
+    def bind_context_menu(card, rom_info)
+      handler = proc { post_card_menu(card, rom_info) }
+      @app.command(:bind, card[:frame],    '<Button-3>', handler)
+      @app.command(:bind, card[:image],    '<Button-3>', handler)
+      @app.command(:bind, card[:title],    '<Button-3>', handler)
+      @app.command(:bind, card[:platform], '<Button-3>', handler)
+    end
+
+    def post_card_menu(card, rom_info)
+      menu = "#{card[:frame]}.ctx"
+      exists = @app.tcl_eval("winfo exists #{menu}") == '1'
+      @app.command(:menu, menu, tearoff: 0) unless exists
+      @app.command(menu, :delete, 0, :end)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.play'),
+        command: proc { emit(:rom_selected, rom_info.path) })
+      qs_slot = quick_save_slot
+      qs_state = quick_save_exists?(rom_info, qs_slot)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.quick_load'),
+        state: qs_state ? :normal : :disabled,
+        command: proc { emit(:rom_quick_load, path: rom_info.path, slot: qs_slot) })
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.set_boxart'),
+        command: proc { pick_custom_boxart(card, rom_info) })
+      @app.command(menu, :add, :separator)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.remove'),
+        command: proc { remove_rom(rom_info) })
+      @app.tcl_eval("tk_popup #{menu} [winfo pointerx .] [winfo pointery .]")
+    end
+
+    def quick_save_slot
+      Gemba.user_config.quick_save_slot
+    end
+
+    def quick_save_exists?(rom_info, slot)
+      return false unless rom_info.rom_id
+      state_file = File.join(Gemba.user_config.states_dir, rom_info.rom_id, "state#{slot}.ss")
+      File.exist?(state_file)
+    end
+
+    def remove_rom(rom_info)
+      @rom_library.remove(rom_info.rom_id)
+      @rom_library.save!
+      refresh
+    end
+
+    def pick_custom_boxart(card, rom_info)
+      return unless @overrides
+      filetypes = '{{PNG Images} {.png}}'
+      path = @app.tcl_eval("tk_getOpenFile -filetypes {#{filetypes}}")
+      return if path.to_s.strip.empty?
+      dest = @overrides.set_custom_boxart(rom_info.rom_id, path)
+      key  = rom_info.rom_id || rom_info.game_code
+      set_card_image(card, key, dest)
+    end
+
+    def set_card_image(card, key, path)
+      # Load full-size photo, scale to fit within IMG_SIZE, delete the original.
+      # Subsample factor is computed from actual dimensions so arbitrary-sized
+      # user images (e.g. custom boxart) don't break the card layout.
+      full_name  = "boxart_full_#{key}"
+      small_name = "boxart_#{key}"
+
+      @app.command(:image, :create, :photo, full_name, file: path)
+      w = @app.tcl_eval("image width #{full_name}").to_i
+      h = @app.tcl_eval("image height #{full_name}").to_i
+      factor = [[(w.to_f / IMG_SIZE).ceil, (h.to_f / IMG_SIZE).ceil].max, 1].max
+
+      @app.command(:image, :create, :photo, small_name)
+      @app.command(small_name, :copy, full_name, subsample: factor)
+      @app.command(:image, :delete, full_name)
+
+      old = @photos[key]
+      @photos[key] = small_name
+      @app.command(card[:image], :configure, image: small_name)
+      @app.command(:image, :delete, old) if old && old != small_name
+    rescue => e
+      Gemba.log(:warn) { "BoxArt image load failed for #{key}: #{e.message}" }
+    end
+  end
+end

data/lib/gemba/gamepad_map.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Manages SDL gamepad button → GBA bitmask mappings.
+  #
+  # Shares the same interface as {KeyboardMap} so that Player can
+  # delegate to either without knowing which device type is active.
+  class GamepadMap
+    DEFAULT_MAP = {
+      a:              KEY_A,
+      b:              KEY_B,
+      back:           KEY_SELECT,
+      start:          KEY_START,
+      dpad_up:        KEY_UP,
+      dpad_down:      KEY_DOWN,
+      dpad_left:      KEY_LEFT,
+      dpad_right:     KEY_RIGHT,
+      left_shoulder:  KEY_L,
+      right_shoulder: KEY_R,
+    }.freeze
+
+    DEFAULT_DEAD_ZONE = 8000
+
+    def initialize(config)
+      @config = config
+      @map = DEFAULT_MAP.dup
+      @device = nil
+      @dead_zone = DEFAULT_DEAD_ZONE
+    end
+
+    attr_accessor :device
+    attr_reader :dead_zone
+
+    def mask
+      return 0 unless @device && !@device.closed?
+      m = 0
+      @map.each { |btn, bit| m |= bit if @device.button?(btn) }
+      m
+    end
+
+    def set(gba_btn, gp_btn)
+      bit = GBA_BTN_BITS[gba_btn] or return
+      @map.delete_if { |_, v| v == bit }
+      @map[gp_btn] = bit
+    end
+
+    def reset!
+      @map = DEFAULT_MAP.dup
+      @dead_zone = DEFAULT_DEAD_ZONE
+    end
+
+    def load_config
+      return unless @device
+      guid = @device.guid rescue return
+      gp_cfg = @config.gamepad(guid, name: @device.name)
+
+      @map = {}
+      gp_cfg['mappings'].each do |gba_str, gp_str|
+        bit = GBA_BTN_BITS[gba_str.to_sym]
+        next unless bit
+        @map[gp_str.to_sym] = bit
+      end
+
+      pct = gp_cfg['dead_zone']
+      @dead_zone = (pct / 100.0 * 32767).round
+    end
+
+    def reload!
+      @config.reload!
+      load_config
+    end
+
+    def labels
+      result = {}
+      @map.each do |input, bit|
+        gba_btn = GBA_BTN_BITS.key(bit)
+        result[gba_btn] = input.to_s if gba_btn
+      end
+      result
+    end
+
+    def save_to_config
+      return unless @device
+      guid = @device.guid rescue return
+      @config.gamepad(guid, name: @device.name)
+      @config.set_dead_zone(guid, dead_zone_pct)
+      @map.each do |gp_btn, bit|
+        gba_btn = GBA_BTN_BITS.key(bit)
+        @config.set_mapping(guid, gba_btn, gp_btn) if gba_btn
+      end
+    end
+
+    def supports_deadzone? = true
+
+    def dead_zone_pct
+      (@dead_zone.to_f / 32767 * 100).round
+    end
+
+    def set_dead_zone(threshold)
+      @dead_zone = threshold.to_i
+    end
+  end
+end

data/lib/gemba/headless.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-# Lightweight entry point for headless (no GUI) usage of gemba.
-# Loads only the C extension and pure-Ruby modules — no Tk, no SDL2.
+# Lightweight entry point — Tk and SDL2 are NOT loaded.
 #
 #   require "gemba/headless"
 #   Gemba::HeadlessPlayer.open("game.gba") { |p| p.step(60) }
 
 require_relative "runtime"
-require_relative "recorder"
-require_relative "recorder_decoder"
-require_relative "headless_player"
+
+module Gemba
+  # Marker — signals the headless stack is loaded without Tk/SDL2.
+  module Headless; end
+end

data/lib/gemba/headless_player.rb

@@ -15,16 +15,19 @@ module Gemba
   class HeadlessPlayer
     # @param rom_path [String] path to ROM file (.gba, .gb, .gbc, .zip)
     # @param config [Config, nil] config object (uses default if nil)
-    def initialize(rom_path, config: nil)
+    def initialize(rom_path, config: nil, bios_path: nil)
       @config = config || Gemba.user_config
-      rom_path = RomLoader.resolve(rom_path)
+      rom_path = RomResolver.resolve(rom_path)
 
       saves = @config.saves_dir
       FileUtils.mkdir_p(saves) unless File.directory?(saves)
-      @core = Core.new(rom_path, saves)
+      @core = Core.new(rom_path, saves, bios_path)
       @keys = 0
     end
 
+    # @return [Core] the underlying mGBA core
+    attr_reader :core
+
     # Open a HeadlessPlayer, yield it, and close when done.
     # @param rom_path [String]
     # @param opts [Hash] passed to {#initialize}
@@ -166,7 +169,9 @@ module Gemba
     def start_recording(path, compression: Zlib::BEST_SPEED)
       check_open!
       raise "Already recording" if recording?
+      platform = Platform.for(@core)
       @recorder = Recorder.new(path, width: @core.width, height: @core.height,
+                               fps_fraction: platform.fps_fraction,
                                compression: compression)
       @recorder.start
     end
@@ -184,6 +189,31 @@ module Gemba
 
     # @!endgroup
 
+    # @!group Input replay
+
+    # Replay a .gir input recording. Loads the anchor save state, validates
+    # the ROM checksum, then feeds each recorded bitmask to the core.
+    #
+    # @param gir_path [String] path to .gir file
+    # @yield [Integer, Integer] bitmask and zero-based frame index after each frame
+    # @return [Integer] number of frames replayed
+    def replay(gir_path)
+      check_open!
+      replayer = InputReplayer.new(gir_path)
+      replayer.validate!(@core)
+      @core.load_state_from_file(replayer.anchor_state_path)
+
+      replayer.each_bitmask do |mask, idx|
+        @core.set_keys(mask)
+        @core.run_frame
+        yield mask, idx if block_given?
+      end
+
+      replayer.frame_count
+    end
+
+    # @!endgroup
+
     # Shut down the core and free resources.
     def close
       return if closed?