pygoattracker 0.1.0__py3-none-any.whl

pygoattracker/__init__.py

@@ -0,0 +1,92 @@
+"""Read, write, play, and render GoatTracker 2 (.SNG) songs."""
+
+from pygoattracker.audio import render_samples, render_wav, write_wav
+from pygoattracker.convert import gt_to_nt2
+from pygoattracker.errors import (
+    ConversionError,
+    GoatTrackerError,
+    NinjaParseError,
+    NinjaValidationError,
+    SngParseError,
+    SngValidationError,
+)
+from pygoattracker.ninja import (
+    NinjaCommand,
+    NinjaPattern,
+    NinjaRow,
+    NinjaSong,
+    build_nt2,
+    parse_nt2,
+    read_nt2,
+    validate_nt2,
+    write_nt2,
+)
+from pygoattracker.model import (
+    Instrument,
+    Orderlist,
+    Pattern,
+    PlayPattern,
+    Repeat,
+    Row,
+    Song,
+    Subtune,
+    Table,
+    Transpose,
+    entry_from_byte,
+)
+from pygoattracker.player import Player, iter_frames
+from pygoattracker.reader import parse_sng, read_sng
+from pygoattracker.reglog import (
+    RegWrite,
+    iter_register_writes,
+    read_reglog,
+    write_reglog,
+)
+from pygoattracker.writer import build_sng, validate_song, write_sng
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ConversionError",
+    "GoatTrackerError",
+    "Instrument",
+    "NinjaCommand",
+    "NinjaParseError",
+    "NinjaPattern",
+    "NinjaRow",
+    "NinjaSong",
+    "NinjaValidationError",
+    "Orderlist",
+    "Pattern",
+    "PlayPattern",
+    "Player",
+    "RegWrite",
+    "Repeat",
+    "Row",
+    "SngParseError",
+    "SngValidationError",
+    "Song",
+    "Subtune",
+    "Table",
+    "Transpose",
+    "__version__",
+    "build_nt2",
+    "build_sng",
+    "entry_from_byte",
+    "gt_to_nt2",
+    "iter_frames",
+    "iter_register_writes",
+    "parse_nt2",
+    "parse_sng",
+    "read_nt2",
+    "read_reglog",
+    "read_sng",
+    "render_samples",
+    "render_wav",
+    "validate_nt2",
+    "validate_song",
+    "write_nt2",
+    "write_reglog",
+    "write_sng",
+    "write_wav",
+]

pygoattracker/audio.py

@@ -0,0 +1,106 @@
+"""Render songs through an emulated SID to samples or WAV.
+
+By default the emulated SID is `pyresidfp
+<https://pypi.org/project/pyresidfp/>`_ (install the ``audio`` extra).
+Any object with ``write_register(reg, value)``, ``clock(timedelta) ->
+samples`` and a ``sampling_frequency`` attribute can be passed as
+``device`` instead, e.g. for tests or a different emulator.
+
+Each register write is clocked individually at the same in-frame offset
+the register log uses, so renders line up with
+:mod:`pygoattracker.reglog` output.
+"""
+
+import wave
+from array import array
+from datetime import timedelta
+from pathlib import Path
+
+from pygoattracker import constants
+from pygoattracker.errors import GoatTrackerError
+from pygoattracker.model import Song
+from pygoattracker.player import iter_frames
+from pygoattracker.reglog import DEFAULT_WRITE_SPACING
+
+CHIP_MODELS = ("6581", "8580")
+
+
+def _default_device(model: str, sampling_frequency: float | None):
+    try:
+        from pyresidfp import SoundInterfaceDevice
+        from pyresidfp.sound_interface_device import ChipModel
+    except ImportError as exc:
+        raise GoatTrackerError(
+            "pyresidfp is required to render audio; "
+            "install with: pip install pygoattracker[audio]"
+        ) from exc
+    chip = {"6581": ChipModel.MOS6581, "8580": ChipModel.MOS8580}[model]
+    if sampling_frequency:
+        return SoundInterfaceDevice(
+            model=chip, sampling_frequency=float(sampling_frequency)
+        )
+    return SoundInterfaceDevice(model=chip)
+
+
+def render_samples(
+    song: Song,
+    seconds: float = 60.0,
+    subtune: int = 0,
+    until_loop: bool = False,
+    model: str = "8580",
+    sampling_frequency: float | None = None,
+    device=None,
+    cycles_per_frame: int = constants.PAL_CYCLES_PER_FRAME,
+    clock_frequency: float = constants.PAL_CLOCK_HZ,
+    **player_options,
+):
+    """Render ``song`` on an emulated SID.
+
+    Returns ``(samples, sampling_frequency)`` where samples are signed
+    16-bit mono. Rendering stops at ``seconds`` (or earlier when the
+    song stops, or at the song loop with ``until_loop``).
+    """
+    if model not in CHIP_MODELS:
+        raise GoatTrackerError(f"chip model must be one of {CHIP_MODELS}")
+    if device is None:
+        device = _default_device(model, sampling_frequency)
+    write_q = DEFAULT_WRITE_SPACING / clock_frequency
+    frame_seconds = cycles_per_frame / clock_frequency
+    max_frames = max(1, round(seconds / frame_seconds))
+    samples = array("h")
+    for writes in iter_frames(
+        song,
+        subtune=subtune,
+        max_frames=max_frames,
+        until_loop=until_loop,
+        **player_options,
+    ):
+        remainder = frame_seconds
+        for reg, val in writes:
+            device.write_register(reg, val)
+            samples.extend(device.clock(timedelta(seconds=write_q)))
+            remainder -= write_q
+        if remainder > 0:
+            samples.extend(device.clock(timedelta(seconds=remainder)))
+    return samples, float(device.sampling_frequency)
+
+
+def write_wav(dst, samples, sampling_frequency: float) -> None:
+    """Write signed 16-bit mono samples as a WAV file."""
+    if not isinstance(samples, array):
+        samples = array("h", samples)
+    with wave.open(str(dst), "wb") as out:
+        out.setnchannels(1)
+        out.setsampwidth(2)
+        out.setframerate(round(sampling_frequency))
+        out.writeframes(samples.tobytes())
+
+
+def render_wav(song: Song, dst, seconds: float = 60.0, **options) -> Path:
+    """Render ``song`` to a WAV file; returns the path written.
+
+    Keyword options are those of :func:`render_samples`.
+    """
+    samples, sampling_frequency = render_samples(song, seconds=seconds, **options)
+    write_wav(dst, samples, sampling_frequency)
+    return Path(dst)

pygoattracker/cli.py

@@ -0,0 +1,118 @@
+"""Command line interface: song info, register logs, and WAV rendering."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from pygoattracker import audio, convert, ninja, reglog
+from pygoattracker.errors import GoatTrackerError
+from pygoattracker.reader import read_sng
+
+
+def _nt2_info(song) -> None:
+    print("format:      NinjaTracker 2")
+    print(f"subtunes:    {len(song.subtunes)}")
+    print(f"patterns:    {len(song.patterns)}")
+    print(f"commands:    {len(song.commands)}")
+    print(f"hardrestart: {song.hr_param:02X} / first wave {song.first_wave:02X}")
+    for num, command in enumerate(song.commands, start=1):
+        print(f"  {num:02X}: {command.name}")
+
+
+def _info(args) -> None:
+    data = Path(args.song).read_bytes()
+    if data[: len(ninja.NT2_MAGIC)] == ninja.NT2_MAGIC:
+        _nt2_info(ninja.parse_nt2(data))
+        return
+    song = read_sng(data)
+    print(f"name:        {song.name}")
+    print(f"author:      {song.author}")
+    print(f"copyright:   {song.copyright}")
+    print(f"subtunes:    {len(song.subtunes)}")
+    print(f"patterns:    {len(song.patterns)}")
+    print(f"instruments: {len(song.instruments)}")
+    for num, instrument in enumerate(song.instruments, start=1):
+        print(f"  {num:02X}: {instrument.name}")
+
+
+def _reglog(args) -> None:
+    song = read_sng(args.song)
+    frames = round(args.seconds * 50)
+    writes = reglog.iter_register_writes(song, subtune=args.subtune, max_frames=frames)
+    reglog.write_reglog(writes, args.output)
+    print(f"wrote {args.output}")
+
+
+def _wav(args) -> None:
+    song = read_sng(args.song)
+    audio.render_wav(
+        song,
+        args.output,
+        seconds=args.seconds,
+        subtune=args.subtune,
+        model=args.model,
+    )
+    print(f"wrote {args.output}")
+
+
+def _nt2(args) -> None:
+    song = read_sng(args.song)
+    report: list = []
+    errors = "drop" if args.lenient else "strict"
+    converted = convert.gt_to_nt2(song, errors=errors, report=report)
+    ninja.write_nt2(converted, args.output)
+    for message in report:
+        print(f"dropped: {message}")
+    print(f"wrote {args.output}")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pygoattracker", description="GoatTracker 2 song tools"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    info = commands.add_parser("info", help="print song metadata")
+    info.add_argument("song", help=".sng file")
+    info.set_defaults(func=_info)
+
+    log = commands.add_parser("reglog", help="write a SID register log")
+    log.add_argument("song", help=".sng file")
+    log.add_argument("output", help="register log file to write")
+    log.add_argument("--subtune", type=int, default=0)
+    log.add_argument("--seconds", type=float, default=60.0)
+    log.set_defaults(func=_reglog)
+
+    nt2 = commands.add_parser("nt2", help="convert to a NinjaTracker 2 song")
+    nt2.add_argument("song", help=".sng file")
+    nt2.add_argument("output", help="NinjaTracker 2 file to write")
+    nt2.add_argument(
+        "--lenient",
+        action="store_true",
+        help="drop and report inexpressible features instead of failing",
+    )
+    nt2.set_defaults(func=_nt2)
+
+    wav = commands.add_parser("wav", help="render through an emulated SID")
+    wav.add_argument("song", help=".sng file")
+    wav.add_argument("output", help="WAV file to write")
+    wav.add_argument("--subtune", type=int, default=0)
+    wav.add_argument("--seconds", type=float, default=60.0)
+    wav.add_argument("--model", choices=audio.CHIP_MODELS, default="8580")
+    wav.set_defaults(func=_wav)
+    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 (GoatTrackerError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pygoattracker/constants.py

@@ -0,0 +1,170 @@
+"""Constants shared by the GoatTracker 2 .SNG format and playroutine.
+
+Values follow GoatTracker 2.76 (``gcommon.h`` and the format description
+in its ``readme.txt`` section 6.1).
+"""
+
+SNG_MAGIC = b"GTS5"
+# GTS3/GTS4 share GTS5's binary layout (with small post-load value
+# conversions); GTS2 (early 3-table GoatTracker 2) and GTS! (GoatTracker
+# 1.x) are converted on load, exactly as GoatTracker 2 imports them.
+SNG_COMPATIBLE_MAGICS = (b"GTS!", b"GTS2", b"GTS3", b"GTS4", b"GTS5")
+
+MAX_STR = 32
+MAX_INSTR = 64
+MAX_CHN = 3
+MAX_PATT = 208
+MAX_TABLES = 4
+MAX_TABLELEN = 255
+MAX_INSTRNAMELEN = 16
+MAX_PATTROWS = 128
+MAX_SONGLEN = 254
+MAX_SONGS = 32
+MAX_NOTES = 96
+
+# Orderlist entry encoding.
+REPEAT = 0xD0
+TRANSDOWN = 0xE0
+TRANSUP = 0xF0
+LOOPSONG = 0xFF
+
+# Pattern note column encoding.
+ENDPATT = 0xFF
+FIRSTNOTE = 0x60
+LASTNOTE = 0xBC
+REST = 0xBD
+KEYOFF = 0xBE
+KEYON = 0xBF
+
+# Pattern commands 0XY-FXY.
+CMD_DONOTHING = 0x0
+CMD_PORTAUP = 0x1
+CMD_PORTADOWN = 0x2
+CMD_TONEPORTA = 0x3
+CMD_VIBRATO = 0x4
+CMD_SETAD = 0x5
+CMD_SETSR = 0x6
+CMD_SETWAVE = 0x7
+CMD_SETWAVEPTR = 0x8
+CMD_SETPULSEPTR = 0x9
+CMD_SETFILTERPTR = 0xA
+CMD_SETFILTERCTRL = 0xB
+CMD_SETFILTERCUTOFF = 0xC
+CMD_SETMASTERVOL = 0xD
+CMD_FUNKTEMPO = 0xE
+CMD_SETTEMPO = 0xF
+
+# Table indexes, in on-disk order.
+WTBL = 0
+PTBL = 1
+FTBL = 2
+STBL = 3
+
+# Wavetable left-side ranges.
+WAVEDELAY = 0x01
+WAVELASTDELAY = 0x0F
+WAVESILENT = 0xE0
+WAVELASTSILENT = 0xEF
+WAVECMD = 0xF0
+WAVELASTCMD = 0xFE
+TABLEJUMP = 0xFF
+
+# SID register map (offsets within the chip's 25 registers).
+SID_REGISTERS = 25
+VOICES = 3
+VOICE_REG_SIZE = 7
+FREQ_LO_REG = 0x00
+FREQ_HI_REG = 0x01
+PULSE_LO_REG = 0x02
+PULSE_HI_REG = 0x03
+CONTROL_REG = 0x04
+AD_REG = 0x05
+SR_REG = 0x06
+FC_LO_REG = 0x15
+FC_HI_REG = 0x16
+RES_FILT_REG = 0x17
+MODE_VOL_REG = 0x18
+
+# 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
+
+# Default player options, as in the GoatTracker editor.
+DEFAULT_ADPARAM = 0x0F00
+
+# PAL note frequency table from the GoatTracker 2 playroutine, notes
+# C-0 to B-7 (the player can reach A-7 to B-7 through transpose only).
+FREQ_LO = (
+    # fmt: off
+    0x17, 0x27, 0x39, 0x4B, 0x5F, 0x74, 0x8A, 0xA1, 0xBA, 0xD4, 0xF0, 0x0E,
+    0x2D, 0x4E, 0x71, 0x96, 0xBE, 0xE8, 0x14, 0x43, 0x74, 0xA9, 0xE1, 0x1C,
+    0x5A, 0x9C, 0xE2, 0x2D, 0x7C, 0xCF, 0x28, 0x85, 0xE8, 0x52, 0xC1, 0x37,
+    0xB4, 0x39, 0xC5, 0x5A, 0xF7, 0x9E, 0x4F, 0x0A, 0xD1, 0xA3, 0x82, 0x6E,
+    0x68, 0x71, 0x8A, 0xB3, 0xEE, 0x3C, 0x9E, 0x15, 0xA2, 0x46, 0x04, 0xDC,
+    0xD0, 0xE2, 0x14, 0x67, 0xDD, 0x79, 0x3C, 0x29, 0x44, 0x8D, 0x08, 0xB8,
+    0xA1, 0xC5, 0x28, 0xCD, 0xBA, 0xF1, 0x78, 0x53, 0x87, 0x1A, 0x10, 0x71,
+    0x42, 0x89, 0x4F, 0x9B, 0x74, 0xE2, 0xF0, 0xA6, 0x0E, 0x33, 0x20, 0xFF,
+    # fmt: on
+)
+FREQ_HI = (
+    # fmt: off
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x02,
+    0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x03, 0x03, 0x03, 0x03, 0x03, 0x04,
+    0x04, 0x04, 0x04, 0x05, 0x05, 0x05, 0x06, 0x06, 0x06, 0x07, 0x07, 0x08,
+    0x08, 0x09, 0x09, 0x0A, 0x0A, 0x0B, 0x0C, 0x0D, 0x0D, 0x0E, 0x0F, 0x10,
+    0x11, 0x12, 0x13, 0x14, 0x15, 0x17, 0x18, 0x1A, 0x1B, 0x1D, 0x1F, 0x20,
+    0x22, 0x24, 0x27, 0x29, 0x2B, 0x2E, 0x31, 0x34, 0x37, 0x3A, 0x3E, 0x41,
+    0x45, 0x49, 0x4E, 0x52, 0x57, 0x5C, 0x62, 0x68, 0x6E, 0x75, 0x7C, 0x83,
+    0x8B, 0x93, 0x9C, 0xA5, 0xAF, 0xB9, 0xC4, 0xD0, 0xDD, 0xEA, 0xF8, 0xFF,
+    # fmt: on
+)
+
+# The playroutine indexes the frequency table with 7-bit note numbers,
+# so pad to 128 entries exactly like the original player's data segment.
+FREQ_TABLE = tuple((hi << 8) | lo for lo, hi in zip(FREQ_LO, FREQ_HI)) + (0,) * (
+    128 - MAX_NOTES
+)
+
+_NOTE_NAMES = (
+    "C-",
+    "C#",
+    "D-",
+    "D#",
+    "E-",
+    "F-",
+    "F#",
+    "G-",
+    "G#",
+    "A-",
+    "A#",
+    "B-",
+)
+
+
+def note_name(note: int) -> str:
+    """Tracker-style display name for a pattern note byte."""
+    if note == REST:
+        return "..."
+    if note == KEYOFF:
+        return "---"
+    if note == KEYON:
+        return "+++"
+    if note == ENDPATT:
+        return "END"
+    if FIRSTNOTE <= note <= LASTNOTE:
+        offset = note - FIRSTNOTE
+        return f"{_NOTE_NAMES[offset % 12]}{offset // 12}"
+    raise ValueError(f"not a note byte: {note:#04x}")
+
+
+def note_value(name: str) -> int:
+    """Pattern note byte for a tracker-style name such as ``A-4``."""
+    if len(name) == 3:
+        prefix, octave = name[:2], name[2]
+        if prefix in _NOTE_NAMES and octave.isdigit() and int(octave) < 8:
+            note = FIRSTNOTE + int(octave) * 12 + _NOTE_NAMES.index(prefix)
+            if note <= LASTNOTE:
+                return note
+    raise ValueError(f"not a note name: {name!r}")