pysidtracker 0.4.0

Shared base for pure-Python C64 SID tracker parsers: PSID/RSID container, loaded-image model, and packed/relocating playroutine detection

pysidtracker

Shared base for the pure-Python C64 SID tracker parsers (pygoattracker, pysidwizard, pydmcsid, pyfuturecomposer, pymusicassembler, pydefmon, pyjch, pysoundmonitor).

Reads .sid containers (PSID/RSID) and bare .prg images into a 64 KiB C64 memory model, and detects packed/relocating playroutines by running the tune's init in a 6502 emulator — container headers are not trusted. Each format package subclasses BaseSidParser for a consistent read / parse / detect API.

Components

• parse_sid_header / SidHeader — PSID/RSID container header parsing.
• SidImage — a loaded 64 KiB C64 memory image with absolute-addressed accessors, from a .sid container or a bare .prg.
• read_bytes — path / bytes / file-like source dispatch.
• SidError hierarchy — SidParseError, SidFormatError, EmulatorUnavailable.
• detect_playroutine / PlayroutineKind — static signature recognition, then an emulated init run to classify DIRECT / RELOCATED / PACKED / UNKNOWN.
• BaseSidParser — the base class each format subclasses.
• CodePattern / find_code_all / find_code_first — masked 6502 code-fragment search with operand capture.
• registers — C64 hardware register map (SID/CIA/VIC, IRQ/NMI and CPU vectors) with predicates and find_register_stores.
• trace_init / InitTrace — run a tune's init under a write observer to report CIA timer cadence and the IRQ/NMI vectors an IRQ-driven header hides.
• playroutine_cadence / Cadence / TriggerSource — derive the play-routine cadence (PAL/NTSC video frame vs CIA-timer latch) from what init programs, not the header.
• native_decrunch — native exomizer unpack (pydexomizer), an init-free alternative depack path; opt-in via detect_playroutine(..., native=True).
• reglog — RegWrite register-log format (read_reglog / write_reglog) and frame_writes, the shared per-frame SID-write framing loop.
• oracle — per-frame SID register grids: register_grid (py65), the stdlib grid_from_writes framer, read_sidwr (preframr-sidtrace .sidwr.bin), and aligned_match.
• testing — HVSC tune fetch/resolve for test suites (fetch_tune, resolve_tune, make_tune_fixtures).
• audio — render_samples / render_wav through an emulated SID (pyresidfp, audio extra).

Install

pip install pysidtracker          # core (includes py65 for init emulation)
pip install pysidtracker[fast]    # + numpy, to accelerate the image scan
pip install pysidtracker[audio]   # + pyresidfp, for WAV/sample rendering

py65 and pydexomizer are required core dependencies (detection runs a tune's 6502 init, and native_decrunch unpacks exomizer-packed images natively). numpy is optional; a pure-stdlib scan is used when it is absent.

Usage

from pysidtracker import BaseSidParser, PlayroutineKind

class MyParser(BaseSidParser):
    def recognize(self, image):
        return image.find(b"MYSIG")            # truthy anchor when found
    def parse(self, data, **kw):
        image = self.load_image(data)          # .sid or .prg -> SidImage
        ...                                    # decode image.mem into a model

det = MyParser().detect("tune.sid")
if det.kind is PlayroutineKind.PACKED:
    ...                                        # header was not trustworthy

Development

pip install -e ".[dev]"
pytest --cov=pysidtracker

See docs/design.md for the detection model and shared primitives, and docs/adoption.md for how the format packages consume this base.

License

Apache 2.0 — see LICENSE.