pygoattracker 0.1.2__tar.gz → 0.1.4__tar.gz

{pygoattracker-0.1.2 → pygoattracker-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygoattracker
-Version: 0.1.2
+Version: 0.1.4
 Summary: Pure-Python reader, writer, and player for GoatTracker 2 (.SNG) songs
 Author: Josh Bailey
 License:                                  Apache License

{pygoattracker-0.1.2 → pygoattracker-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pygoattracker"
-version = "0.1.2"
+version = "0.1.4"
 description = "Pure-Python reader, writer, and player for GoatTracker 2 (.SNG) songs"
 readme = "README.md"
 requires-python = ">=3.10"

{pygoattracker-0.1.2 → pygoattracker-0.1.4}/src/pygoattracker/player.py

@@ -89,9 +89,31 @@ class Player:
         adparam: int = constants.DEFAULT_ADPARAM,
         optimize_pulse: bool = True,
         optimize_realtime: bool = True,
+        freq_table=None,
+        simplepulse: bool = False,
     ):
         if not 0 <= subtune < len(song.subtunes):
             raise GoatTrackerError(f"no such subtune: {subtune}")
+        # The editor playroutine (gplay.c) reads a fixed note-frequency table
+        # zero-padded to 128 entries. The PACKED player (gt2reloc/player.s) lays
+        # the table out as ``freqtbllo[firstnote..lastnote]`` followed
+        # immediately by ``freqtblhi[...]`` with NO padding, then the songtable;
+        # an out-of-range note (a wavetable relative step past the last note)
+        # therefore overruns into the adjacent relocated memory and yields an
+        # image-specific frequency. ``freq_table`` lets a caller (the packed-SID
+        # decompiler) supply that exact 128-entry table read from the image so
+        # the render reproduces the packed player's overrun frequencies. When
+        # None the editor's zero-padded ``constants.FREQ_TABLE`` is used.
+        self._freq_table = (
+            constants.FREQ_TABLE if freq_table is None else tuple(freq_table)
+        )
+        # ``simplepulse`` selects the packed player's SIMPLEPULSE pulse code
+        # path (greloc's one-byte pulse optimization), which computes pulse
+        # width differently from the editor player. The pulse table must then
+        # be the PACKED table (greloc's set-pulse byte + swapped speed); see
+        # ``_pulse_exec_simple``. Default False = the editor's full-mod path,
+        # so .SNG / editor playback is unchanged.
+        self.simplepulse = simplepulse
         self.adparam = adparam & 0xFFFF
         self.optimize_pulse = optimize_pulse
         self.optimize_realtime = optimize_realtime
@@ -201,7 +223,7 @@ class Player:
         return self._rtable[table][(ptr - 1) & 0xFF]
 
     def _freq(self, note: int) -> int:
-        return constants.FREQ_TABLE[note & 0x7F]
+        return self._freq_table[note & 0x7F]
 
     def _speed_value(self, idx: int, chan: _Channel) -> int:
         """16-bit speedtable value; high bit selects realtime calculation."""
@@ -537,6 +559,9 @@ class Player:
             self._toneporta(chan, chan.cmddata)
 
     def _pulse_exec(self, chan: _Channel) -> None:
+        if self.simplepulse:
+            self._pulse_exec_simple(chan)
+            return
         ptbl = constants.PTBL
         if self._lt(ptbl, chan.pulse_table_ptr) == constants.TABLEJUMP:
             chan.pulse_table_ptr = self._rt(ptbl, chan.pulse_table_ptr)
@@ -558,6 +583,50 @@ class Player:
             if not chan.pulsetime:
                 chan.pulse_table_ptr = (chan.pulse_table_ptr + 1) & 0xFF
 
+    def _pulse_exec_simple(self, chan: _Channel) -> None:
+        """SIMPLEPULSE pulse executor (player.s mt_setpulse/mt_pulsemod,
+        ``.IF SIMPLEPULSE != 0``).
+
+        greloc's SIMPLEPULSE optimization (greloc.c ~888/1302) packs the
+        pulse table so a SET-PULSE step is ONE byte ``(pulsehi & 0x0f) |
+        (pulselo & 0xf0)`` and the modulation speed is pre-swapped
+        (``swapnybbles``). The packed player keeps a single ghost pulse byte:
+        mt_setpulse stores that one packed byte to BOTH ghostpulselo and
+        ghostpulsehi (no separate hi store, no ``& 0x0F``), and mt_pulsemod
+        does an 8-bit ``lo = lo + speed + carry`` accumulate writing the same
+        byte to both lo and hi. The SID then masks the high pulse nibble to 12
+        bits. The editor player (``_pulse_exec``) instead computes
+        ``pulse = (left & 0x0f) << 8 | right`` giving pulse-hi 0 where this
+        packed player gives pulse-hi = the packed byte's low nibble.
+
+        ``chan.pulse`` carries that single packed byte in its low 8 bits; the
+        12-bit SID pulse is ``((byte & 0x0f) << 8) | byte``.
+        """
+        ptbl = constants.PTBL
+        if self._lt(ptbl, chan.pulse_table_ptr) == constants.TABLEJUMP:
+            chan.pulse_table_ptr = self._rt(ptbl, chan.pulse_table_ptr)
+            if not chan.pulse_table_ptr:
+                return
+        byte = chan.pulse & 0xFF
+        if not chan.pulsetime:
+            left = self._lt(ptbl, chan.pulse_table_ptr)
+            if left >= 0x80:
+                # Set pulse: one packed byte -> both lo and hi ghost registers.
+                byte = self._rt(ptbl, chan.pulse_table_ptr)
+                chan.pulse = ((byte & 0x0F) << 8) | byte
+                chan.pulse_table_ptr = (chan.pulse_table_ptr + 1) & 0xFF
+                return
+            chan.pulsetime = left
+        if chan.pulsetime:
+            # mt_pulsemod: lo = lo + speed + carry-out; hi = lo (same byte).
+            speed = self._rt(ptbl, chan.pulse_table_ptr)
+            total = byte + speed
+            byte = (total + (total >> 8)) & 0xFF
+            chan.pulse = ((byte & 0x0F) << 8) | byte
+            chan.pulsetime -= 1
+            if not chan.pulsetime:
+                chan.pulse_table_ptr = (chan.pulse_table_ptr + 1) & 0xFF
+
     def _get_new_notes(self, channel: int, chan: _Channel) -> None:
         pattern = self._patterns[chan.pattnum]
         newnote = pattern[chan.pattptr]

{pygoattracker-0.1.2 → pygoattracker-0.1.4}/src/pygoattracker.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygoattracker
-Version: 0.1.2
+Version: 0.1.4
 Summary: Pure-Python reader, writer, and player for GoatTracker 2 (.SNG) songs
 Author: Josh Bailey
 License:                                  Apache License

{pygoattracker-0.1.2 → pygoattracker-0.1.4}/tests/test_player.py

@@ -89,6 +89,24 @@ def test_single_note_timeline(song):
     assert (constants.CONTROL_REG, 0x09) in frames[55]
 
 
+def test_freq_table_override(song):
+    """A per-instance ``freq_table`` overrides the editor's fixed note table so
+    the packed-SID decompiler can reproduce the packed player's overrun
+    frequencies (it lays the table out unpadded, so out-of-range notes read
+    adjacent image bytes). Default (None) keeps the editor table."""
+    # The default render emits C-4 at the standard table frequency.
+    base = play(Player(song), 60)
+    assert (constants.FREQ_LO_REG, C4_FREQ & 0xFF) in base[8]
+    assert (constants.FREQ_HI_REG, C4_FREQ >> 8) in base[8]
+    # Override note 48 (C-4) to an arbitrary image-specific value; the render
+    # now emits that frequency for the same note, nothing else changes.
+    table = list(constants.FREQ_TABLE)
+    table[48] = 0xBEEF
+    frames = play(Player(song, freq_table=table), 60)
+    assert (constants.FREQ_LO_REG, 0xEF) in frames[8]
+    assert (constants.FREQ_HI_REG, 0xBE) in frames[8]
+
+
 def test_keyoff_keyon(song):
     song.patterns[0].rows[4] = Row(note=constants.KEYOFF)
     song.patterns[0].rows[5] = Row(note=constants.KEYON)
@@ -323,6 +341,57 @@ def test_pulse_low_byte_unmasked(song):
     assert player.regs[constants.PULSE_LO_REG] == 0x01
 
 
+def test_simplepulse_set_writes_packed_byte_to_both_nibbles(song):
+    # greloc's SIMPLEPULSE optimization packs a set-pulse step into one byte and
+    # the packed player stores it to BOTH ghostpulselo and ghostpulsehi.  For a
+    # packed set byte $88 the SID pulse is ((0x88 & 0x0f) << 8) | 0x88 == $888
+    # (pulse-hi nibble = the byte's low nibble), whereas the editor player
+    # computes (left & 0x0f) << 8 | right == $088 (pulse-hi 0).
+    song.pulsetable.left = [0x80, 0xFF]
+    song.pulsetable.right = [0x88, 0x00]
+    song.instruments[0].pulse_ptr = 1
+    editor = Player(song)
+    play(editor, 10)
+    assert (editor.regs[3] << 8) | editor.regs[2] == 0x088
+
+    packed = Player(song, simplepulse=True)
+    play(packed, 10)
+    assert (packed.regs[3] << 8) | packed.regs[2] == 0x888
+
+
+def test_simplepulse_modulation_accumulates_one_byte(song):
+    # SIMPLEPULSE modulation does lo = lo + speed + carry and mirrors the byte
+    # into pulse-hi.  Start at packed byte $08, then a 16-step modulation of $10:
+    # the byte walks $08,$18,$28,... and pulse-hi tracks its low nibble ($8).
+    song.pulsetable.left = [0x80, 0x10, 0xFF]
+    song.pulsetable.right = [0x08, 0x10, 0x00]
+    song.instruments[0].pulse_ptr = 1
+    player = Player(song, simplepulse=True)
+    play(player, 10)
+    history = []
+    for _ in range(20):
+        player.play_frame()
+        history.append((player.regs[3], player.regs[2]))  # (hi, lo)
+    # The defining SIMPLEPULSE invariant: the one ghost byte feeds both pulse
+    # registers, so pulse-hi is ALWAYS the low nibble of pulse-lo (the editor's
+    # 12-bit pulse keeps an independent hi byte and would not hold this).
+    assert all(hi == (lo & 0x0F) for hi, lo in history)
+    # While in the $10-per-step ramp the low byte climbs by $10 (low nibble
+    # fixed at $8) until a low-nibble carry advances the table.
+    assert history[0] == (0x08, 0x28)
+    assert history[2] == (0x08, 0x38)
+
+
+def test_simplepulse_default_off_matches_editor(song):
+    # Default simplepulse=False leaves the editor pulse path byte-identical.
+    song.pulsetable.left = [0x88, 0x10, 0xFF]
+    song.pulsetable.right = [0x00, 0x40, 0x00]
+    song.instruments[0].pulse_ptr = 1
+    a = reg_history(song, 40, constants.PULSE_HI_REG)
+    b = reg_history(song, 40, constants.PULSE_HI_REG, simplepulse=False)
+    assert a == b
+
+
 def test_filter_program():
     # A long pattern so the looping song does not retrigger the note
     # (and with it the filter program) during the measurement.