Metadata-Version: 2.4
Name: sidwizard-driver
Version: 0.4.0
Summary: Python automation harness for driving SID-Wizard inside asid-vice — captures per-frame SID register writes from the real 6502 player.
Author: anarkiwi
License: Apache-2.0
Project-URL: Homepage, https://github.com/anarkiwi/sidwizard-driver
Project-URL: Issues, https://github.com/anarkiwi/sidwizard-driver/issues
Project-URL: Source, https://github.com/anarkiwi/sidwizard-driver
Keywords: c64,commodore-64,sid-wizard,sidwizard,vice,asid-vice,sid,music,emulator,automation,binary-monitor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vice-driver>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pyright>=1.1.350; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Dynamic: license-file

# sidwizard-driver

Python harness that drives [SID-Wizard](https://csdb.dk/release/?id=258573)
inside [asid-vice](https://github.com/anarkiwi/asid-vice) and captures
per-frame SID register writes from its real 6502 player. Output is a
deduplicated `(frame, reg, value)` CSV — ground truth for verifying
pure-Python SWM players like
[pysidwizard](https://github.com/anarkiwi/pysidwizard).

Built on [vice-driver](https://pypi.org/project/vice-driver/).

## Install

```
pip install sidwizard-driver
```

Requires Docker (or compatible) and the `asid-vice:latest` image — see
[anarkiwi/asid-vice](https://github.com/anarkiwi/asid-vice).

The SID-Wizard editor disk is fetched on demand from CSDB and cached
under `~/.cache/sidwizard-driver/` (override with `--d64 <path>` or
`XDG_CACHE_HOME`). Pre-fetch:

```
python -m sidwizard_driver.fetch
```

## Usage

Boot smoke:

```
python -m sidwizard_driver.smoke
```

Capture a tune to CSV:

```
python -m sidwizard_driver.capture --swm tune.swm --frames 1500 --out tune.csv
```

Dump per-frame player ghost-register state:

```
python -m sidwizard_driver.ghost_dump --swm tune.swm --frames 60 --annotate --out ghost.csv
```

## CSV schema

`capture` emits `frame,reg,value` (integers). Frame 0 is the first
player tick after F1. `reg` is the SID register offset (`0..0x18`).
Consecutive writes of the same value to the same register are
collapsed.

`ghost_dump` emits `frame,addr,value` (with optional `label` column).
Each frame yields rows for the per-voice zero-page block
(`$10..$80`) plus six additional rows:

- Three for the filter-program self-modifying operand bytes —
  labelled `FLTCTRL` / `FLTPOSI` / `CWEPCNT`. These live in the
  loaded player code (`$1xxx`) and let downstream tools reconstruct
  SID-Wizard's per-frame filter-table position + sweep counter,
  which are NOT in zero page.
- Three for the per-voice DETUNER bytes (`DETUNER_v0` / `v1` / `v2`).
  DETUNER is in the CONST_VAR ZP region that INIPVAR doesn't clear;
  its base address varies by build, so it's discovered from the
  WRPITCH ``adc DETUNER,X`` operand and captured per voice.

## License

Apache-2.0.
