unitracker-player 0.3.0__tar.gz → 0.5.0__tar.gz

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitracker-player
-Version: 0.3.0
+Version: 0.5.0
 Summary: Plays canonical unitracker documents to SID register state per tick
 Author: Josh Bailey
 License:                                  Apache License
@@ -211,7 +211,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: unitracker-grammar>=0.3.0
+Requires-Dist: unitracker-grammar>=0.4.0
 Requires-Dist: lark>=1.2
 Requires-Dist: numpy>=1.26
 Requires-Dist: tqdm>=4.66

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitracker-player"
-version = "0.3.0"
+version = "0.5.0"
 description = "Plays canonical unitracker documents to SID register state per tick"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,7 +12,7 @@ license = { file = "LICENSE" }
 authors = [{ name = "Josh Bailey" }]
 classifiers = ["Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3"]
 dependencies = [
-  "unitracker-grammar>=0.3.0",
+  "unitracker-grammar>=0.4.0",
   "lark>=1.2",
   "numpy>=1.26",
   "tqdm>=4.66",

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/src/unitracker_player/document.py

@@ -33,6 +33,8 @@ _VALUES = {
     "CTRLMASK",
     "NONE",
     "NAME",
+    "HOLD_CELL",
+    "HOLD_EVENT",
 }
 _PITCH = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
 _NOTE = re.compile(r"([A-G])(#?)(-?\d+)")
@@ -108,7 +110,7 @@ class Play:
 
 @dataclass(frozen=True)
 class Header:
-    """The header lines, with their defaults."""
+    """The header lines, with their defaults; ``hold`` is ``{cell: ((event, k), ...)}``."""
 
     version: str
     meta: dict = field(default_factory=dict)
@@ -116,6 +118,7 @@ class Header:
     clock_hz: int | None = None
     voices: int = 3
     tempo: tuple = (6, 6)
+    hold: dict = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -204,6 +207,7 @@ class ToDocument(Nodes):
             *clock,
             head.pop("voices", 3),
             head.pop("tempo", (6, 6)),
+            head.pop("hold", {}),
         )
         programs = {**defs["restart"], **defs["ctrl"], **defs["pw"], **defs["filter"]}
         return Document(
@@ -248,6 +252,15 @@ class ToDocument(Nodes):
         values = _values(children)
         return ("tempo", (values[0], values[-1]))
 
+    @staticmethod
+    def hold(children):
+        return ("hold", dict(_values(children)))
+
+    @staticmethod
+    def hold_cell(children):
+        cell, *events = _values(children)
+        return cell, tuple((name, int(k or 0)) for name, _, k in (e.partition("-") for e in events))
+
     @staticmethod
     def tables(children):
         values = _values(children)

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/src/unitracker_player/expr.py

@@ -24,9 +24,11 @@ def constant(node: ast.expr) -> int | None:
 
 def compile_expr(node: ast.expr, table: Callable[[int], int], tables: dict) -> Fn:
     """``node`` as a callable of ``(v, phi, n)``, reading ``F`` from ``table`` and ``T[k]`` from
-    ``tables``."""
+    ``tables``; the callable's ``node`` is ``node``."""
     namespace = {"_F": table, "_T": {name: indexed(values) for name, values in tables.items()}}
-    return _compiled(node, namespace, zero=True)
+    fn = _compiled(node, namespace, zero=True)
+    fn.node = node
+    return fn
 
 
 def offset(n: int) -> ast.expr:

{unitracker_player-0.3.0 → unitracker_player-0.5.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
 
@@ -77,6 +78,8 @@ class Song:
     loop: int | None
     lookahead: int
     table: object
+    hold: dict
+    horizon: int
 
 
 def _tempo(value, where: str) -> tuple:
@@ -256,6 +259,8 @@ def compile_document(doc: Document) -> Song:
         raise PlayError(f"song: loop row {doc.loop} out of range")
     instruments = [v for k, v in comp.memo.items() if k[0] == "ins"]
     lookahead = max((r[0][1] for i in instruments if (r := i.restart)), default=0)
+    hold = {cell: frozenset(events) for cell, events in head.hold.items()}
+    earliest = max((k for events in hold.values() for _, k in events), default=0)
     return Song(
         head.voices,
         _tempo(head.tempo, "tempo"),
@@ -265,6 +270,8 @@ def compile_document(doc: Document) -> Song:
         doc.loop,
         lookahead,
         table,
+        hold,
+        lookahead + earliest,
     )
 
 
@@ -313,8 +320,8 @@ class _Sequencer:
             self.end = t
 
     def advance(self, limit: int) -> list:
-        """The events whose steps begin by tick ``limit``, as ``(tick, voice, event,
-        transpose)``."""
+        """The steps that begin by tick ``limit``, as ``(tick, voice, event, transpose, last)``:
+        ``event`` None for a step an event's ``*k`` times, ``last`` for a phrase's last step."""
         out = []
         while self.end is None:
             live = [v for v in range(self.voices) if not self.stopped[v]]
@@ -329,14 +336,16 @@ class _Sequencer:
                     break
                 due = [v for v in due if not self.stopped[v]]
             for v in due:
+                event = None
                 if self.rest[v]:
                     self.rest[v] -= 1
-                    continue
-                event = self.phrase[v][self.pos[v]]
-                self.pos[v] += 1
-                self.rest[v] = event.steps - 1
-                out.append((t, v, event, self.transpose[v]))
-                self._retime(v, event)
+                else:
+                    event = self.phrase[v][self.pos[v]]
+                    self.pos[v] += 1
+                    self.rest[v] = event.steps - 1
+                    self._retime(v, event)
+                last = not self.rest[v] and self.pos[v] == len(self.phrase[v])
+                out.append((t, v, event, self.transpose[v], last))
             for v in due:
                 self.next[v] = t + self.tempo[v][self.phase[v]]
                 self.phase[v] ^= 1
@@ -362,7 +371,7 @@ class _Voice:
         return None if self.note is None else self.note + self.relative
 
 
-class Player:
+class Player:  # pylint: disable=too-many-instance-attributes
     """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. ``regs`` is the register file the last tick wrote,
     each register by its own statement, so a line tracer sees one store per register."""
@@ -378,6 +387,8 @@ class Player:
         self._ins = [None] * song.voices
         self._events = defaultdict(list)
         self._lookahead = defaultdict(list)
+        self._held = defaultdict(set)
+        self._noted = [None] * song.voices
         self._init = [i for v, e in enumerate(song.init) for _, i in self._schedule(0, v, e, 0)]
 
     @property
@@ -398,6 +409,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))
@@ -411,12 +426,35 @@ class Player:
             if has
         ]
 
+    def _hold_step(self, t: int, v: int, event: CEvent | None, last: bool):
+        """The hold ticks of voice ``v``'s step at tick ``t``: the tick of each event it is, and
+        of its read, by the restart of the voice's instrument before the step's event."""
+        at = {"step": t, "last": t if last else None, "read": None}
+        if event is not None and isinstance(event.note, int):
+            at["legato" if event.legato else "note"] = t
+        ins = self._ins[v]
+        if ins is not None:
+            at["read"] = t - (ins.restart[0][1] if ins.restart else 0)
+        for cell, events in self.song.hold.items():
+            self._held[v, cell].update(at[e] - k for e, k in events if at.get(e) is not None)
+
+    def _holds(self, v: int, cell: str, t: int) -> bool:
+        """Whether tick ``t`` is one of voice ``v``'s hold events of ``cell``."""
+        rowed = ("row", 0) in self.song.hold.get(cell, ()) and t in self._held[v, "row"]
+        return rowed or t in self._held[v, cell]
+
+    def _advance(self, t: int):
+        """Schedules the steps that begin by the song's horizon past tick ``t``."""
+        for tick, v, event, transpose, last in self._seq.advance(t + self.song.horizon):
+            self._hold_step(tick, v, event, last)
+            if event is not None:
+                for at, item in self._schedule(tick, v, event, transpose):
+                    self._events[at].append(item)
+
     def step(self) -> list | None:
         """Plays one tick."""
         t = self.tick
-        for tick, v, event, transpose in self._seq.advance(t + self.song.lookahead):
-            for at, item in self._schedule(tick, v, event, transpose):
-                self._events[at].append(item)
+        self._advance(t)
         if self.finished:
             return None
         if t == 0:
@@ -476,7 +514,9 @@ class Player:
                 raise PlayError(f"voice {v + 1}: a program loops in no time at tick {t}")
             seen.add((id(prog), index))
             _, hold, ops = prog.rows[index]
-            self._apply(v, ops, t, False)
+            self._apply(v, ops, t, False, kind == CONTROL)
+            if kind == CONTROL and any(key not in ("ctrl", "gate") for key, _ in ops):
+                self._held[v, "row"].add(t)
             if slots[kind] is not slot or slot[0] is None:
                 continue
             index += 1
@@ -490,8 +530,11 @@ class Player:
     def _row(self, v: int, row: tuple, t: int, first: bool = False):
         self._apply(v, row[2], t, first)
 
-    def _apply(self, v: int, ops: tuple, t: int, first: bool):  # pylint: disable=too-many-branches
-        """A row's keys, in vocabulary order; ``first`` marks a restart's first-tick row."""
+    # pylint: disable-next=too-many-branches,too-many-arguments,too-many-positional-arguments
+    def _apply(self, v: int, ops: tuple, t: int, first: bool, ctrl: bool = False):
+        """A row's keys, in vocabulary order; ``first`` marks a restart's first-tick row,
+        ``ctrl`` a control program's row, whose modulators hold on the ``ctrl.`` cells."""
+        held = "ctrl." if ctrl else ""
         voice = self.voices[v]
         for key, value in ops:
             if key == "ctrl":
@@ -515,11 +558,11 @@ class Player:
                 if value is None:
                     self._stop_pulse(v)
                 else:
-                    voice.pw_prog = [value, 0]
+                    voice.pw_prog = [value, 0, held + "pw", None, None]
             elif key == "cut":
-                self.cut_prog = [value, 0, v]
+                self.cut_prog = [value, 0, v, held + "cut", None, None]
             elif key == "freq":
-                voice.freq_prog = [value, 0]
+                voice.freq_prog = [value, 0, held + "freq", self._before(v, t), None]
             elif key == "run":
                 self._start(v, value[0], value[1], t)
             elif key == "filter":
@@ -554,6 +597,7 @@ class Player:
             voice.note = event.note + transpose
             if not event.legato:
                 voice.relative, voice.absolute, voice.gate = 0, None, 1
+                self._noted[v] = t
                 if ins is not None:
                     self._instrument(v, ins, event, t)
         elif event.note is not None and part != "ops":
@@ -573,7 +617,7 @@ class Player:
             self._start(v, PULSE, ins.pw, t)
         if ins.filter is not None and not event.keep_filter:
             self._start(v, FILTER, ins.filter, t)
-        voice.freq_prog = None if ins.freq is None else [ins.freq, 0]
+        voice.freq_prog = None if ins.freq is None else [ins.freq, 0, "freq", -1, None]
         self._arm_osc(voice, ins.fn, ins.p0)
         voice.freq_cmd = voice.pw_cmd = None
         if self.cut_cmd and self.cut_cmd[2] == v:
@@ -587,7 +631,7 @@ class Player:
             else:
                 self._start(v, value[0], value[1], t)
         elif key == "pw":
-            voice.pw_cmd = None if value is None else [value, 0]
+            voice.pw_cmd = None if value is None else [value, 0, "pw", None, None]
             if value is None:
                 self._stop_pulse(v)
         elif key == "filter":
@@ -601,9 +645,9 @@ class Player:
         elif key == "resfilt":
             self.res, self.route = value[0] & 15, value[1] & 15
         elif key == "cut":
-            self.cut_cmd = [value, 0, v]
+            self.cut_cmd = [value, 0, v, "cut", None, None]
         elif key == "freq":
-            voice.freq_cmd = None if value is None else [value, 0]
+            voice.freq_cmd = None if value is None else [value, 0, "freq", self._before(v, t), None]
             if value is not None:
                 voice.osc = None
         elif key == "set":
@@ -617,34 +661,59 @@ class Player:
         if fn is None:
             voice.osc = None
             return
-        voice.osc = [fn, dict(p0) if p0 else {}, 0]
+        voice.osc = [fn, dict(p0) if p0 else {}, 0, "freq", -1, None]
+
+    def _owner(self, t: int, cmd: list | None, prog: list | None, v: int | None = None) -> tuple:
+        """``(modulator, held)`` of the command, else the program modulator, held by voice
+        ``v`` (the cutoff's: the voice that set it); ``(None, False)`` for neither."""
+        mod = cmd or prog
+        if mod is None:
+            return None, False
+        return mod, self._holds(mod[2] if v is None else v, mod[-3], t)
+
+    def _before(self, v: int, t: int) -> int | None:
+        """A frequency modulator's φ before its first firing: -1 for one set on the tick a note
+        starts, else None (the frequency keeps its value)."""
+        return -1 if self._noted[v] == t else None
 
     def _fire(self):
+        t = self.tick
         for vix, voice in enumerate(self.voices):
+            n = voice.sounding
             if voice.osc is not None:
-                n = voice.sounding
                 base = self.song.table(n) if n is not None else 0
-                fn, bag, tick = voice.osc
+                fn, bag = voice.osc[0], voice.osc[1]
                 base = (base + bag.get("detune", 0) * vix) & FREQ_MASK
-                voice.freq = fn(bag, voice.freq, tick, base) & FREQ_MASK
-                voice.osc[2] += 1
+                if at := _firing(voice.osc, 2, self._holds(vix, "freq", t), voice.freq):
+                    voice.freq = fn(bag, *at, base) & FREQ_MASK
                 continue
-            mod, n = voice.freq_cmd or voice.freq_prog, voice.sounding
-            if mod:
-                voice.freq = mod[0](voice.freq, mod[1], n or 0) & FREQ_MASK
-                mod[1] += 1
-            elif n is not None:
-                voice.freq = self.song.table(n)
-        for voice in self.voices:
-            mod = voice.pw_cmd or voice.pw_prog
-            if mod:
-                voice.pw = mod[0](voice.pw, mod[1], voice.sounding or 0) & PW_MASK
-                mod[1] += 1
-        mod = self.cut_cmd or self.cut_prog
-        if mod:
-            n = self.voices[mod[2]].sounding
-            self.cut = mod[0](self.cut, mod[1], n or 0) & CUT_MASK
-            mod[1] += 1
+            mod, held = self._owner(t, voice.freq_cmd, voice.freq_prog, vix)
+            if mod is None:
+                if n is not None:
+                    voice.freq = self.song.table(n)
+            elif at := _firing(mod, 1, held, voice.freq):
+                voice.freq = mod[0](*at, n or 0) & FREQ_MASK
+        for vix, voice in enumerate(self.voices):
+            mod, held = self._owner(t, voice.pw_cmd, voice.pw_prog, vix)
+            if mod and (at := _firing(mod, 1, held, voice.pw)):
+                voice.pw = mod[0](*at, voice.sounding or 0) & PW_MASK
+        mod, held = self._owner(t, self.cut_cmd, self.cut_prog)
+        if mod and (at := _firing(mod, 1, held, self.cut)):
+            self.cut = mod[0](*at, self.voices[mod[2]].sounding or 0) & CUT_MASK
+        for ticks in self._held.values():
+            ticks.discard(t)
+
+
+def _firing(mod: list, at: int, held: bool, v: int) -> tuple | None:
+    """The ``(v, φ)`` modulator ``mod`` (its φ at ``at``, then its key, its φ before its first
+    firing and its last firing's ``(v, φ)``) is evaluated at with the cell's value ``v``, or
+    None to keep it: on a hold tick its last firing's, before its first ``(v, φ before)`` or
+    None, φ not advancing; else ``v`` and its φ, which then advances."""
+    if held:
+        return mod[-1] or (None if mod[-2] is None else (v, mod[-2]))
+    mod[-1] = (v, mod[at])
+    mod[at] += 1
+    return mod[-1]
 
 
 def play(source, ticks: int | None = None, progress: bool = False) -> np.ndarray:

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/src/unitracker_player.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitracker-player
-Version: 0.3.0
+Version: 0.5.0
 Summary: Plays canonical unitracker documents to SID register state per tick
 Author: Josh Bailey
 License:                                  Apache License
@@ -211,7 +211,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: unitracker-grammar>=0.3.0
+Requires-Dist: unitracker-grammar>=0.4.0
 Requires-Dist: lark>=1.2
 Requires-Dist: numpy>=1.26
 Requires-Dist: tqdm>=4.66

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/src/unitracker_player.egg-info/SOURCES.txt

@@ -15,5 +15,6 @@ src/unitracker_player.egg-info/requires.txt
 src/unitracker_player.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_document.py
+tests/test_hold.py
 tests/test_modulation.py
 tests/test_player.py

{unitracker_player-0.3.0 → unitracker_player-0.5.0}/src/unitracker_player.egg-info/requires.txt

@@ -1,4 +1,4 @@
-unitracker-grammar>=0.3.0
+unitracker-grammar>=0.4.0
 lark>=1.2
 numpy>=1.26
 tqdm>=4.66

unitracker_player-0.5.0/tests/test_hold.py

@@ -0,0 +1,150 @@
+"""Holds: a modulator repeats its last firing on its cell's hold events (docs/semantics.md)."""
+
+import ast
+
+import pytest
+from song import cutoff, doc, freq, pulse
+from unitracker_grammar import frequency as F
+
+from unitracker_player import Player, load, play
+
+SWEEP = "{ctrl: [{ctrl: 65}, end], pw: 10*φ + 1}"
+
+
+def sweep(held: set, ticks: int, start: int = 0) -> list:
+    """``10*φ + 1`` from ``start``, φ advancing on every tick but ``held``, 0 before; a held
+    tick before the first firing keeps the pulse width."""
+    out, phi, last = [], 0, 0
+    for t in range(ticks):
+        if t >= start:
+            if t in held:
+                out.append(last)
+                continue
+            last = 10 * phi + 1
+            phi += 1
+        out.append(last)
+    return out
+
+
+@pytest.mark.parametrize(
+    "hold, held",
+    [
+        ("step", {0, 3, 6, 9}),
+        ("step-1", {2, 5, 8}),
+        ("step-2", {1, 4, 7}),
+        ("last", {9}),
+        ("last-1", {8}),
+        ("note", {0, 9}),
+        ("note-1", {8}),
+        ("legato", {3}),
+    ],
+)
+def test_a_pulse_holds_on_its_events(hold, held):
+    text = doc(
+        phrase="[C4.i1, D4!legato, -.i1!pw, E4!pw]",
+        ins=SWEEP,
+        head=f"tempo: 3\nhold: {{pw: [{hold}]}}\n",
+    )
+    assert pulse(play(text, 12)) == sweep(held, 12)
+
+
+def test_a_modulator_held_on_the_tick_it_starts_fires_first_on_its_next():
+    """A note starts the instrument's pulse on a held step: the step keeps the pulse width, and
+    the pulse fires first on the next tick."""
+    text = doc(phrase="[C4.i1, D4]", ins=SWEEP, head="tempo: 3\nhold: {pw: [step]}\n")
+    assert pulse(play(text, 6)) == [0, 1, 11, 11, 1, 11]
+
+
+def test_a_read_is_the_step_less_its_instrument_s_restart_lookahead():
+    """The voice reads its step its instrument's lookahead earlier, the instrument it plays before
+    the step names another; a voice with no instrument reads nothing."""
+    ins = {
+        "i1": "{ctrl: [{ctrl: 65}, end], pw: 10*φ + 1, restart: [{hold: 2, gate: 0}, {}, end]}",
+        "i2": "{ctrl: [{ctrl: 65}, end], restart: [{hold: 1, gate: 0}, {}, end]}",
+    }
+    text = doc(
+        phrase="[-, C4.i1, -, -.i2!pw, -!pw]", ins=ins, head="tempo: 4\nhold: {pw: [read]}\n"
+    )
+    held = {6, 10, 15}
+    assert pulse(play(text, 20)) == sweep(held, 20, start=4)
+
+
+def test_a_control_program_row_holds_on_any_key_but_ctrl_and_gate():
+    """A row setting a note is a row event; one setting only ctrl and gate is not, nor is a
+    restart's row. The held frequency repeats its last firing at the row's new note."""
+    ins = (
+        "{ctrl: [{ctrl: 65}, {gate: 1}, {note: +12}, {ctrl: 64}, end], freq: F(N) + φ,"
+        " restart: [{hold: 1, sr: 1}, {}, end]}"
+    )
+    text = doc(phrase="[C4.i1, -*2]", ins=ins, head="tempo: 3\nhold: {freq: [row]}\n")
+    c4, c5 = F(48), F(60)
+    assert freq(play(text, 6)) == [c4, c4 + 1, c5 + 1, c5 + 2, c5 + 3, c5 + 4]
+
+
+def test_a_held_frequency_follows_its_note_and_a_recurrence_holds_its_value():
+    """On a held legato tick a closed form takes the new note, a recurrence keeps its word."""
+    for expr, expected in (
+        ("F(N) + φ", [F(48), F(48) + 1, F(50) + 1, F(50) + 2]),
+        ("v + 1 + (φ < 1)*F(N)", [F(48) + 1, F(48) + 2, F(48) + 2, F(48) + 3]),
+    ):
+        ins = f"{{ctrl: [{{ctrl: 65}}, end], freq: {expr}}}"
+        text = doc(phrase="[C4.i1, D4!legato]", ins=ins, head="tempo: 2\nhold: {freq: [legato]}\n")
+        assert freq(play(text, 4)) == expected
+
+
+def test_a_note_s_frequency_is_at_phi_minus_1_before_its_first_firing():
+    """A note's command and its instrument's frequency, held before their first firings, play
+    their values at φ -1; a command no note starts keeps the frequency."""
+    text = doc(
+        phrase="[C4.i1!freq:x1, -!freq:none, D4!freq:x2!legato, -]",
+        ins="{ctrl: [{ctrl: 65}, end], freq: F(N) + φ}",
+        x={"x1": "F(N) + 100", "x2": "v + 7"},
+        head="tempo: 2\nhold: {freq: [step]}\n",
+    )
+    c4 = F(48)
+    assert freq(play(text, 6)) == [c4 + 100, c4 + 100, c4 - 1, c4, c4, c4 + 7]
+
+
+def test_a_shape_holds_its_tick():
+    """An instrument's modulator shape repeats its last tick too."""
+    text = doc(
+        phrase="[C4.i1, -]",
+        ins="{ctrl: [{ctrl: 65}, end], mod: ramp {step: 5}}",
+        head="tempo: 2\nhold: {freq: [step]}\n",
+    )
+    base = F(48)
+    assert freq(play(text, 4)) == [base, base, base, base + 5]
+
+
+def test_the_cutoff_holds_on_the_events_of_the_voice_that_set_it():
+    """Voice 2 sets the cutoff; voice 1's steps do not hold it, voice 2's do."""
+    head = "voices: 2\ntempo: 2\nhold: {cut: [step]}\n"
+    text = doc(
+        phrase={"p1": "[C4.i1!vtempo:3*3]", "p2": "[C4.i2, -, -*2]"},
+        ins={"i1": "{ctrl: [{ctrl: 65}, end]}", "i2": "{ctrl: [{ctrl: 65}, end], filter: 8*φ + 8}"},
+        rows=("[p1, p2]",),
+        head=head,
+    )
+    assert cutoff(play(text, 8)) == [0, 8, 8, 16, 16, 24, 24, 32]
+
+
+def test_no_hold_line_holds_nothing():
+    text = doc(phrase="[C4.i1, D4!legato, -]", ins=SWEEP, head="tempo: 3\n")
+    assert pulse(play(text, 9)) == sweep(set(), 9)
+
+
+def test_a_compiled_expression_carries_its_node():
+    song = load(doc(ins="{ctrl: [{ctrl: 65}, end], pw: 10*φ + 1}"))
+    player = Player(song)
+    player.step()
+    assert ast.unparse(player.voices[0].pw_prog[0].node) == "10 * φ + 1"
+
+
+@pytest.mark.parametrize(
+    "hold, expected", [("freq", [0, 1, 2, 3, 4]), ("ctrl.freq", [-1, -1, -1, 0, 1])]
+)
+def test_a_control_row_s_modulator_holds_on_the_ctrl_cell(hold, expected):
+    """A control row's frequency holds on ``ctrl.freq``'s events alone; its rows hold it."""
+    ins = "{ctrl: [{ctrl: 65, freq: F(N) + φ}, {note: +0}, {note: +0}, end]}"
+    text = doc(phrase="[C4.i1, -*3]", ins=ins, head=f"tempo: 4\nhold: {{{hold}: [row]}}\n")
+    assert [f - F(48) for f in freq(play(text, 5))] == expected

{unitracker_player-0.3.0 → unitracker_player-0.5.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))