pygoattracker

Pure-Python reader, writer, and player for GoatTracker 2 .SNG songs, with SID register-log output and audio rendering through an emulated SID.

Consumes .sid files (PSID/RSID containers) and bare .prg images through the shared pysidtracker base: the packed GoatTracker playroutine (as produced by gt2reloc) is detected and decompiled back to a Song, including crunched/relocated images whose init is run in a 6502 emulator — container headers are not trusted.

Install

pip install pygoattracker          # read/write/play/register logs, .sid decompile
pip install pygoattracker[audio]   # + WAV rendering via pyresidfp

Decompiling .sid files (including crunched/relocated images, run in a 6502 emulator via jennings) works out of the box; only WAV rendering needs the extra.

Usage

Recover a song from a .sid file:

from pygoattracker import decompile_sid, write_sng

result = decompile_sid("tune.sid")     # path, bytes, or binary file object
song = result.song                     # the parsed Song model
write_sng(song, "tune.sng")            # a .SNG this library reads and plays

Read a GoatTracker .SNG song:

from pygoattracker import read_sng

song = read_sng("tune.sng")
print(song.name, song.author, song.copyright)

The player is one class deriving from pysidtracker.MemPlayer; its render is validated byte-exactly against a sidplayfp oracle across GoatTracker play-routine variations (see docs/oracle-testing.md).

See docs/usage.md for building songs, playback, register logs, WAV rendering, NinjaTracker 2, and the command line, docs/format.md for the format specification, data model, and .sid decompilation notes, and docs/oracle-testing.md for the byte-exact oracle tests.

Development

pip install -e ".[dev]"
./run_tests.sh        # black + pylint + pytest with coverage gate

License

Apache 2.0 — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pygoattracker-0.3.1.tar.gz (92.4 kB view details)

Uploaded Jul 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pygoattracker-0.3.1-py3-none-any.whl (64.3 kB view details)

Uploaded Jul 23, 2026 Python 3

File details

Details for the file pygoattracker-0.3.1.tar.gz.

File metadata

Download URL: pygoattracker-0.3.1.tar.gz
Upload date: Jul 23, 2026
Size: 92.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pygoattracker-0.3.1.tar.gz
Algorithm	Hash digest
SHA256	`a9a3792d33526d73bbe7152d059761a3ed510a33daefa5b5bdb05a7fb6a8ee77`
MD5	`53f7fb397e47c8542801179d1ebd6c48`
BLAKE2b-256	`add8d3bae2cf3bdfae6e206db4683e766b2ac4762cae01a927ba223ad16896f4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygoattracker-0.3.1.tar.gz:

Publisher: publish.yml on anarkiwi/pygoattracker

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pygoattracker-0.3.1.tar.gz
- Subject digest: a9a3792d33526d73bbe7152d059761a3ed510a33daefa5b5bdb05a7fb6a8ee77
- Sigstore transparency entry: 2224857040
- Sigstore integration time: Jul 23, 2026
Source repository:
- Permalink: anarkiwi/pygoattracker@53991526f1c1e69dd1d623c96ebaec80a003a485
- Branch / Tag: refs/tags/v0.3.1
- Owner: https://github.com/anarkiwi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@53991526f1c1e69dd1d623c96ebaec80a003a485
- Trigger Event: release