pyfuturecomposer 0.1.0__py3-none-any.whl

pyfuturecomposer/__init__.py

@@ -0,0 +1,34 @@
+"""Read, play, and render Future Composer (MoN / Deenen) SID songs."""
+
+from pyfuturecomposer.audio import render_samples, render_wav, write_wav
+from pyfuturecomposer.errors import FutureComposerError, SidParseError
+from pyfuturecomposer.model import Song
+from pyfuturecomposer.player import Player, iter_frames, render_grid
+from pyfuturecomposer.reader import parse, read
+from pyfuturecomposer.reglog import (
+    RegWrite,
+    iter_register_writes,
+    read_reglog,
+    write_reglog,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FutureComposerError",
+    "Player",
+    "RegWrite",
+    "SidParseError",
+    "Song",
+    "__version__",
+    "iter_frames",
+    "iter_register_writes",
+    "parse",
+    "read",
+    "read_reglog",
+    "render_grid",
+    "render_samples",
+    "render_wav",
+    "write_reglog",
+    "write_wav",
+]

pyfuturecomposer/audio.py

@@ -0,0 +1,94 @@
+"""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:`pyfuturecomposer.reglog` output.
+"""
+
+import wave
+from array import array
+from datetime import timedelta
+from pathlib import Path
+
+from pyfuturecomposer import constants
+from pyfuturecomposer.errors import FutureComposerError
+from pyfuturecomposer.model import Song
+from pyfuturecomposer.player import iter_frames
+
+CHIP_MODELS = ("6581", "8580")
+
+
+def _default_device(model: str, sampling_frequency):
+    try:
+        from pyresidfp import SoundInterfaceDevice
+        from pyresidfp.sound_interface_device import ChipModel
+    except ImportError as exc:
+        raise FutureComposerError(
+            "pyresidfp is required to render audio; "
+            "install with: pip install pyfuturecomposer[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,
+    model: str = "8580",
+    sampling_frequency=None,
+    device=None,
+    cycles_per_frame: int = constants.PAL_CYCLES_PER_FRAME,
+    clock_frequency: float = constants.PAL_CLOCK_HZ,
+):
+    """Render ``song`` on an emulated SID.
+
+    Returns ``(samples, sampling_frequency)`` where samples are signed 16-bit
+    mono.  Rendering stops at ``seconds`` (the player loops, so a duration is
+    required).
+    """
+    if model not in CHIP_MODELS:
+        raise FutureComposerError(f"chip model must be one of {CHIP_MODELS}")
+    if device is None:
+        device = _default_device(model, sampling_frequency)
+    write_q = constants.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, max_frames=max_frames):
+        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)

pyfuturecomposer/cli.py

@@ -0,0 +1,72 @@
+"""Command line interface: song info, register logs, and WAV rendering."""
+
+import argparse
+import sys
+
+from pyfuturecomposer import audio, reglog
+from pyfuturecomposer.errors import FutureComposerError
+from pyfuturecomposer.reader import read
+
+
+def _info(args) -> None:
+    song = read(args.song)
+    print(f"name:        {song.name}")
+    print(f"author:      {song.author}")
+    print(f"released:    {song.released}")
+    print(f"load:        ${song.load:04X}")
+    print(f"init/play:   ${song.init:04X} / ${song.play:04X}")
+    print(f"image bytes: {len(song.image)}")
+
+
+def _reglog(args) -> None:
+    song = read(args.song)
+    frames = round(args.seconds * 50)
+    writes = reglog.iter_register_writes(song, max_frames=frames)
+    reglog.write_reglog(writes, args.output)
+    print(f"wrote {args.output}")
+
+
+def _wav(args) -> None:
+    song = read(args.song)
+    audio.render_wav(song, args.output, seconds=args.seconds, model=args.model)
+    print(f"wrote {args.output}")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pyfuturecomposer", description="Future Composer song tools"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    info = commands.add_parser("info", help="print song metadata")
+    info.add_argument("song", help="Future Composer .sid/.prg file")
+    info.set_defaults(func=_info)
+
+    log = commands.add_parser("reglog", help="write a SID register log")
+    log.add_argument("song", help="Future Composer .sid/.prg file")
+    log.add_argument("output", help="register log file to write")
+    log.add_argument("--seconds", type=float, default=60.0)
+    log.set_defaults(func=_reglog)
+
+    wav = commands.add_parser("wav", help="render through an emulated SID")
+    wav.add_argument("song", help="Future Composer .sid/.prg file")
+    wav.add_argument("output", help="WAV file to write")
+    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 (FutureComposerError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyfuturecomposer/constants.py

@@ -0,0 +1,93 @@
+"""Constants for the Future Composer (MoN / Deenen) player and song format.
+
+Values follow the decompiled Future Composer player (``entry_1806`` of the
+MoN/FutureComposer player, reverse-engineered from the representative tune
+*We R Da Best (tune 2)* by Warren Pilbrough / Jade Tiger), cross-checked
+byte-exact against the ``preframr-sidtrace`` register oracle.  The player code is
+identical across tunes of this variant; only its DATA (sequences, patterns,
+instruments, mod tables) differs, carried inline at fixed offsets-from-load.
+
+FC is RELOCATABLE (init = load, play = load + 6); every absolute address in the
+disassembly is load-relative, so the constants here are OFFSETS-FROM-LOAD and the
+player reads/writes them at ``load + offset``.
+"""
+
+# SID register map.
+SID_REGISTERS = 25
+VOICES = 3
+SID_BASE = 0xD400
+MODE_VOL_REG = 0x18
+RES_FILT_REG = 0x17
+FC_HI_REG = 0x16
+# Pulse-width high registers carry only their low nibble (12-bit pulse).
+PW_HI_REGS = (0x03, 0x0A, 0x11)
+
+# 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
+
+# Cycles between consecutive register writes within one frame (approximates the
+# store instructions of the 6502 playroutine).
+DEFAULT_WRITE_SPACING = 16
+
+# Standard Future Composer entry points (the PSID header normally matches).
+DEFAULT_INIT_OFFSET = 0  # init = load
+DEFAULT_PLAY_OFFSET = 6  # play = load + 6
+
+# ---------------------------------------------------------------------------
+# Player-code / inline-table OFFSETS-FROM-LOAD.  The player binary is identical
+# across tunes of this variant, so each table lives at a fixed offset from the
+# load address (relocation-safe -- the same offsets work for any load address).
+# Derived directly from the disassembly (subtract $1800 from the absolute addr).
+# ---------------------------------------------------------------------------
+OFF_FREQ_LO = 0x5AB  # $1dab note freq-lo table (also the slide-target base)
+OFF_FREQ_HI = 0x60B  # $1e0b note freq-hi table
+OFF_SEQ_LO = 0x6EC  # $1eec per-voice sequence pointer table, low bytes
+OFF_SEQ_HI = 0x6EF  # $1eef per-voice sequence pointer table, high bytes
+OFF_PAT_PTR = 0x6F8  # $1ef8 interleaved pattern pointer table (id*2)
+OFF_INSTR = 0x721  # $1f21 instrument record array (8-byte records)
+OFF_VOICE_BASE = 0x6E9  # $1ee9 per-voice SID register base (0, 7, 14)
+OFF_SPEED = 0x6E8  # $1ee8 song speed (tempo divider reload)
+OFF_PW_STEP = 0x6DC  # $1edc pulse-width sweep step table
+OFF_FILTER = 0x6D0  # $1ed0 filter-cutoff walk table
+OFF_WAVE_ARP = 0x679  # $1e79 ($02ac & 0x40) wave/arp ctrl table
+OFF_ARP_DELAY = 0x6CD  # $1ecd arp-delay table
+OFF_WAVE_PROG_PTR = 0x685  # $1e85 wave-program pointer table
+OFF_WAVE_PROG_PITCH = 0x68D  # $1e8d wave-program pitch table
+OFF_WAVE_PROG_CTRL = 0x69D  # $1e9d wave-program control table
+OFF_MOD = 0x726  # $1f26 per-instrument modulation-control bytes
+OFF_SLIDE_LO = 0x2DB  # $1adb self-modified slide-lo store
+OFF_PW_CARRY = 0x3B7  # $1bb7 pulse-width-lo carry immediate
+OFF_FILT_LO = 0x6CE  # $1ece filter cutoff-lo store
+OFF_FILT_HI = 0x6CF  # $1ecf filter cutoff-hi store
+OFF_WAVE_PROG_SELF = 0x492  # $1c92 self-modified wave-program pointer slots
+
+# Instrument record (8 bytes) field offsets.
+INSTR_RECORD_SIZE = 8
+INSTR_PULSE_CTRL = 0
+INSTR_WAVEFORM = 1
+INSTR_AD = 2
+INSTR_SR = 3
+INSTR_AUX = 4
+INSTR_VIB_CTRL = 5
+INSTR_PW_CTRL = 6
+INSTR_MASTER_CTRL = 7
+
+# Pattern / sequence opcode grammar boundaries.
+NOTE_MAX = 0x7F  # < 0x80: a note (indexes the freq tables)
+DUR_MIN = 0x80  # 0x80..0xBF: set note duration (dur = value & 0x3F)
+INSTR_MIN = 0xC0  # 0xC0..0xDF: instrument select (id = value & 0x1F)
+PORTA_MIN = 0xE0  # 0xE0..0xEF: portamento/slide command (+1 arg byte)
+ROWMARK_MIN = 0xF0  # 0xF0..0xFF: row, no new instrument; next byte is the note
+PATTERN_END = 0xFF  # pattern terminator (after a note)
+SEQ_END = 0xFE  # sequence end-of-song
+SEQ_LOOP = 0xFF  # sequence loop-this-voice
+SEQ_TRANSPOSE = 0x80  # bit7 set in a sequence byte = transpose (& 0x1F)
+SEQ_REPEAT = 0x40  # bit6 set = repeat-count (& 0x3F)
+INSTR_MASK = 0x1F
+DUR_MASK = 0x3F
+
+# DAT_02c9 filter-routing accumulator base, seeded by SUB_1d65 at init.
+FILTER_ROUTE_SEED = 0xB0

pyfuturecomposer/errors.py

@@ -0,0 +1,9 @@
+"""Exceptions raised by pyfuturecomposer."""
+
+
+class FutureComposerError(Exception):
+    """Base class for all pyfuturecomposer errors."""
+
+
+class SidParseError(FutureComposerError):
+    """A PSID/PRG image (or byte string) could not be parsed."""

pyfuturecomposer/model.py

@@ -0,0 +1,37 @@
+"""The Future Composer song model.
+
+Future Composer carries its authored data (sequences, patterns, instruments and
+the modulation tables) INLINE in the module image at fixed offsets-from-load, and
+the player walks that image directly every frame.  A :class:`Song` therefore holds
+the loaded image bytes + the load address + the SID header metadata; the player
+(:mod:`pyfuturecomposer.player`) reads the inline tables from the image as the
+6502 player does, so the model stays a faithful, minimal container.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Song:
+    """A parsed Future Composer tune.
+
+    ``image`` is the raw C64 image (player code + inline song data); ``load`` is
+    its load address; ``init`` / ``play`` are the player entry points (init =
+    load, play = load + 6 for FC); ``name`` / ``author`` / ``released`` are the
+    PSID header strings (empty for a bare ``.prg``).
+    """
+
+    image: bytes
+    load: int
+    init: int
+    play: int
+    name: str = ""
+    author: str = ""
+    released: str = ""
+
+    def byte(self, addr: int) -> int:
+        """Read the image byte at absolute C64 ``addr`` (0 outside the image)."""
+        idx = addr - self.load
+        if 0 <= idx < len(self.image):
+            return self.image[idx]
+        return 0