pyjch 0.1.0__py3-none-any.whl

pyjch/__init__.py

@@ -0,0 +1,30 @@
+"""Read and play JCH NewPlayer SID songs (byte-exact register output)."""
+
+from pyjch.errors import JCHError, SidParseError
+from pyjch.model import Song
+from pyjch.player import Player, iter_frames, render_grid
+from pyjch.reader import parse, read
+from pyjch.reglog import (
+    RegWrite,
+    iter_register_writes,
+    read_reglog,
+    write_reglog,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JCHError",
+    "Player",
+    "RegWrite",
+    "SidParseError",
+    "Song",
+    "__version__",
+    "iter_frames",
+    "iter_register_writes",
+    "parse",
+    "read",
+    "read_reglog",
+    "render_grid",
+    "write_reglog",
+]

pyjch/cli.py

@@ -0,0 +1,64 @@
+"""Command line interface: song info and register logs."""
+
+import argparse
+import sys
+
+from pyjch import reglog
+from pyjch.errors import JCHError
+from pyjch.reader import read
+
+
+def _info(args) -> None:
+    song = read(args.song)
+    print(f"name:        {song.name}")
+    print(f"author:      {song.author}")
+    print(f"released:    {song.released}")
+    print(f"load:        ${song.load_addr:04X}")
+    print(f"init/play:   ${song.init_addr:04X} / ${song.play_addr:04X}")
+    print(f"AD/SR:       ${song.init_ad:02X} / ${song.init_sr:02X}")
+    print(f"gate on/off: ${song.gate_ctrl:02X} / ${song.gateoff_ctrl:02X}")
+    print(f"subptr lo/hi:${song.subptr_lo:04X} / ${song.subptr_hi:04X}")
+    for voice in range(3):
+        addr = song.orderlist_ptr(0, voice)
+        print(f"  voice {voice}: orderlist @ ${addr:04X}")
+
+
+def _reglog(args) -> None:
+    song = read(args.song)
+    frames = round(args.seconds * 50)
+    writes = reglog.iter_register_writes(song, max_frames=frames)
+    reglog.write_reglog(writes, args.output)
+    print(f"wrote {args.output}")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pyjch", description="JCH NewPlayer song tools"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    info = commands.add_parser("info", help="print song metadata")
+    info.add_argument("song", help="JCH NewPlayer .sid/.prg file")
+    info.set_defaults(func=_info)
+
+    log = commands.add_parser("reglog", help="write a SID register log")
+    log.add_argument("song", help="JCH NewPlayer .sid/.prg file")
+    log.add_argument("output", help="register log file to write")
+    log.add_argument("--seconds", type=float, default=60.0)
+    log.set_defaults(func=_reglog)
+    return parser
+
+
+def main(argv=None) -> int:
+    """CLI entry point; returns a process exit code."""
+    args = _parser().parse_args(argv)
+    try:
+        args.func(args)
+    except (JCHError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyjch/constants.py

@@ -0,0 +1,86 @@
+"""Constants for the JCH NewPlayer and song format.
+
+Values follow the reverse-engineered JCH NewPlayer
+(``re-trackers/JCH_NewPlayer/{decompile.c,disasm.asm}``), cross-checked
+byte-exact against the ``preframr-sidtrace`` register oracle.  The player
+code is identical across JCH tunes; only its DATA (orderlists, subpatterns,
+instruments, frequency tables and the addresses they live at) differs per
+tune, so the reader DISCOVERS each per-tune immediate and table base from
+the player code's 16-bit operands (relocation-safe -- no fixed-address
+assumption).
+"""
+
+# SID register map.
+SID_REGISTERS = 25
+VOICES = 3
+VOICE_REG_SIZE = 7
+
+# Per-voice SID base offsets ($D400 + offset).
+SID_OFFSET = (0, 7, 14)
+
+# Pulse-width high registers carry only their low nibble (12-bit pulse).
+PW_HI_REGS = (0x03, 0x0A, 0x11)
+
+# Per-tune operand offsets-from-load.  The player binary is identical
+# across JCH tunes, so each per-tune immediate / pointer-table base lives
+# at a fixed offset in the code; the reader reads the byte (or 16-bit
+# operand) there to discover the per-tune value (relocation-safe).
+OP_INIT_AD = 0x0AA  # LDA #imm @ $10AA -> attack/decay default
+OP_INIT_SR = 0x0B5  # LDA #imm @ $10B5 -> sustain/release default
+OP_GATEOFF_CTRL = 0x199  # LDA #imm @ $1198 -> gate-off / rest CTRL
+OP_GATE_CTRL = 0x1E1  # LDA #imm @ $11E0 -> gate-on CTRL
+OP_SUBPTR_LO = 0x12C  # LDA abs,Y operand @ $112B -> subpattern ptr lo base
+OP_SUBPTR_HI = 0x131  # LDA abs,Y operand @ $1130 -> subpattern ptr hi base
+
+# Fixed in-image work / data addresses the player reads (absolute, relative
+# to load; the player binary places them at the same offsets across tunes).
+ORDERLIST_PTR_TABLE = 0x010  # $1010: per-subtune orderlist ptr pairs (8/subtune)
+FREQ_LO = 0x21F  # $121F: note frequency table, low bytes (0x80 entries)
+FREQ_HI = 0x220  # $1220: note frequency table, high bytes
+FREQ_TABLE_LEN = 0x80
+
+# Per-voice transpose / detune immediates the play routine indexes by X.
+VOICE_TRANSPOSE = 0x00A  # $100A,X : per-voice arp/transpose base byte
+VOICE_DETUNE = 0x00D  # $100D,X : per-voice frequency add (detune)
+
+# Player work-RAM addresses (the play routine's $..,X arrays).  Init writes
+# only a handful; the rest keep their loaded-image value.
+WORK_CUR_PTR_LO = 0x2DF  # $12DF,X : current opcode-stream pointer, low
+WORK_CUR_PTR_HI = 0x2E2  # $12E2,X : current opcode-stream pointer, high
+WORK_BASE_PTR_LO = 0x2E5  # $12E5,X : orderlist base pointer, low
+WORK_BASE_PTR_HI = 0x2E8  # $12E8,X : orderlist base pointer, high
+WORK_SAVE_PTR_LO = 0x2EB  # $12EB,X : saved (pushed) pointer, low
+WORK_SAVE_PTR_HI = 0x2EE  # $12EE,X : saved (pushed) pointer, high
+WORK_SID_OFFSET = 0x2F1  # $12F1,X : SID voice register offset (0,7,14)
+WORK_TEMPO = 0x2F4  # $12F4 / $12F5 : tempo counter / reload
+WORK_GATE_CTR = 0x2F9  # $12F9,X : per-voice gate-delay counter
+WORK_GATE_RELOAD = 0x2F6  # $12F6,X : per-voice gate-delay reload
+WORK_GATE_FLAG = 0x2FC  # $12FC,X : gate-this-frame flag
+WORK_FREQ_LO = 0x2FF  # $12FF,X : computed FREQ_LO
+WORK_FREQ_HI = 0x302  # $1302,X : computed FREQ_HI
+WORK_TRANSPOSE = 0x305  # $1305,X : current transpose offset
+WORK_SUBPAT_DEPTH = 0x308  # $1308,X : in-subpattern flag/depth
+
+# Default subtune orderlist-pointer index (the 7th pair feeds the tempo).
+TEMPO_PTR_INDEX = 0x2F4
+
+# Zero-page opcode-stream pointer used by the play routine.
+ZP_PTR_LO = 0xFB
+ZP_PTR_HI = 0xFC
+
+# SID register init values written by the JCH init routine.
+INIT_CTRL = 0x88  # $D404/$D40B/$D412
+INIT_PW_HI_V0 = 0x04  # $D403
+INIT_PW_HI_V12 = 0x01  # $D40A / $D411
+INIT_VOLUME = 0x0F  # $D418
+
+# C64 timing.  A PAL frame is 312 rasterlines x 63 cycles.
+PAL_CLOCK_HZ = 985248
+PAL_CYCLES_PER_FRAME = 19656
+NTSC_CLOCK_HZ = 1022727
+NTSC_CYCLES_PER_FRAME = 17095
+
+# Standard JCH NewPlayer entry points (PSID header normally matches).
+DEFAULT_LOAD = 0x1000
+DEFAULT_INIT = 0x1060
+DEFAULT_PLAY = 0x10E8

pyjch/errors.py

@@ -0,0 +1,9 @@
+"""Exceptions raised by pyjch."""
+
+
+class JCHError(Exception):
+    """Base class for all pyjch errors."""
+
+
+class SidParseError(JCHError):
+    """A PSID/RSID/PRG image (or byte string) could not be parsed."""

pyjch/model.py

@@ -0,0 +1,80 @@
+"""Typed model of a JCH NewPlayer song.
+
+A :class:`Song` holds everything the reader recovers from a JCH tune
+image: the per-tune discovered immediates (the AD/SR defaults and the
+gate-on / gate-off CTRL bytes), the relocated subpattern pointer-table
+bases, the per-subtune orderlist pointer pairs, the split note-frequency
+tables, and the raw whole-image bytes.  The player reads the opcode
+streams (orderlists + subpatterns) directly out of ``image`` via the
+discovered addresses, exactly as the 6502 player does, so a relocated
+tune of the same player plays unchanged.
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+from pyjch import constants
+
+
+@dataclass
+class Song:
+    """A complete JCH NewPlayer song.
+
+    ``load_addr`` is the C64 load address; ``image`` the raw whole-image
+    bytes (player + data).  ``init_ad`` / ``init_sr`` are the discovered
+    attack-decay / sustain-release defaults; ``gate_ctrl`` / ``gateoff_ctrl``
+    the discovered gate-on / gate-off (rest) CTRL bytes; ``subptr_lo`` /
+    ``subptr_hi`` the (relocated) subpattern pointer-table base addresses;
+    ``orderlist_ptr_table`` the absolute base of the per-subtune orderlist
+    pointer pairs; ``freq_lo`` / ``freq_hi`` the split note-frequency
+    tables.
+    """
+
+    # pylint: disable=too-many-instance-attributes  # a full tune is wide
+    load_addr: int = constants.DEFAULT_LOAD
+    init_addr: int = constants.DEFAULT_INIT
+    play_addr: int = constants.DEFAULT_PLAY
+    name: str = ""
+    author: str = ""
+    released: str = ""
+    # Per-tune discovered immediates.
+    init_ad: int = 0
+    init_sr: int = 0
+    gate_ctrl: int = 0
+    gateoff_ctrl: int = 0
+    # Per-tune discovered (relocated) table bases (absolute addresses).
+    subptr_lo: int = 0
+    subptr_hi: int = 0
+    orderlist_ptr_table: int = constants.DEFAULT_LOAD + constants.ORDERLIST_PTR_TABLE
+    # Split note-frequency tables.
+    freq_lo: List[int] = field(default_factory=list)
+    freq_hi: List[int] = field(default_factory=list)
+    # Raw whole-image bytes (player + data) the player reads opcode streams
+    # and pointer tables out of, via the discovered addresses.
+    image: bytes = b""
+    # The original container header (PSID/RSID bytes before the image), kept
+    # for reference; empty for a bare ``.prg``.
+    container_header: bytes = b""
+
+    def orderlist_ptr(self, subtune: int, voice: int) -> int:
+        """Absolute address of ``voice``'s orderlist for ``subtune``.
+
+        The init routine indexes the pointer table by ``subtune * 8`` and
+        reads three consecutive 2-byte pairs (one per voice).
+        """
+        base = self.orderlist_ptr_table + (subtune << 3) + voice * 2
+        lo = self._byte(base)
+        hi = self._byte(base + 1)
+        return lo | (hi << 8)
+
+    def subpattern_ptr(self, index: int) -> int:
+        """Absolute address of subpattern ``index`` (0-127)."""
+        lo = self._byte(self.subptr_lo + index)
+        hi = self._byte(self.subptr_hi + index)
+        return lo | (hi << 8)
+
+    def _byte(self, abs_addr: int) -> int:
+        idx = abs_addr - self.load_addr
+        if 0 <= idx < len(self.image):
+            return self.image[idx]
+        return 0

pyjch/player.py

@@ -0,0 +1,300 @@
+"""JCH NewPlayer playroutine in Python.
+
+A faithful, byte-exact transcription of the JCH NewPlayer's init
+(``FUN_1060``) and play (``FUN_10e8``) routines, recovered from the
+player's disassembly (``re-trackers/JCH_NewPlayer/disasm.asm``) and
+validated byte-exact against the ``preframr-sidtrace`` register oracle.
+
+The transcription keeps full 6502 semantics: a 64K memory image (the
+player walks per-voice opcode streams via the zero-page pointer
+``$fb/$fc``, reads its work-RAM and pointer tables out of the loaded
+image, and writes the SID registers into ``$D400..``).  The per-tune
+ADDRESSES and immediates it operates on are discovered by the reader, so
+a relocated tune of the same player plays unchanged.
+
+Each :meth:`Player.play_frame` call runs one frame and returns the SID
+register writes for that frame as ``(register, value)`` pairs in
+ascending register order (all 25 on the first frame, only changed
+registers afterwards).
+"""
+
+from typing import List, Optional
+
+from pyjch import constants
+from pyjch.model import Song
+
+_D400 = 0xD400
+
+
+class Player:
+    """Play a :class:`~pyjch.model.Song` one frame at a time."""
+
+    # pylint: disable=too-many-instance-attributes  # full player machine state
+    def __init__(self, song: Song, subtune: int = 0):
+        self._song = song
+        self._load = song.load_addr
+        # 64K memory; place the image at its load address.
+        self._mem = bytearray(0x10000)
+        for i, byte in enumerate(song.image):
+            self._mem[(self._load + i) & 0xFFFF] = byte
+        # Per-tune discovered values (already resolved by the reader).
+        self._init_ad = song.init_ad
+        self._init_sr = song.init_sr
+        self._gate_ctrl = song.gate_ctrl
+        self._gateoff_ctrl = song.gateoff_ctrl
+        self._subptr_lo = song.subptr_lo
+        self._subptr_hi = song.subptr_hi
+        self.regs = [0] * constants.SID_REGISTERS
+        self._last_regs: Optional[List[int]] = None
+        self._init(subtune)
+
+    # -- raw memory access -----------------------------------------------
+    def _rd(self, addr: int) -> int:
+        return self._mem[addr & 0xFFFF]
+
+    def _wr(self, addr: int, val: int) -> None:
+        self._mem[addr & 0xFFFF] = val & 0xFF
+
+    # -- init: FUN_1060(subtune) -----------------------------------------
+    def _init(self, subtune: int = 0) -> None:
+        m = self._mem
+        load = self._load
+        # Y = subtune*8; loop X=0..2 copying orderlist ptr pairs into the
+        # per-voice cur/base pointers.
+        y = (subtune << 3) & 0xFF
+        for x in range(3):
+            uvar = m[(load + constants.ORDERLIST_PTR_TABLE + y) & 0xFFFF]
+            m[(load + constants.WORK_CUR_PTR_LO + x) & 0xFFFF] = uvar
+            m[(load + constants.WORK_BASE_PTR_LO + x) & 0xFFFF] = uvar
+            uvar = m[(load + constants.ORDERLIST_PTR_TABLE + y + 1) & 0xFFFF]
+            m[(load + constants.WORK_CUR_PTR_HI + x) & 0xFFFF] = uvar
+            m[(load + constants.WORK_BASE_PTR_HI + x) & 0xFFFF] = uvar
+            y = (y + 2) & 0xFF
+        # Tempo reload from the 7th pair byte.
+        m[(load + constants.WORK_TEMPO) & 0xFFFF] = m[
+            (load + constants.ORDERLIST_PTR_TABLE + y) & 0xFFFF
+        ]
+        m[(load + constants.WORK_TEMPO + 1) & 0xFFFF] = m[
+            (load + constants.WORK_TEMPO) & 0xFFFF
+        ]
+        for x in range(6):
+            m[(load + 0x305 + x) & 0xFFFF] = 0
+        for x in range(0x19):
+            m[(_D400 + x) & 0xFFFF] = 0
+        m[_D400 + 0x04] = constants.INIT_CTRL
+        m[_D400 + 0x0B] = constants.INIT_CTRL
+        m[_D400 + 0x12] = constants.INIT_CTRL
+        m[_D400 + 0x05] = self._init_ad
+        m[_D400 + 0x0C] = self._init_ad
+        m[_D400 + 0x13] = self._init_ad
+        m[_D400 + 0x06] = self._init_sr
+        m[_D400 + 0x0D] = self._init_sr
+        m[_D400 + 0x14] = self._init_sr
+        m[_D400 + 0x03] = constants.INIT_PW_HI_V0
+        m[_D400 + 0x0A] = constants.INIT_PW_HI_V12
+        m[_D400 + 0x11] = constants.INIT_PW_HI_V12
+        m[_D400 + 0x18] = constants.INIT_VOLUME
+        for x in range(3):
+            m[(load + constants.WORK_GATE_CTR + x) & 0xFFFF] = 0xFF
+            m[(load + constants.WORK_GATE_RELOAD + x) & 0xFFFF] = 0x03
+        self._snapshot_regs()
+
+    # -- play: FUN_10e8 --------------------------------------------------
+    def _frame(self) -> None:
+        load = self._load
+        rd = self._rd
+        wr = self._wr
+
+        x = 2
+        while True:
+            # 10f0: load cur ptr for voice X into the zero-page pointer.
+            wr(constants.ZP_PTR_LO, rd(load + constants.WORK_CUR_PTR_LO + x))
+            wr(constants.ZP_PTR_HI, rd(load + constants.WORK_CUR_PTR_HI + x))
+            a = rd(load + constants.WORK_GATE_CTR + x)  # gate-delay counter
+            if a & 0x80:  # BMI -> LAB_110a (a < 0)
+                self._note_advance(x)
+            else:
+                wr(load + constants.WORK_GATE_FLAG + x, 1)
+            # 11d7:
+            if rd(load + constants.WORK_GATE_FLAG + x) == 0:
+                wr(
+                    _D400 + 0x04 + rd(load + constants.WORK_SID_OFFSET + x),
+                    self._gate_ctrl,
+                )
+            # 11e5:
+            yreg = rd(load + constants.WORK_SID_OFFSET + x)
+            wr(_D400 + yreg, rd(load + constants.WORK_FREQ_LO + x))
+            wr(_D400 + 0x01 + yreg, rd(load + constants.WORK_FREQ_HI + x))
+            wr(load + constants.WORK_CUR_PTR_LO + x, rd(constants.ZP_PTR_LO))
+            wr(load + constants.WORK_CUR_PTR_HI + x, rd(constants.ZP_PTR_HI))
+            x = (x - 1) & 0xFF
+            if x & 0x80:  # BMI 1204
+                break
+        # 1204: tempo divider; on wrap, decrement the per-voice gate counters.
+        tempo = (rd(load + constants.WORK_TEMPO) - 1) & 0xFF
+        wr(load + constants.WORK_TEMPO, tempo)
+        if tempo != 0:
+            return
+        wr(load + constants.WORK_TEMPO, rd(load + constants.WORK_TEMPO + 1))
+        for off in range(3):
+            wr(
+                load + constants.WORK_GATE_CTR + off,
+                (rd(load + constants.WORK_GATE_CTR + off) - 1) & 0xFF,
+            )
+
+    def _ptr_get(self) -> int:
+        return self._rd(constants.ZP_PTR_LO) | (self._rd(constants.ZP_PTR_HI) << 8)
+
+    def _inc_fb(self) -> None:
+        v = (self._rd(constants.ZP_PTR_LO) + 1) & 0xFF
+        self._wr(constants.ZP_PTR_LO, v)
+        if v == 0:
+            self._wr(constants.ZP_PTR_HI, (self._rd(constants.ZP_PTR_HI) + 1) & 0xFF)
+
+    def _note_advance(self, x: int) -> None:
+        # pylint: disable=too-many-statements,too-many-branches  # 6502 label graph
+        load = self._load
+        rd = self._rd
+        wr = self._wr
+        bvar1 = 0  # latched between labels (the 6502 accumulator)
+        pc = "110a"
+        while True:
+            if pc == "110a":
+                wr(
+                    load + constants.WORK_GATE_CTR + x,
+                    rd(load + constants.WORK_GATE_RELOAD + x),
+                )
+                pc = "1110"
+            elif pc == "1110":
+                pc = (
+                    "1118"
+                    if rd(load + constants.WORK_SUBPAT_DEPTH + x) == 0
+                    else "1163"
+                )
+            elif pc == "1118":
+                bvar1 = rd(self._ptr_get())  # LDA (fb),Y  Y=0
+                if bvar1 < 0x80:  # CMP #$80; BPL 113b -> else (<$80) fallthrough
+                    # 1120: subpattern-ref; push cur ptr, jump via subptr tables.
+                    yidx = bvar1
+                    wr(load + constants.WORK_SAVE_PTR_LO + x, rd(constants.ZP_PTR_LO))
+                    wr(load + constants.WORK_SAVE_PTR_HI + x, rd(constants.ZP_PTR_HI))
+                    wr(constants.ZP_PTR_LO, rd(self._subptr_lo + yidx))
+                    wr(constants.ZP_PTR_HI, rd(self._subptr_hi + yidx))
+                    wr(
+                        load + constants.WORK_SUBPAT_DEPTH + x,
+                        (rd(load + constants.WORK_SUBPAT_DEPTH + x) + 1) & 0xFF,
+                    )
+                    pc = "1163"
+                else:  # 113b
+                    if (bvar1 & 0xE0) != 0x80:  # BNE 1155
+                        pc = "1155"
+                    else:
+                        v = (((bvar1 & 0x1F) - 0x0C) << 1) & 0xFF
+                        wr(load + constants.WORK_TRANSPOSE + x, v)
+                        self._inc_fb()
+                        pc = "1118"
+            elif pc == "1155":
+                wr(constants.ZP_PTR_LO, rd(load + constants.WORK_BASE_PTR_LO + x))
+                wr(constants.ZP_PTR_HI, rd(load + constants.WORK_BASE_PTR_HI + x))
+                pc = "110a"
+            elif pc == "1163":
+                bvar1 = rd(self._ptr_get())
+                if bvar1 >= 0x80:  # BPL 11a5 -> else (>=$80)
+                    pc = "11a5"
+                else:
+                    c = (bvar1 << 1) & 0xFF  # ASL A
+                    if c == 0:  # BEQ 1195
+                        pc = "1195"
+                    elif c == 0xFE:  # CMP #$fe; BEQ 119d
+                        pc = "119d"
+                    else:
+                        bv2 = (
+                            c
+                            + rd(load + constants.VOICE_TRANSPOSE + x)
+                            + rd(load + constants.WORK_TRANSPOSE + x)
+                        ) & 0xFF
+                        lo = rd(load + constants.FREQ_LO + bv2)
+                        add = rd(load + constants.VOICE_DETUNE + x)
+                        s = lo + add
+                        wr(load + constants.WORK_FREQ_LO + x, s & 0xFF)
+                        hi = rd(load + constants.FREQ_HI + bv2)
+                        wr(
+                            load + constants.WORK_FREQ_HI + x,
+                            (hi + (1 if s > 0xFF else 0)) & 0xFF,
+                        )
+                        wr(load + constants.WORK_GATE_FLAG + x, 0)
+                        pc = "11d1"
+            elif pc == "1195":
+                wr(
+                    _D400 + 0x04 + rd(load + constants.WORK_SID_OFFSET + x),
+                    self._gateoff_ctrl,
+                )
+                pc = "119d"
+            elif pc == "119d":
+                wr(load + constants.WORK_GATE_FLAG + x, 1)
+                pc = "11d1"
+            elif pc == "11a5":
+                if (bvar1 & 0xF0) == 0x80:  # BNE 11b8 -> else (==$80)
+                    val = bvar1 & 0x0F
+                    wr(load + constants.WORK_GATE_CTR + x, val)
+                    wr(load + constants.WORK_GATE_RELOAD + x, val)
+                    pc = "11c8"
+                else:
+                    pc = "11b8"
+            elif pc == "11b8":
+                wr(load + constants.WORK_SUBPAT_DEPTH + x, 0)
+                wr(constants.ZP_PTR_LO, rd(load + constants.WORK_SAVE_PTR_LO + x))
+                wr(constants.ZP_PTR_HI, rd(load + constants.WORK_SAVE_PTR_HI + x))
+                pc = "11c8"
+            elif pc == "11c8":
+                self._inc_fb()
+                pc = "1110"
+            elif pc == "11d1":
+                self._inc_fb()
+                return
+
+    # -- frame output / public API ---------------------------------------
+    def _snapshot_regs(self) -> None:
+        self.regs = [self._mem[_D400 + i] for i in range(constants.SID_REGISTERS)]
+
+    def play_frame(self) -> List[tuple]:
+        """Run one player tick; return this frame's SID register writes.
+
+        The first frame returns all 25 registers; later frames return only
+        registers whose value changed.
+        """
+        self._frame()
+        self._snapshot_regs()
+        if self._last_regs is None:
+            writes = list(enumerate(self.regs))
+        else:
+            writes = [
+                (reg, value)
+                for reg, (value, last) in enumerate(zip(self.regs, self._last_regs))
+                if value != last
+            ]
+        self._last_regs = list(self.regs)
+        return writes
+
+
+def iter_frames(song: Song, max_frames: Optional[int] = None):
+    """Yield per-frame register write lists for ``song``.
+
+    Stops after ``max_frames`` frames (required for a non-looping render,
+    since the JCH player loops forever).
+    """
+    player = Player(song)
+    frame = 0
+    while max_frames is None or frame < max_frames:
+        yield player.play_frame()
+        frame += 1
+
+
+def render_grid(song: Song, nframes: int) -> List[List[int]]:
+    """Render ``nframes`` of forward-filled per-frame register snapshots."""
+    player = Player(song)
+    rows: List[List[int]] = []
+    for _ in range(nframes):
+        player.play_frame()
+        rows.append(player.regs[:])
+    return rows