trackmod 0.2.0__py3-none-any.whl

trackmod/binary/volume.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from trackmod.core.volumes.codec import decode_volume
+from trackmod.core.volumes.command import (
+    VolumeCommand,
+    VolumeEffect,
+    VolumeValue,
+)
+from trackmod.limits.bound import Bound
+from trackmod.schema.config import FROZEN
+from trackmod.spec.grid import EMPTY
+
+
+class VolumeSpan(BaseModel):
+    """One run of a volume-column byte: what it states, where the run opens, and the amounts it holds."""
+
+    model_config = FROZEN
+
+    effect: VolumeEffect
+    base: int
+    amounts: Bound
+
+    def holds(self, byte: int) -> bool:
+        """Whether ``byte`` falls inside this run."""
+        return self.amounts.contains(byte - self.base)
+
+    def stated(self, byte: int) -> VolumeCommand:
+        """The command ``byte`` states, at the amount it counts from this run's base."""
+        return VolumeCommand(effect=self.effect, amount=byte - self.base)
+
+    def stored(self, amount: int) -> int:
+        """The byte this run stores ``amount`` as."""
+        return self.base + amount
+
+
+class VolumeColumn(BaseModel):
+    """How one format divides its volume-column byte between levels and the effects it carries beside them.
+
+    A tracker reads the column by the range a byte falls in, so stating those ranges as data is what lets
+    the parser, the packer and the capacity table read one specification. ``absent`` is the byte a format
+    writes where a cell states no volume at all, which the formats storing every column of a cell need.
+    """
+
+    model_config = FROZEN
+
+    level_base: int
+    levels: Bound
+    spans: tuple[VolumeSpan, ...]
+    absent: int | None
+
+    def span(self, effect: VolumeEffect) -> VolumeSpan | None:
+        """The run this column gives ``effect``, where it names one."""
+        return next((span for span in self.spans if span.effect is effect), None)
+
+    def states_volume(self, byte: int) -> bool:
+        """Whether ``byte`` states a volume at all, apart from the byte a format writes for none."""
+        return byte != self.absent
+
+    def stated(self, byte: int) -> VolumeValue | None:
+        """The level or command ``byte`` states, or ``None`` when it names nothing this column defines."""
+        if not self.states_volume(byte):
+            return None
+
+        level = byte - self.level_base
+        if self.levels.contains(level):
+            return level
+
+        return next((span.stated(byte) for span in self.spans if span.holds(byte)), None)
+
+    def stored(self, volume: VolumeValue) -> int | None:
+        """The byte this column stores ``volume`` as, or ``None`` when it cannot state it."""
+        match volume:
+            case VolumeCommand():
+                span = self.span(volume.effect)
+                return span.stored(volume.amount) if span is not None and span.amounts.contains(volume.amount) else None
+            case int():
+                return self.level_base + volume if self.levels.contains(volume) else None
+
+    def encoded(self, volume: VolumeValue) -> int:
+        """The byte this column stores ``volume`` as.
+
+        Raises:
+            ValueError: when the column cannot state ``volume``.
+        """
+        byte = self.stored(volume)
+        if byte is None:
+            raise ValueError(self.refusal(volume))
+
+        return byte
+
+    def stored_code(self, code: int) -> int:
+        """The byte a grid volume code is written as, leaving an absent volume absent.
+
+        Raises:
+            ValueError: when the code names a volume this column cannot state.
+        """
+        if code == EMPTY:
+            return EMPTY
+
+        return self.encoded(decode_volume(code))
+
+    def refusal(self, volume: VolumeValue) -> str:
+        """Why this column cannot state ``volume``."""
+        match volume:
+            case VolumeCommand():
+                span = self.span(volume.effect)
+                if span is None:
+                    return f"the volume column has no run for {volume.effect.name}"
+
+                return f"amount {volume.amount} lies outside {span.amounts}, the amounts its run holds"
+            case int():
+                return f"level {volume} lies outside {self.levels}, the levels the volume column holds"

trackmod/binary/warnings.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import warnings
+from collections import defaultdict
+
+from trackmod.core.patterns.column import Column
+
+
+class UnnamedByteWarning(UserWarning):
+    """A stored byte naming nothing its format defines, which the column it sits in reads as absent."""
+
+
+class UnnamedBytes:
+    """The bytes one parse met that name nothing the format defines, gathered so one warning covers them.
+
+    A file reaching past what this library has a vocabulary for states it in cell after cell, so
+    gathering what was met and reporting once says as much as a warning per cell would -- the way a
+    :class:`~trackmod.limits.checklist.Checklist` gathers the violations of a whole module.
+    """
+
+    def __init__(self) -> None:
+        self._met: dict[Column, set[int]] = defaultdict(set)
+
+    def met(self, byte: int, *, column: Column) -> None:
+        """Record a byte the column names nothing for."""
+        self._met[column].add(byte)
+
+    def warn(self) -> None:
+        """Report everything gathered as one warning, where anything was met."""
+        if not self._met:
+            return
+
+        stated = "; ".join(
+            f"{column} {', '.join(str(byte) for byte in sorted(bytes_met))}" for column, bytes_met in self._met.items()
+        )
+        warnings.warn(
+            f"bytes this format leaves unnamed, read as absent: {stated}",
+            UnnamedByteWarning,
+            stacklevel=2,
+        )

trackmod/core/effects/catalog.py

@@ -0,0 +1,35 @@
+from typing import Protocol
+
+from trackmod.core.effects.effect import Effect
+
+
+class EffectCatalog(Protocol):
+    """The effects every format here expresses, so a caller can author them without picking a format.
+
+    Every method returns the :class:`Effect` its format uses for that intent and validates the argument
+    against the room the format's parameter byte leaves for it.
+    """
+
+    def set_speed(self, ticks: int) -> Effect:
+        """Set the ticks each row lasts."""
+
+    def set_tempo(self, beats_per_minute: int) -> Effect:
+        """Set the tick rate, in the tracker's beats-per-minute units."""
+
+    def position_jump(self, order: int) -> Effect:
+        """Continue playback at the given order-list position."""
+
+    def pattern_break(self, row: int) -> Effect:
+        """End the pattern and continue at the given row of the next order."""
+
+    def note_delay(self, ticks: int) -> Effect:
+        """Delay this cell's note by the given number of ticks into the row."""
+
+    def note_cut(self, ticks: int) -> Effect:
+        """Silence this channel the given number of ticks into the row."""
+
+    def volume_slide(self, *, up: int, down: int) -> Effect:
+        """Slide the channel volume by one nibble per tick, in exactly one direction."""
+
+    def set_panning(self, position: int) -> Effect:
+        """Place the channel on the stereo field, on the shared 0..255 scale."""

trackmod/core/effects/effect.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+
+from trackmod.schema.config import FROZEN
+from trackmod.spec.width import BYTE_MAX
+
+
+class Effect(BaseModel):
+    """One effect-column entry: a format-specific command byte and its parameter byte.
+
+    The pair travels together because a tracker reads them together — a parameter without its command is
+    meaningless. Each format's catalog and command enumeration give the byte values their meaning.
+    """
+
+    model_config = FROZEN
+
+    command: int = Field(ge=0, le=BYTE_MAX)
+    parameter: int = Field(ge=0, le=BYTE_MAX)

trackmod/core/envelopes/curve.py

@@ -0,0 +1,85 @@
+from collections.abc import Sequence
+from typing import Final
+
+from pydantic import BaseModel, Field
+
+from trackmod.core.envelopes.envelope import Envelope
+from trackmod.core.envelopes.point import EnvelopePoint
+from trackmod.core.envelopes.span import EnvelopeSpan
+from trackmod.core.timing.clock import elapsed_ticks, tick_seconds
+from trackmod.limits.bound import Bound
+from trackmod.schema.config import FROZEN
+
+TICK_APART: Final = 1
+
+
+class Breakpoint(BaseModel):
+    """One point of a curve stated in time: the value it reaches ``seconds`` after a voice starts."""
+
+    model_config = FROZEN
+
+    seconds: float = Field(ge=0.0)
+    value: int
+
+
+def placed_ticks(breakpoints: Sequence[Breakpoint], *, tempo: int, bound: Bound) -> tuple[int, ...]:
+    """Where each breakpoint lands on the tick grid, ascending and inside ``bound``.
+
+    A format reads its breakpoints in order and separates them by at least a tick, so two that round onto
+    the same tick are moved apart, and a curve reaching past the last tick a format counts is drawn back
+    into the ticks that remain. Each breakpoint keeps room for the ones behind it, which is what keeps
+    the end of a curve stated where a format would otherwise be handed points it cannot order.
+
+    Raises:
+        ValueError: when the breakpoints outnumber the ticks in ``bound``, leaving nowhere to separate them.
+    """
+    if len(breakpoints) > bound.room:
+        raise ValueError(f"{len(breakpoints)} breakpoints ask for more than the {bound.room} ticks in {bound}")
+
+    placed: list[int] = []
+    for index, point in enumerate(breakpoints):
+        lowest = placed[-1] + TICK_APART if placed else bound.minimum
+        highest = bound.maximum - (len(breakpoints) - 1 - index)
+        placed.append(min(max(elapsed_ticks(point.seconds, tempo), lowest), highest))
+
+    return tuple(placed)
+
+
+def timed_envelope(
+    breakpoints: Sequence[Breakpoint],
+    *,
+    tempo: int,
+    tick_bound: Bound,
+    value_bound: Bound,
+    loop: EnvelopeSpan | None = None,
+    sustain: EnvelopeSpan | None = None,
+) -> Envelope:
+    """An envelope holding a curve given in time, written onto the tick grid ``tempo`` runs.
+
+    A caller fitting a curve to a recording works in seconds and levels; a format stores ticks and node
+    values inside its own ranges. This states the curve once in the terms it was measured in and hands a
+    format what it holds: each breakpoint at the tick it falls on, each value on the grid ``value_bound``
+    names, both spans over the breakpoint indices as given.
+
+    Ticks are relative to ``tempo``, so the same curve written for a different clock is a different
+    envelope -- which is why the tempo a curve was fitted at is worth keeping beside it.
+
+    Raises:
+        ValueError: when the breakpoints outnumber the ticks in ``tick_bound``, or when a span reaches
+            past the breakpoints given.
+    """
+    ticks = placed_ticks(breakpoints, tempo=tempo, bound=tick_bound)
+    points = tuple(
+        EnvelopePoint(tick=tick, value=value_bound.clamp(point.value)) for tick, point in zip(ticks, breakpoints)
+    )
+    return Envelope(points=points, loop=loop, sustain=sustain)
+
+
+def envelope_seconds(envelope: Envelope, *, tempo: int) -> tuple[Breakpoint, ...]:
+    """The curve an envelope holds, read back in time at the tempo it was written for.
+
+    This is the way back from :func:`timed_envelope`, for a caller measuring what a stored curve does
+    against the trajectory it was fitted to.
+    """
+    length = tick_seconds(tempo)
+    return tuple(Breakpoint(seconds=point.tick * length, value=point.value) for point in envelope.points)

trackmod/core/envelopes/envelope.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import itertools
+
+from pydantic import BaseModel, Field, model_validator
+
+from trackmod.core.envelopes.point import EnvelopePoint
+from trackmod.core.envelopes.span import EnvelopeSpan
+from trackmod.schema.config import FROZEN
+
+
+class Envelope(BaseModel):
+    """A breakpoint curve applied to every voice an instrument starts.
+
+    An instrument that carries no envelope of a kind leaves that property alone, so absence rather than
+    an enable flag is what switches an envelope off.
+
+    Points are given in tick order. Two points sharing a tick stand the curve up vertically there, which
+    is how a tracker states an instant change of level.
+    """
+
+    model_config = FROZEN
+
+    points: tuple[EnvelopePoint, ...] = Field(min_length=1)
+    loop: EnvelopeSpan | None = None
+    sustain: EnvelopeSpan | None = None
+
+    @model_validator(mode="after")
+    def _consistent(self) -> Envelope:
+        ticks = [point.tick for point in self.points]
+        if any(later < earlier for earlier, later in itertools.pairwise(ticks)):
+            raise ValueError(f"envelope ticks run backward: {ticks}")
+
+        for name, span in (("loop", self.loop), ("sustain", self.sustain)):
+            if span is not None and span.end >= self.length:
+                raise ValueError(f"envelope {name} span {span.begin}..{span.end} escapes {self.length} points")
+
+        return self
+
+    @property
+    def length(self) -> int:
+        """How many breakpoints the curve holds."""
+        return len(self.points)

trackmod/core/envelopes/kind.py

@@ -0,0 +1,10 @@
+from enum import StrEnum, unique
+
+
+@unique
+class EnvelopeKind(StrEnum):
+    """Which property of a voice an envelope shapes over time."""
+
+    VOLUME = "volume"
+    PANNING = "panning"
+    PITCH = "pitch"

trackmod/core/envelopes/point.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel
+
+from trackmod.schema.config import FROZEN
+from trackmod.schema.scalars import Tick
+
+
+class EnvelopePoint(BaseModel):
+    """One breakpoint: the value the envelope reaches at ``tick``, interpolated from the point before.
+
+    A point sharing its tick with the point before it is reached at once, stating a step in the curve.
+    """
+
+    model_config = FROZEN
+
+    tick: Tick
+    value: int

trackmod/core/envelopes/repair.py

@@ -0,0 +1,85 @@
+from collections.abc import Sequence
+
+from trackmod.core.envelopes.point import EnvelopePoint
+from trackmod.core.envelopes.span import EnvelopeSpan
+from trackmod.core.repairs.report import Repairs
+from trackmod.limits.bound import Bound
+
+
+def repaired_span(
+    bounds: tuple[int, int] | None,
+    *,
+    points: int,
+    name: str,
+    subject: str,
+    repairs: Repairs,
+) -> EnvelopeSpan | None:
+    """The pair of point indices a file states, drawn inside the points the envelope holds.
+
+    A tracker states a loop or a sustain as a pair of point indices, and files carry pairs reaching past
+    the last point or ending before they begin. Both are drawn back to the points that exist: the end to
+    the last point, then the begin to the end, which is the reading players settled on. The pair is taken
+    as the two numbers the record holds, since a span ending before it begins is one this model states no
+    span for.
+    """
+    if bounds is None:
+        return None
+
+    stated_begin, stated_end = bounds
+    end = min(stated_end, points - 1)
+    begin = min(stated_begin, end)
+    if (begin, end) != (stated_begin, stated_end):
+        repairs.made(
+            f"{name} span {stated_begin}..{stated_end} drawn to {begin}..{end}",
+            subject=subject,
+        )
+
+    return EnvelopeSpan(begin=begin, end=end)
+
+
+def repaired_points(
+    points: Sequence[EnvelopePoint],
+    *,
+    subject: str,
+    repairs: Repairs,
+) -> tuple[EnvelopePoint, ...]:
+    """Stored breakpoints put in tick order, holding each one at the tick the one before it reached.
+
+    A curve is read in the order its points are stored, so a point stated at an earlier tick than the
+    one before it is played the moment that one is. Files carry such points where a tracker left the
+    node table longer than the count it uses.
+    """
+    ordered: list[EnvelopePoint] = []
+    for point in points:
+        reached = ordered[-1].tick if ordered else point.tick
+        ordered.append(point if point.tick >= reached else EnvelopePoint(tick=reached, value=point.value))
+
+    moved = sum(1 for before, after in zip(points, ordered) if before.tick != after.tick)
+    if moved:
+        repairs.made(
+            f"{moved} envelope points stated out of order held at the tick before them",
+            subject=subject,
+        )
+
+    return tuple(ordered)
+
+
+def leveled_points(
+    points: Sequence[EnvelopePoint],
+    *,
+    bound: Bound,
+    subject: str,
+    repairs: Repairs,
+) -> tuple[EnvelopePoint, ...]:
+    """Stored breakpoints drawn inside the levels a format's own field holds.
+
+    A tracker states each breakpoint's level in the width its record keeps and leaves the nodes past the
+    count it uses as it found them, so a file states levels in nodes no curve reaches. Each is drawn to
+    the nearest level the field holds, which keeps the curve the file meant.
+    """
+    drawn = tuple(EnvelopePoint(tick=point.tick, value=bound.clamp(point.value)) for point in points)
+    moved = sum(1 for before, after in zip(points, drawn) if before.value != after.value)
+    if moved:
+        repairs.made(f"{moved} envelope levels drawn inside {bound}", subject=subject)
+
+    return drawn

trackmod/core/envelopes/span.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, model_validator
+
+from trackmod.schema.config import FROZEN
+from trackmod.schema.scalars import Index
+
+
+class EnvelopeSpan(BaseModel):
+    """An inclusive range of point indices, as trackers store envelope loop and sustain points."""
+
+    model_config = FROZEN
+
+    begin: Index
+    end: Index
+
+    @model_validator(mode="after")
+    def _ascending(self) -> EnvelopeSpan:
+        if self.end < self.begin:
+            raise ValueError(f"envelope span {self.begin}..{self.end} runs backward")
+
+        return self

trackmod/core/instruments/behavior.py

@@ -0,0 +1,30 @@
+from enum import IntEnum, unique
+
+
+@unique
+class NewNoteAction(IntEnum):
+    """What happens to a channel's playing voice when the same channel starts a new note."""
+
+    CUT = 0
+    CONTINUE = 1
+    NOTE_OFF = 2
+    FADE = 3
+
+
+@unique
+class DuplicateCheck(IntEnum):
+    """What makes two voices of one instrument count as duplicates."""
+
+    OFF = 0
+    NOTE = 1
+    SAMPLE = 2
+    INSTRUMENT = 3
+
+
+@unique
+class DuplicateAction(IntEnum):
+    """What happens to the voice a duplicate check finds."""
+
+    CUT = 0
+    NOTE_OFF = 1
+    FADE = 2

trackmod/core/instruments/fade.py

@@ -0,0 +1,61 @@
+import math
+from typing import Final
+
+from trackmod.core.timing.clock import tick_seconds
+from trackmod.spec.levels import MIN_FADEOUT, NO_FADEOUT
+
+SLOWEST_STEP: Final = 1
+
+
+def fade_ticks(fadeout: int, *, counter: int) -> float:
+    """How many ticks a fading voice takes to reach silence, counting down by ``fadeout`` a tick.
+
+    A voice being faded carries a counter that starts full at ``counter`` and drops by ``fadeout`` every
+    tick, and what remains of it scales the level the voice plays at. So the fadeout an instrument
+    states is a rate, and the time it buys is ``counter / fadeout`` ticks.
+
+    ``NO_FADEOUT`` leaves the counter full, which is a voice that keeps its level for as long as it
+    sounds and reads here as a fade of unbounded length.
+
+    Raises:
+        ValueError: when ``fadeout`` runs backward, or ``counter`` is empty.
+    """
+    if fadeout < MIN_FADEOUT:
+        raise ValueError(f"fadeout {fadeout} is below {MIN_FADEOUT}")
+
+    if counter < SLOWEST_STEP:
+        raise ValueError(f"a fade counter holds at least {SLOWEST_STEP}, got {counter}")
+
+    return math.inf if fadeout == NO_FADEOUT else counter / fadeout
+
+
+def fade_seconds(fadeout: int, *, counter: int, tempo: int) -> float:
+    """How long a fading voice takes to reach silence at ``tempo``.
+
+    Raises:
+        ValueError: when ``fadeout`` runs backward, ``counter`` is empty, or ``tempo`` is below the
+            slowest clock the shared model counts.
+    """
+    return fade_ticks(fadeout, counter=counter) * tick_seconds(tempo)
+
+
+def fadeout_value(seconds: float, *, counter: int, tempo: int) -> int:
+    """The rate an instrument states to fade a voice out over ``seconds`` at ``tempo``.
+
+    This is the way back from :func:`fade_seconds`, for a caller that knows how long a released note
+    should take to die and needs the counter step a format stores.
+
+    Raises:
+        ValueError: when ``seconds`` is at most nothing, or asks for a fade slower than the counter
+            reaches. The slowest fade a format states drops its counter by one a tick, which lasts
+            ``counter`` ticks, and anything slower would round to the value meaning no fade at all.
+    """
+    if seconds <= 0.0:
+        raise ValueError(f"a fade lasts a positive time, got {seconds} seconds")
+
+    value = round(counter * tick_seconds(tempo) / seconds)
+    if value < SLOWEST_STEP:
+        longest = fade_seconds(SLOWEST_STEP, counter=counter, tempo=tempo)
+        raise ValueError(f"a fade of {seconds} s at tempo {tempo} is longer than the {longest} s the counter reaches")
+
+    return value