pysidwizard

Pure-Python reader, writer, and bit-exact player for SID-Wizard (Hermit / Mihaly Horvath) C64 tracker modules. Implements the SWM file format and player IRQ from first principles, with no native dependencies. The player is validated byte-for-byte against the anarkiwi/sidtrace sidplayfp oracle over real HVSC SID-Wizard exports (pytest -m oracle, needs Docker).

Also consumes .sid files (PSID/RSID containers) and bare .prg images through the shared pysidtracker base: SID-Wizard .sid exports (plain or packed SWP) are read into the same SWMFile model, packed/relocating builds are detected, and container headers are not trusted. Standalone packed .swp files (SWP1) are read with the same decodable fidelity. The .sid/.swp paths are read-only and lossy (see docs/format.md).

Install

pip install pysidwizard

Usage

from pysidwizard import read_swm, write_swm, build_swm

swm = read_swm("tune.swm")            # native SID-Wizard module (bare or PRG-wrapped)
print(swm.author_str(), swm.frame_speed, swm.highlight)

for row in swm.patterns[0].rows[:4]:  # typed rows; no byte poking
    print(row)

write_swm(swm, "out.swm")             # byte-exact round-trip

# SID-Wizard tunes exported to .sid read into the same model:
from pysidwizard import read_sid
swm_from_sid = read_sid("tune.sid")   # read-only, lossy

# ...as do standalone packed .swp files (SWP1):
from pysidwizard import read_swp
swm_from_swp = read_swp("tune.swp")   # read-only, lossy

See docs/usage.md for building modules from scratch, playback, WAV rendering, raw write iteration, and the CLI, and docs/format.md for the SWM/.sid/.swp format, data model, and player correctness. The HVSC oracle survey runs the player against every HVSC SID-Wizard tune.

Development

pip install -e ".[dev]"
python -m pytest                                   # unit tests (fast, no Docker)
python -m pytest -m oracle                          # sidtrace oracle; requires Docker

The four SWM test tunes are not tracked in this repo (SID-Wizard binary artifacts); tests/_swm_cache.py fetches them on demand and SHA-256 verifies each one.

License

Apache 2.0 — see LICENSE.