unitracker-player 0.2.0__tar.gz → 0.4.0__tar.gz

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitracker-player
-Version: 0.2.0
+Version: 0.4.0
 Summary: Plays canonical unitracker documents to SID register state per tick
 Author: Josh Bailey
 License:                                  Apache License
@@ -247,6 +247,7 @@ frames = play(text, ticks=3000)   # a looping song needs ticks
 song = load(text)                 # parse and compile once; play(song, ...) reuses it
 player = Player(song)
 regs = player.step()              # the 25 registers after one tick; None once the song ends
+player.regs                       # the register file the last tick wrote, one store per register
 ```
 
 `read(text)` returns the document as plain dataclasses. A text outside the grammar raises

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/README.md

@@ -22,6 +22,7 @@ frames = play(text, ticks=3000)   # a looping song needs ticks
 song = load(text)                 # parse and compile once; play(song, ...) reuses it
 player = Player(song)
 regs = player.step()              # the 25 registers after one tick; None once the song ends
+player.regs                       # the register file the last tick wrote, one store per register
 ```
 
 `read(text)` returns the document as plain dataclasses. A text outside the grammar raises

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitracker-player"
-version = "0.2.0"
+version = "0.4.0"
 description = "Plays canonical unitracker documents to SID register state per tick"
 readme = "README.md"
 requires-python = ">=3.12"

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/src/unitracker_player/player.py

@@ -16,6 +16,7 @@ from unitracker_player.modulation import SHAPES
 VERSION = "1.20"
 MAX_VOICES = 3
 REGISTERS = 25
+ENVELOPE = ("ad", "sr")
 CONTROL, PULSE, FILTER = range(3)
 FREQ_MASK, PW_MASK, CUT_MASK = 0xFFFF, 0xFFF, 0x7FF
 
@@ -364,11 +365,13 @@ class _Voice:
 
 class Player:
     """Plays a Song one tick at a time; ``step()`` returns the registers at the end of the
-    tick, or None once the song has ended."""
+    tick, or None once the song has ended. ``regs`` is the register file the last tick wrote,
+    each register by its own statement, so a line tracer sees one store per register."""
 
     def __init__(self, song: Song):
         self.song = song
         self.tick = 0
+        self.regs = [0] * REGISTERS
         self.voices = [_Voice() for _ in range(song.voices)]
         self.cut = self.res = self.route = self.mode = self.vol = 0
         self.cut_prog = self.cut_cmd = None
@@ -396,6 +399,10 @@ class Player:
             return [(t, (v, event, transpose, ins, None, None))]
         *ahead, (last, _) = ins.restart
         if isinstance(event.note, int):
+            if ahead:
+                wait, hold, ops = ahead[-1][0]
+                envelope = tuple(op for op in event.ops if op[0] in ENVELOPE)
+                ahead[-1] = ((wait, hold, ops + envelope), ahead[-1][1])
             for row, before in ahead:
                 if t - before >= 0:
                     self._lookahead[t - before].append((v, row))
@@ -436,26 +443,22 @@ class Player:
         return self.registers()
 
     def registers(self) -> list:
-        """The 25 register values."""
-        regs = [0] * REGISTERS
+        """The 25 register values, written to ``regs``."""
+        regs = self.regs
         for v, voice in enumerate(self.voices):
-            ctrl = ((voice.ctrl ^ voice.mask) & 0xFE) | (voice.ctrl & voice.gate & 1)
-            regs[7 * v : 7 * v + 7] = [
-                voice.freq & 0xFF,
-                voice.freq >> 8,
-                voice.pw & 0xFF,
-                voice.pw >> 8,
-                ctrl,
-                voice.ad,
-                voice.sr,
-            ]
-        regs[21:25] = [
-            self.cut & 7,
-            self.cut >> 3,
-            self.res << 4 | self.route,
-            self.mode | self.vol,
-        ]
-        return regs
+            at = 7 * v
+            regs[at] = voice.freq & 0xFF
+            regs[at + 1] = voice.freq >> 8
+            regs[at + 2] = voice.pw & 0xFF
+            regs[at + 3] = voice.pw >> 8
+            regs[at + 4] = ((voice.ctrl ^ voice.mask) & 0xFE) | (voice.ctrl & voice.gate & 1)
+            regs[at + 5] = voice.ad
+            regs[at + 6] = voice.sr
+        regs[21] = self.cut & 7
+        regs[22] = self.cut >> 3
+        regs[23] = self.res << 4 | self.route
+        regs[24] = self.mode | self.vol
+        return list(regs)
 
     def _start(self, v: int, kind: int, prog: CProgram | None, t: int):
         running = prog is not None and bool(prog.rows)

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/src/unitracker_player.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitracker-player
-Version: 0.2.0
+Version: 0.4.0
 Summary: Plays canonical unitracker documents to SID register state per tick
 Author: Josh Bailey
 License:                                  Apache License
@@ -247,6 +247,7 @@ frames = play(text, ticks=3000)   # a looping song needs ticks
 song = load(text)                 # parse and compile once; play(song, ...) reuses it
 player = Player(song)
 regs = player.step()              # the 25 registers after one tick; None once the song ends
+player.regs                       # the register file the last tick wrote, one store per register
 ```
 
 `read(text)` returns the document as plain dataclasses. A text outside the grammar raises

{unitracker_player-0.2.0 → unitracker_player-0.4.0}/tests/test_player.py

@@ -202,6 +202,32 @@ def test_a_note_less_event_splits_at_its_restart_lookahead(phrase, address, expe
     assert reg(play(doc(phrase, LEAD % HR3)), address) == expected
 
 
+FIRST_TICK = "[{hold: 2, gate: 0, ad: 15, sr: 0}, {ctrl: 9, gate: 1, ad: 9, sr: 240}, {}, end]"
+
+
+@pytest.mark.parametrize(
+    "phrase, restart, address, expected",
+    [
+        ("[C4.i1, D4, -*2]", FIRST_TICK, 5, [9] * 3 + [15] * 2 + [9] * 19),
+        ("[C4.i1, D4!ad:10, -*2]", FIRST_TICK, 5, [9] * 3 + [15] * 2 + [10] * 19),
+        ("[C4.i1, D4!sr:155, -*2]", FIRST_TICK, 6, [240] * 3 + [0] * 2 + [155] * 19),
+        ("[C4.i1, D4!sr:155, -*2]", FIRST_TICK, 5, [9] * 3 + [15] * 2 + [9] * 19),
+        ("[C4.i1, D4!ad:10!legato, -*2]", FIRST_TICK, 5, [9] * 6 + [10] * 18),
+        ("[C4.i1!ad:10, -*3]", FIRST_TICK, 5, [10] * 24),
+        ("[C4.i1, D4!ad:10, -*2]", HR, 5, [9] * 5 + [10] * 19),
+        ("[C4.i1, D4!ad:10, -*2]", "[{ctrl: 9}, end]", 5, [9] * 6 + [10] * 18),
+    ],
+)
+def test_a_notes_envelope_commands_apply_with_its_restarts_first_tick_row(
+    phrase, restart, address, expected
+):
+    """A note's !ad and !sr apply after its restart's last lookahead row, on that row's tick,
+    winning over the row's own ad and sr, and again on the note's tick after its instrument;
+    its other commands, a dropped row, a restart of one row and !legato leave them on its
+    tick."""
+    assert reg(play(doc(phrase, LEAD % restart)), address) == expected
+
+
 def test_a_note_triggers_on_its_step_after_its_restart_lookahead():
     """The frequency and the instrument's envelope take the note on its step."""
     frames = play(doc("[C4.i1, D4, -*2]", LEAD % HR))
@@ -479,6 +505,17 @@ def test_the_player_steps_until_the_song_ends():
     assert regs[24] is None and player.step() is None
 
 
+def test_regs_is_the_register_file_each_tick_rewrites():
+    """`Player.regs` holds the last tick's registers; each step returns a copy of it."""
+    player = Player(load(doc()))
+    first = player.step()
+    assert first == player.regs and first is not player.regs
+    player.voices[0].ad = 0x5A
+    after = player.registers()
+    assert [i for i, (x, y) in enumerate(zip(first, after)) if x != y] == [5]
+    assert after[5] == player.regs[5] == 0x5A and first[5] == 9
+
+
 def _twice(text: str) -> str:
     return text.replace("      ins:\n", "      ins:\n        i1: {ad: 1}\n", 1)