unitracker-player 0.2.0__py3-none-any.whl

unitracker_player/__init__.py

@@ -0,0 +1,6 @@
+"""The generic player of canonical unitracker documents: SID register state per tick."""
+
+from unitracker_player.document import Document, read
+from unitracker_player.player import Player, PlayError, Song, compile_document, load, play
+
+__all__ = ["Document", "PlayError", "Player", "Song", "compile_document", "load", "play", "read"]

unitracker_player/cli.py

@@ -0,0 +1,37 @@
+"""``unitracker-play FILE [--ticks N] [--out frames.npz|frames.csv]``."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from unitracker_player.player import REGISTERS, load, play
+
+HEADER = ",".join(f"d4{r:02x}" for r in range(REGISTERS))
+
+
+def write(frames: np.ndarray, out) -> None:
+    """``frames`` as an ``.npz`` (array ``frames``) or as CSV, one row per tick, to ``out``: a
+    path or a text stream."""
+    if isinstance(out, Path) and out.suffix == ".npz":
+        np.savez_compressed(out, frames=frames)
+    else:
+        np.savetxt(out, frames, fmt="%d", delimiter=",", header=HEADER, comments="")
+
+
+def main(argv=None) -> int:
+    """Plays FILE and writes its registers per tick to ``--out``, or as CSV to stdout."""
+    args = argparse.ArgumentParser(prog="unitracker-play", description=main.__doc__)
+    args.add_argument("file", type=Path)
+    args.add_argument("--ticks", type=int, help="ticks to play; required for a looping song")
+    args.add_argument("--out", type=Path, help="frames.npz or frames.csv")
+    opts = args.parse_args(argv)
+    if opts.out is not None and opts.out.suffix not in (".npz", ".csv"):
+        args.error(f"--out {opts.out}: write .npz or .csv")
+    try:
+        frames = play(load(opts.file.read_text(encoding="utf-8")), opts.ticks, progress=True)
+    except ValueError as exc:
+        args.error(f"{opts.file}: {exc}")
+    write(frames, opts.out if opts.out is not None else sys.stdout)
+    return 0

unitracker_player/document.py

@@ -0,0 +1,447 @@
+"""A canonical document as plain dataclasses, transformed from its parse tree."""
+
+import json
+import re
+from dataclasses import dataclass, field
+
+import ast
+
+from lark import Token, exceptions
+from unitracker_grammar import CanonicalError, parser
+from unitracker_grammar.expr import Nodes
+
+NONE = None
+_MISSING = object()
+_VALUES = {
+    "INT",
+    "SIGNED",
+    "NOTE",
+    "NOTE_ATOM",
+    "INS",
+    "CTRL",
+    "PW",
+    "FILTER",
+    "RESTART",
+    "X",
+    "PHRASE",
+    "XTABLE",
+    "META_KEY",
+    "TEXT",
+    "SQUOTED",
+    "DQUOTED",
+    "VERSION",
+    "CTRLMASK",
+    "NONE",
+    "NAME",
+}
+_PITCH = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+_NOTE = re.compile(r"([A-G])(#?)(-?\d+)")
+_KINDS = {"restart", "ins", "ctrl", "pw", "filter", "x", "phrase"}
+
+
+def note_number(name: str) -> int:
+    """The format note of a note name: ``12*octave + pitch class`` (C2 is 24, B-1 is -1)."""
+    letter, sharp, octave = _NOTE.fullmatch(name).groups()
+    return 12 * int(octave) + _PITCH[letter] + (1 if sharp else 0)
+
+
+@dataclass(frozen=True)
+class Expr:
+    """A modulator expression as its node (:mod:`unitracker_grammar.expr`)."""
+
+    node: ast.expr
+
+
+@dataclass(frozen=True)
+class Row:
+    """A program row: its timing and its other keys in vocabulary order."""
+
+    wait: int = 0
+    hold: int = 1
+    keys: tuple = ()
+
+
+@dataclass(frozen=True)
+class Program:
+    """Rows in the order they run, then ``end`` (``loop`` None) or ``{loop: k}``."""
+
+    rows: tuple
+    loop: int | None = None
+
+
+@dataclass(frozen=True)
+class Instrument:
+    """An instrument's fields; a program field holds a name or a program, ``freq`` an Expr."""
+
+    ad: int | None = None
+    sr: int | None = None
+    ctrl: str | Program | None = None
+    pw: str | Program | None = None
+    filter: str | Program | None = None
+    freq: Expr | None = None
+    fn: object | None = None
+    p0: dict | None = None
+    restart: str | Program | None = None
+
+
+@dataclass(frozen=True)
+class Event:
+    """An event atom: its note atom, instrument name, commands in vocabulary order, keep flags
+    and steps."""
+
+    note: str
+    ins: str | None = None
+    commands: tuple = ()
+    keep_pw: bool = False
+    keep_filter: bool = False
+    steps: int = 1
+
+
+@dataclass(frozen=True)
+class Play:
+    """A play entry: ``phrase`` (a name and a transpose), ``cont`` (``~``) or ``end``."""
+
+    kind: str
+    phrase: str | None = None
+    transpose: int = 0
+
+
+@dataclass(frozen=True)
+class Header:
+    """The header lines, with their defaults."""
+
+    version: str
+    meta: dict = field(default_factory=dict)
+    cycles_per_tick: int | None = None
+    clock_hz: int | None = None
+    voices: int = 3
+    tempo: tuple = (6, 6)
+
+
+@dataclass(frozen=True)
+class Document:
+    """A whole document: the header, its tables and init row, every definition by name and the
+    timeline's rows of play entries with its ending (``loop`` None for ``end``)."""
+
+    header: Header
+    tables: dict
+    init: tuple | None
+    instruments: dict
+    programs: dict
+    expressions: dict
+    phrases: dict
+    timeline: tuple
+    loop: int | None
+
+
+def _tok(token: Token):
+    if token.type in ("INT", "SIGNED"):
+        return int(token)
+    return NONE if token.type == "NONE" else str(token)
+
+
+def _values(children) -> list:
+    """The children that carry meaning: subtrees' results and value tokens."""
+    return [
+        _tok(c) if isinstance(c, Token) else c
+        for c in children
+        if not isinstance(c, Token) or c.type in _VALUES
+    ]
+
+
+def _words(children) -> list[str]:
+    """The keyword tokens among ``children``, stripped."""
+    return [c.strip() for c in children if isinstance(c, Token) and c.type not in _VALUES]
+
+
+def _link(key):
+    """A link of a key chain: its own key's value (one value or a tuple) before the chain's
+    rest."""
+
+    def method(_self, children):
+        rest, own = {}, []
+        for c in _values(children):
+            if isinstance(c, dict):
+                rest = c
+            else:
+                own.append(c)
+        if not own:
+            return rest
+        return {key: own[0] if len(own) == 1 else tuple(own), **rest}
+
+    return method
+
+
+def _chain(prefix, keys):
+    return {f"{prefix}_{k}": _link(k) for k in keys}
+
+
+class ToDocument(Nodes):
+    """The parse tree of ``canonical.lark`` to a Document; each method is the grammar rule of
+    its name, and an expression's rules are :class:`Nodes`'."""
+
+    # pylint: disable=too-many-public-methods,missing-function-docstring
+
+    def start(self, children):
+        head, defs, timeline = {"tables": {}, "init": None}, {k: {} for k in _KINDS}, []
+        for item in _values(children):
+            tag = item[0]
+            if isinstance(item, str):
+                head["version"] = item
+            elif tag == "row":
+                for kind, entries in item[1]:
+                    for name, value in entries:
+                        if name in defs[kind]:
+                            raise CanonicalError(f"{name} is defined twice")
+                        defs[kind][name] = value
+                timeline.append(item[2])
+            else:
+                head[tag] = item[1]
+        clock = head.pop("clock", (None, None))
+        header = Header(
+            head.pop("version"),
+            head.pop("meta"),
+            *clock,
+            head.pop("voices", 3),
+            head.pop("tempo", (6, 6)),
+        )
+        programs = {**defs["restart"], **defs["ctrl"], **defs["pw"], **defs["filter"]}
+        return Document(
+            header,
+            head["tables"],
+            head["init"],
+            defs["ins"],
+            programs,
+            defs["x"],
+            defs["phrase"],
+            tuple(timeline),
+            head["ending"],
+        )
+
+    @staticmethod
+    def meta(children):
+        return ("meta", dict(_values(children)))
+
+    @staticmethod
+    def meta_item(children):
+        return tuple(_values(children))
+
+    @staticmethod
+    def text(children):
+        (token,) = children
+        if token.type == "SQUOTED":
+            return token[1:-1].replace("''", "'")
+        if token.type == "DQUOTED":
+            return json.loads(token)
+        return str(token)
+
+    @staticmethod
+    def clock(children):
+        return ("clock", tuple(_values(children)))
+
+    @staticmethod
+    def voices(children):
+        return ("voices", _values(children)[0])
+
+    @staticmethod
+    def tempo(children):
+        values = _values(children)
+        return ("tempo", (values[0], values[-1]))
+
+    @staticmethod
+    def tables(children):
+        values = _values(children)
+        return ("tables", dict(zip(values[::2], values[1::2])))
+
+    @staticmethod
+    def intlist(children):
+        return tuple(_values(children))
+
+    @staticmethod
+    def init(children):
+        return ("init", tuple(_values(children)))
+
+    @staticmethod
+    def row(children):
+        values = _values(children)
+        return ("row", values[:-1], values[-1])
+
+    @staticmethod
+    def ending(children):
+        values = _values(children)
+        return ("ending", values[0] if values else None)
+
+    @staticmethod
+    def plays(children):
+        return tuple(_values(children))
+
+    @staticmethod
+    def play(children):
+        values = _values(children)
+        if values:
+            return Play("phrase", values[0], values[1] if len(values) > 1 else 0)
+        return Play("cont" if _words(children) == ["~"] else "end")
+
+    @staticmethod
+    def section(children):
+        kind = children[0].type.lower()
+        values = _values(children)
+        entries = list(zip(values[::2], values[1::2]))
+        if kind == "x":
+            entries = [(n, Expr(v)) for n, v in entries]
+        elif kind in ("pw", "filter"):
+            entries = [(n, _modulation(kind, v)) for n, v in entries]
+        return (kind, entries)
+
+    @staticmethod
+    def instrument(children):
+        values = dict(_values(children)[0])
+        for kind in ("pw", "filter"):
+            if kind in values:
+                values[kind] = _modulation(kind, values[kind])
+        return Instrument(**values)
+
+    @staticmethod
+    def program(children):
+        values = _values(children)
+        if values and isinstance(values[-1], int):
+            return Program(tuple(values[:-1]), values[-1])
+        return Program(tuple(values))
+
+    @staticmethod
+    def modulation(children):
+        return _values(children)[0]
+
+    @staticmethod
+    def ins_fn(children):
+        """``mod: NAME`` and its parameter bag as ``{fn: NAME, p0: the bag}``, the instrument's
+        ``restart`` where it has no modulator, and either where the two share an instrument."""
+        values = _values(children)
+        name = next((v for v in values if not isinstance(v, dict)), None)
+        if name is None:
+            return next((c for c in values if isinstance(c, dict)), {})
+        bag = next((c for c in values if isinstance(c, dict) and "restart" not in c), {})
+        rest = next((c for c in values if isinstance(c, dict) and "restart" in c), {})
+        return {"fn": name, "p0": bag, **rest}
+
+    @staticmethod
+    def param_bag(children):
+        return dict(_values(children))
+
+    @staticmethod
+    def pname_val(children):
+        name, value = _values(children)
+        return str(name), value
+
+    @staticmethod
+    def pname_list(children):
+        return list(_values(children))
+
+    @staticmethod
+    def cmd_set(children):
+        """The event's ``!set`` writes, ``{key: value}``, into a one ``set`` command."""
+        flat = [c for c in _values(children) if not isinstance(c, dict)]
+        rest = next((c for c in children if isinstance(c, dict)), {})
+        bag = dict(zip(flat[::2], flat[1::2]))
+        return {"set": bag, **rest} if bag else rest
+
+    @staticmethod
+    def row_(children):
+        keys = dict(*_values(children))
+        return Row(keys.pop("wait", 0), keys.pop("hold", 1), tuple(keys.items()))
+
+    @staticmethod
+    def ctrl_value(children):
+        (value,) = _values(children)
+        if isinstance(value, int):
+            return (value, None)
+        ctrl, mask = value.split("^")
+        return (int(ctrl) if ctrl else None, int(mask))
+
+    @staticmethod
+    def note_value(children):
+        (value,) = _values(children)
+        return ("rel", value) if isinstance(value, int) else ("abs", note_number(value))
+
+    @staticmethod
+    def pw_value(children):
+        values = _values(children)
+        return values[0] if values else NONE
+
+    @staticmethod
+    def route_value(children):
+        values = _values(children)
+        mask = values[0] if values else 0
+        words = "".join(_words(children))
+        if words.startswith("+"):
+            return ("add", mask)
+        return ("remove", mask) if "-" in words else ("mask", mask)
+
+    @staticmethod
+    def program_name(children):
+        return _values(children)[0]
+
+    @staticmethod
+    def phrase(children):
+        return tuple(_values(children))
+
+    @staticmethod
+    def event(children):
+        values = _values(children)
+        note, rest = values[0], values[1:]
+        ins = rest.pop(0) if rest and isinstance(rest[0], str) else None
+        commands, keep_pw, keep_filter = rest[0], rest[1], rest[2]
+        steps = rest[3] if len(rest) > 3 else 1
+        return Event(note, ins, tuple(commands.items()), keep_pw, keep_filter, steps)
+
+    @staticmethod
+    def cmd_filter(children):
+        rest = next((c for c in children if isinstance(c, dict)), {})
+        return {"filter": NONE, **rest} if _words(children) else rest
+
+    @staticmethod
+    def cmd_legato(children):
+        return {"legato": True} if children else {}
+
+    @staticmethod
+    def keep_pw(children):
+        return bool(children)
+
+    @staticmethod
+    def keep_filter(children):
+        return bool(children)
+
+    def fexpr(self, children):
+        return Expr(super().fexpr(children))
+
+
+for _name, _method in {
+    **_chain(
+        "row", "wait hold ctrl gate note ad sr pw cut res route mode freq run filter vol".split()
+    ),
+    **_chain("ins", "ad sr ctrl pw filter freq restart".split()),
+    **_chain("cmd", "run pw ad sr ctrl resfilt mode vol cut tempo vtempo freq".split()),
+}.items():
+    setattr(ToDocument, _name, _method)
+
+
+def _modulation(kind: str, value):
+    """A pulse or filter modulation as a program: an expression is a one-row program setting
+    the slot's cell."""
+    if isinstance(value, Expr):
+        return Program((Row(keys=(("pw" if kind == "pw" else "cut", value),)),))
+    return value
+
+
+def read(text: str) -> Document:
+    """The Document of canonical document ``text``."""
+    try:
+        tree = parser().parse(text)
+    except exceptions.UnexpectedInput as exc:
+        raise CanonicalError(
+            f"line {exc.line} column {exc.column}: {str(exc).splitlines()[0]}"
+        ) from exc
+    try:
+        return ToDocument().transform(tree)
+    except exceptions.VisitError as exc:
+        raise exc.orig_exc from exc

unitracker_player/expr.py

@@ -0,0 +1,34 @@
+"""Modulator expressions compiled once to Python callables of ``(v, phi, n)`` by
+:mod:`unitracker_grammar.expr`, ``//`` and ``%`` 0 by a divisor of 0."""
+
+import ast
+import functools
+from collections.abc import Callable
+
+from unitracker_grammar import frequency
+from unitracker_grammar.expr import compile_expr as _compiled
+from unitracker_grammar.expr import indexed, tree
+
+Fn = Callable[[int, int, int], int]
+
+
+def note_table(clock_hz: int) -> Callable[[int], int]:
+    """``F(k)`` at ``clock_hz``, cached."""
+    return functools.lru_cache(maxsize=None)(functools.partial(frequency, clock_hz=clock_hz))
+
+
+def constant(node: ast.expr) -> int | None:
+    """The integer an expression is, when it is an integer literal."""
+    return node.value if isinstance(node, ast.Constant) else 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``."""
+    namespace = {"_F": table, "_T": {name: indexed(values) for name, values in tables.items()}}
+    return _compiled(node, namespace, zero=True)
+
+
+def offset(n: int) -> ast.expr:
+    """``F(N) + n``: the expression of an integer ``freq``."""
+    return tree(f"F(N) + {n}")

unitracker_player/modulation.py

@@ -0,0 +1,110 @@
+"""The native frequency oscillations as one arithmetic function each over a parameter bag.
+
+A shape is ``f(bag, v, t, note)``: the bag (the instrument's ``p0``, merged with the
+event's ``!set`` writes), the voice's current word ``v``, the tick ``t`` since its arm, and
+the note's base word ``note``; each is one closed form the player re-evaluates each tick.
+"""
+
+F16 = 0xFFFF
+
+# pylint: disable=unused-argument
+
+
+def _steps(bag, t, at_delay=False):
+    """The steps applied by tick ``t``: the ticks past the ``delay`` (or from it, when the shape
+    steps on the tick the delay elapses), none on a ``skip``."""
+    delay = bag.get("delay", 0)
+    first = delay if at_delay else delay + 1
+    if t < first:
+        return 0
+    held = len([s for s in (bag.get("skip") or ()) if first <= s <= t])
+    return t - first + 1 - held
+
+
+def set_(bag, v, t, note=0):
+    """The note plus the bag's offset, held."""
+    return (note + bag.get("offset", 0)) & bag.get("mask", F16)
+
+
+def ramp(bag, v, t, note=0):
+    """The note plus offset, stepping ``step`` per step, clamped to ``max`` when it climbs,
+    back at the note once ``ticks`` has run, wrapped to the ``mask``."""
+    q = _steps(bag, t)
+    ticks = bag.get("ticks")
+    if ticks is not None and q >= ticks:
+        q = 0
+    step = bag.get("step", 0)
+    out = q * step
+    hi = bag.get("max")
+    if hi is not None and step >= 0:
+        out = min(out, hi)
+    return (note + bag.get("offset", 0) + out) & bag.get("mask", F16)
+
+
+def slew_to_target(bag, v, t, note=0):
+    """The note plus offset, walking ``target`` over the steps of ``step``, the last landing
+    on it."""
+    q = _steps(bag, t)
+    target = bag.get("target", 0)
+    step = max(1, abs(bag.get("step", 1)))
+    land = (abs(target) + step - 1) // step
+    if target == 0 or q >= land:
+        out = target
+    else:
+        out = q * step if target > 0 else -q * step
+    return (note + bag.get("offset", 0) + out) & bag.get("mask", F16)
+
+
+def slew_to_zero(bag, v, t, note=0):
+    """The note plus offset, with a ``start`` run back to zero, ``amp`` plus one per step,
+    the last landing on zero."""
+    amp = bag.get("amp", 0)
+    s = bag.get("start", 0)
+    if s > 0x7FFF:
+        s -= 0x10000
+    if amp <= 0 or s == 0:
+        out = s
+    else:
+        sign, s0 = (1, s) if s > 0 else (-1, -s)
+        land = s0 // (amp + 1)
+        q = _steps(bag, t)
+        out = 0 if q > land else sign * (s0 - q * (amp + 1))
+    return (note + bag.get("offset", 0) + out) & bag.get("mask", F16)
+
+
+def _triangle_prefix(k: int, vcmp: int) -> int:
+    """The sum of the native vibrato's step signs, step 1 to ``k``: the flip is checked on the
+    running time before the step, so the period is 2*extent + 4: extent//2 + 1 plus steps, the
+    negative run, and its complement, net zero."""
+    if k == 0 or vcmp >= 126:
+        return k
+    a = vcmp // 2 + 1
+    b = 2 * a + (vcmp & 1)
+    rem = k % (2 * vcmp + 4)
+    if rem <= a:
+        return rem
+    if rem <= a + b:
+        return a - (rem - a)
+    return a - b + (rem - a - b)
+
+
+def triangle(bag, v, t, note=0):
+    """The note plus offset, with the native vibrato's step of ``step`` on each step of the
+    ``extent``'s period."""
+    q = _steps(bag, t, at_delay=True)
+    if q == 0:
+        return (note + bag.get("offset", 0)) & bag.get("mask", F16)
+    amp = abs(bag.get("step", 0)) or 1
+    vcmp = bag.get("extent", 128)
+    return (note + bag.get("offset", 0) + (amp * _triangle_prefix(q, vcmp)) & F16) & bag.get(
+        "mask", F16
+    )
+
+
+SHAPES = {
+    "set": set_,
+    "ramp": ramp,
+    "slew_to_target": slew_to_target,
+    "slew_to_zero": slew_to_zero,
+    "triangle": triangle,
+}