pymusicassembler 0.1.0__py3-none-any.whl

pymusicassembler/__init__.py

@@ -0,0 +1,59 @@
+"""Read, write, play, and render Music Assembler SID songs."""
+
+from pymusicassembler.audio import render_samples, render_wav, write_wav
+from pymusicassembler.errors import (
+    MusicAssemblerError,
+    SidParseError,
+    SongValidationError,
+)
+from pymusicassembler.model import (
+    DurationEvent,
+    Instrument,
+    InstrumentEvent,
+    NoteEvent,
+    OrderEntry,
+    Orderlist,
+    Pattern,
+    Song,
+)
+from pymusicassembler.player import Player, iter_frames, render_grid
+from pymusicassembler.reader import parse, read
+from pymusicassembler.reglog import (
+    RegWrite,
+    iter_register_writes,
+    read_reglog,
+    write_reglog,
+)
+from pymusicassembler.writer import build, validate, write
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DurationEvent",
+    "Instrument",
+    "InstrumentEvent",
+    "MusicAssemblerError",
+    "NoteEvent",
+    "OrderEntry",
+    "Orderlist",
+    "Pattern",
+    "Player",
+    "RegWrite",
+    "SidParseError",
+    "Song",
+    "SongValidationError",
+    "__version__",
+    "build",
+    "iter_frames",
+    "iter_register_writes",
+    "parse",
+    "read",
+    "read_reglog",
+    "render_grid",
+    "render_samples",
+    "render_wav",
+    "validate",
+    "write",
+    "write_reglog",
+    "write_wav",
+]

pymusicassembler/audio.py

@@ -0,0 +1,97 @@
+"""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:`pymusicassembler.reglog` output.
+"""
+
+import wave
+from array import array
+from datetime import timedelta
+from pathlib import Path
+
+from pymusicassembler import constants
+from pymusicassembler.errors import MusicAssemblerError
+from pymusicassembler.model import Song
+from pymusicassembler.player import iter_frames
+from pymusicassembler.reglog import DEFAULT_WRITE_SPACING
+
+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 MusicAssemblerError(
+            "pyresidfp is required to render audio; "
+            "install with: pip install pymusicassembler[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 MusicAssemblerError(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, 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)

pymusicassembler/cli.py

@@ -0,0 +1,88 @@
+"""Command line interface: song info, register logs, and WAV rendering."""
+
+import argparse
+import sys
+
+from pymusicassembler import audio, reglog, writer
+from pymusicassembler.errors import MusicAssemblerError
+from pymusicassembler.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_addr:04X}")
+    print(f"init/play:   ${song.init_addr:04X} / ${song.play_addr:04X}")
+    print(f"patterns:    {len(song.patterns)}")
+    print(f"instruments: {len(song.instruments)}")
+    for voice, orderlist in enumerate(song.orderlists):
+        ids = " ".join(f"{e.pattern_id:02X}" for e in orderlist.entries)
+        print(f"  voice {voice}: {len(orderlist.entries)} entries [{ids}]")
+
+
+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 _resave(args) -> None:
+    song = read(args.song)
+    writer.write(song, args.output, container=args.container)
+    print(f"wrote {args.output}")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pymusicassembler", description="Music Assembler song tools"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    info = commands.add_parser("info", help="print song metadata")
+    info.add_argument("song", help="Music Assembler .sid/.prg file")
+    info.set_defaults(func=_info)
+
+    log = commands.add_parser("reglog", help="write a SID register log")
+    log.add_argument("song", help="Music Assembler .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="Music Assembler .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)
+
+    resave = commands.add_parser("resave", help="re-emit the tune image")
+    resave.add_argument("song", help="Music Assembler .sid/.prg file")
+    resave.add_argument("output", help="output file")
+    resave.add_argument("--container", choices=("auto", "psid", "prg"), default="auto")
+    resave.set_defaults(func=_resave)
+    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 (MusicAssemblerError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pymusicassembler/constants.py

@@ -0,0 +1,121 @@
+"""Constants for the Music Assembler player and song format.
+
+Values follow the decompiled Music Assembler player (Richard Bayliss /
+Eric Campbell era), cross-checked byte-exact against the
+``preframr-sidtrace`` register oracle.  The player code is identical
+across Music Assembler tunes; only its DATA (orderlists, patterns,
+instruments and the addresses they live at) differs per tune.
+"""
+
+# 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
+PW_LO_REG = 0x02
+PW_HI_REG = 0x03
+CTRL_REG = 0x04
+AD_REG = 0x05
+SR_REG = 0x06
+FC_HI_REG = 0x16
+RES_FILT_REG = 0x17
+MODE_VOL_REG = 0x18
+
+# Per-voice SID base offsets ($D400 + offset).
+SID_OFFSET = (0, 7, 14)
+
+# Pulse-width high registers carry only their low nibble (12-bit pulse).
+PW_HI_REGS = (PW_HI_REG, PW_HI_REG + 7, PW_HI_REG + 14)
+
+# Pattern byte grammar boundaries.
+NOTE_MAX = 0x5F  # < 0x60: a note (+ trailing control byte)
+DUR_MIN = 0x60  # 0x60..0x7F: bare duration token
+INSTR_MIN = 0x80  # 0x80..0x9F: instrument select (id = value & 0x1F)
+INSTR_MAX = 0x9F
+LONGDUR_MIN = 0xA0  # 0xA0..0xFE: long-duration token (dur = value & 0x1F)
+PATTERN_END = 0xFF
+ORDER_END = 0xFF  # orderlist terminator -> loop to start
+SILENCE_PATTERN = 0xFE  # orderlist pattern id $FE: gate off, no row
+
+# Note-control byte ($1141) bit meanings (the byte after a note).
+CTL_FILTER = 0x80  # inline filter command attached
+CTL_VIBARP = 0x20  # inline vibrato/arp params attached
+CTL_TRIGGERED = 0x40  # note-trigger latch (set after the trigger frame)
+CTL_DUR_MASK = 0x1F
+
+# Instrument record byte offsets (8-byte record).
+INSTR_RECORD_SIZE = 8
+INSTR_AD = 0
+INSTR_SR = 1
+INSTR_WAVEFORM = 2
+INSTR_PULSE_INIT = 3
+INSTR_PULSE_STEP = 4
+INSTR_ARP_SPEED = 5
+INSTR_ARP_STEP = 6
+INSTR_PORTA = 7
+
+# Player constants recovered from the disassembly.
+TEMPO_DIVIDER = 2  # play-call divider ($1090 reset value)
+FILTER_STEP = 0xF0  # cutoff sweep increment per owner frame ($129e += step)
+FILTER_CTR = 0x29  # cutoff sweep gate-counter reset ($1296)
+RES_PRESETS = (0xF1, 0xF7, 0xF7)  # per-voice RES_FILT preset ($12b3)
+
+# Player-code operand offsets-from-load.  The player binary is identical
+# across Music Assembler tunes, so each pointer-table base address lives
+# at a fixed offset in the code; the reader reads the 16-bit operand
+# there to discover the per-tune table base (relocation-safe).
+OP_PATTERN_LO = 0x081  # pattern pointer table, low bytes
+OP_PATTERN_HI = 0x086  # pattern pointer table, high bytes
+OP_ORDER_LO = 0x173  # orderlist pointer table, low bytes
+OP_ORDER_HI = 0x178  # orderlist pointer table, high bytes
+OP_INSTR = 0x215  # instrument record table base
+OP_FREQ_LO = 0x0EC  # frequency table, low bytes
+OP_FREQ_HI = 0x0F5  # frequency table, high bytes
+OP_INNER_LO = 0x3C6  # instrument inner (effect program) pointer table, low
+OP_INNER_HI = 0x3CB  # instrument inner pointer table, high
+OP_ARP = 0x2C2  # 4-entry arp direction table
+
+# Fixed table sizes the reader extracts.
+FREQ_TABLE_LEN = 96  # note frequency table entries
+
+# 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
+
+# Standard Music Assembler entry points (PSID header normally matches).
+DEFAULT_LOAD = 0x1021
+DEFAULT_INIT = 0x1048
+DEFAULT_PLAY = 0x1021
+
+# Per-voice work-RAM absolute addresses (voice index added).  The init
+# routine ($1048) zeroes only $1081..$1090 (pat_cursor / ctrl /
+# order_cursor / dur / pattern_id) and then reloads pattern_id / transrep
+# / repeat from each voice's orderlist; EVERY other work-RAM byte keeps
+# its loaded-image value.  A tune saved mid-playback bakes live values
+# into these addresses, so the player seeds its voice state from the
+# image here -- otherwise its first frames diverge from the oracle.
+WORK_MASTER_TEMPO = 0x1090  # global play-call tempo counter
+WORK_FILTER_OWNER = 0x1262  # filter-sweep owner voice
+WORK_NOTE_INDEX = 0x10C9
+WORK_FREQ_LO = 0x10CC
+WORK_FREQ_HI = 0x10CF
+WORK_ARP_SUBSTEP = 0x10DD
+WORK_PW_SUBSTEP = 0x10E0
+WORK_PW_DIR = 0x10E3
+WORK_NOTE_CTL = 0x1141
+WORK_INSTR_CURSOR = 0x1144
+WORK_VIB_LO_STEP = 0x1147
+WORK_VIB_HI_STEP = 0x114A
+WORK_PORTA_CTR = 0x114D
+WORK_VIB_FREQ_HI = 0x12B6
+WORK_VIB_TOGGLE = 0x12B9
+WORK_ARP_PHASE = 0x12BD
+WORK_INSTR_X8 = 0x13D9
+WORK_PW_LO = 0x13DC
+WORK_PW_HI = 0x13DF
+WORK_VIB_FREQ_LO = 0x13E2
+WORK_CTRL_MASK = 0x1031
+WORK_FLAGS = 0x00FD  # zero-page; outside the image -> defaults to 0

pymusicassembler/errors.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by pymusicassembler."""
+
+
+class MusicAssemblerError(Exception):
+    """Base class for all pymusicassembler errors."""
+
+
+class SidParseError(MusicAssemblerError):
+    """A PSID/PRG image (or byte string) could not be parsed."""
+
+
+class SongValidationError(MusicAssemblerError):
+    """A Song does not satisfy the Music Assembler format limits."""

pymusicassembler/model.py

@@ -0,0 +1,231 @@
+"""Typed model of a Music Assembler song.
+
+A :class:`Song` holds everything needed to play and re-emit a Music
+Assembler tune: three per-voice orderlists, the shared pattern pool,
+8-byte instrument records, the per-tune note-frequency tables and the
+instrument inner (effect) programs.
+
+Patterns are kept as RAW byte sequences (the player's own pattern
+bytecode, minus the ``$FF`` terminator).  The grammar -- ``<0x60`` note +
+control byte, ``0x60-0x7F`` bare duration, ``0x80-0x9F`` instrument
+select, ``0xA0-0xFE`` long duration -- is documented on
+:meth:`Pattern.events`, which decodes the bytes into typed events for
+inspection, while the bytes themselves drive both the player and the
+writer so a tune round-trips byte-for-byte.
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+from pymusicassembler import constants
+from pymusicassembler.errors import MusicAssemblerError
+
+
+@dataclass(frozen=True)
+class OrderEntry:
+    """One orderlist entry: play ``pattern_id`` with a transpose/repeat.
+
+    The on-disk pair is ``(pattern_id, transpose << 4 | repeat)``.
+    ``transpose`` is the orderlist transpose added to note indices (0-15);
+    ``repeat`` is the raw 0-15 repeat field (the pattern plays
+    ``repeat + 1`` times in total, matching the player's repeat counter).
+    Pattern id ``0xFE`` is the silence marker (gate off, no row).
+    """
+
+    pattern_id: int
+    transpose: int = 0
+    repeat: int = 0
+
+    def control_byte(self) -> int:
+        """The packed ``transpose << 4 | repeat`` control byte."""
+        if not 0 <= self.transpose <= 0x0F:
+            raise MusicAssemblerError(f"transpose out of range: {self.transpose}")
+        if not 0 <= self.repeat <= 0x0F:
+            raise MusicAssemblerError(f"repeat out of range: {self.repeat}")
+        return (self.transpose << 4) | self.repeat
+
+    @classmethod
+    def from_bytes(cls, pattern_id: int, control: int) -> "OrderEntry":
+        """Decode an on-disk ``(pattern_id, control)`` pair."""
+        return cls(
+            pattern_id=pattern_id,
+            transpose=(control >> 4) & 0x0F,
+            repeat=control & 0x0F,
+        )
+
+
+@dataclass
+class Orderlist:
+    """One voice's orderlist: a sequence of entries, looping at the end."""
+
+    entries: List[OrderEntry] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class NoteEvent:
+    """A note row: ``note`` (+ orderlist transpose) indexes the freq table."""
+
+    note: int
+    control: int  # the trailing note-control byte ($1141)
+    args: tuple = ()  # inline filter/vibrato argument bytes
+
+
+@dataclass(frozen=True)
+class InstrumentEvent:
+    """An instrument-select event (``id`` 0-31)."""
+
+    instrument: int
+
+
+@dataclass(frozen=True)
+class DurationEvent:
+    """A bare/long duration token (sets the row's frame duration)."""
+
+    duration: int
+    long: bool = False  # True for the $A0-$FE long-duration form
+
+
+PatternEvent = NoteEvent | InstrumentEvent | DurationEvent
+
+
+@dataclass
+class Pattern:
+    """A pattern: raw player bytecode (no trailing ``$FF`` terminator)."""
+
+    data: List[int] = field(default_factory=list)
+
+    def to_bytes(self) -> bytes:
+        """On-disk pattern bytes including the ``$FF`` terminator."""
+        return bytes(list(self.data) + [constants.PATTERN_END])
+
+    def events(self) -> List[PatternEvent]:
+        """Decode the raw bytes into typed events (for inspection).
+
+        Mirrors the player's pattern walk: ``$80-$9F`` selects an
+        instrument and the following byte may continue into a note;
+        ``$A0-$FE`` and ``$60-$7F`` are duration tokens; ``<0x60`` is a
+        note whose control byte (and any inline filter/vibrato args)
+        follows.  Decoding is best-effort and never consumes past the
+        end of ``data``.
+        """
+        events: List[PatternEvent] = []
+        data = self.data
+        i = 0
+        n = len(data)
+        while i < n:
+            val = data[i]
+            if val >= constants.INSTR_MIN:
+                if val >= constants.LONGDUR_MIN:  # long-duration token
+                    events.append(
+                        DurationEvent(val & constants.CTL_DUR_MASK, long=True)
+                    )
+                    i += 1
+                    continue
+                events.append(InstrumentEvent(val & 0x1F))  # instrument select
+                i += 1
+                if i < n and data[i] >= constants.DUR_MIN:
+                    events.append(DurationEvent(data[i] & constants.CTL_DUR_MASK))
+                    i += 1
+                    continue
+                if i >= n:
+                    break
+                val = data[i]
+            elif val >= constants.DUR_MIN:  # bare duration token
+                events.append(DurationEvent(val & constants.CTL_DUR_MASK))
+                i += 1
+                continue
+            # a note (val < 0x60)
+            note = val
+            i += 1
+            if i >= n:
+                events.append(NoteEvent(note, 0))
+                break
+            ctl = data[i]
+            i += 1
+            args: List[int] = []
+            if ctl >= constants.CTL_FILTER:
+                args = data[i : i + 2]
+                i += 2
+            elif ctl & constants.CTL_VIBARP:
+                args = data[i : i + 2]
+                i += 2
+            events.append(NoteEvent(note, ctl, tuple(args)))
+        return events
+
+
+@dataclass
+class Instrument:
+    """An 8-byte instrument record.
+
+    Fields map to the record bytes the player reads: attack/decay,
+    sustain/release, waveform, pulse-width init + sweep step, arp
+    speed + step, and the porta/effect flags byte.
+    """
+
+    attack_decay: int = 0
+    sustain_release: int = 0
+    waveform: int = 0
+    pulse_init: int = 0
+    pulse_step: int = 0
+    arp_speed: int = 0
+    arp_step: int = 0
+    porta: int = 0
+
+    def to_bytes(self) -> bytes:
+        """The 8 on-disk record bytes."""
+        return bytes(
+            (
+                self.attack_decay & 0xFF,
+                self.sustain_release & 0xFF,
+                self.waveform & 0xFF,
+                self.pulse_init & 0xFF,
+                self.pulse_step & 0xFF,
+                self.arp_speed & 0xFF,
+                self.arp_step & 0xFF,
+                self.porta & 0xFF,
+            )
+        )
+
+    @classmethod
+    def from_bytes(cls, raw) -> "Instrument":
+        """Decode an 8-byte record."""
+        b = list(raw) + [0] * (8 - len(raw))
+        return cls(b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7])
+
+
+@dataclass
+class Song:
+    """A complete Music Assembler song.
+
+    ``load_addr`` is the C64 load address; ``orderlists`` are the three
+    per-voice orderlists; ``patterns`` the shared pattern pool indexed by
+    pattern id; ``instruments`` the 8-byte records indexed by instrument
+    id; ``freq_lo`` / ``freq_hi`` the per-tune split note-frequency
+    tables; ``inner_programs`` the per-instrument effect programs the
+    instrument inner-table indexes (kept as raw bytes for round-trip).
+
+    The remaining fields capture the per-tune table base addresses and
+    any image bytes the player code/data occupy, so the writer can
+    re-emit a byte-stable image.
+    """
+
+    # pylint: disable=too-many-instance-attributes  # a full tune is wide
+    load_addr: int = constants.DEFAULT_LOAD
+    init_addr: int = constants.DEFAULT_INIT
+    play_addr: int = constants.DEFAULT_PLAY
+    name: str = ""
+    author: str = ""
+    released: str = ""
+    orderlists: List[Orderlist] = field(
+        default_factory=lambda: [Orderlist() for _ in range(constants.VOICES)]
+    )
+    patterns: List[Pattern] = field(default_factory=list)
+    instruments: List[Instrument] = field(default_factory=list)
+    freq_lo: List[int] = field(default_factory=list)
+    freq_hi: List[int] = field(default_factory=list)
+    # Raw whole-image bytes (player + data) for byte-stable re-emission.
+    image: bytes = b""
+    # The original container header (PSID/RSID bytes before the image), kept
+    # so a tune read from a ``.sid`` re-emits its exact container; empty for a
+    # bare ``.prg`` or a programmatically built song.
+    container_header: bytes = b""