trackmod 0.2.0__py3-none-any.whl

trackmod/__init__.py

@@ -0,0 +1,79 @@
+import importlib.metadata
+
+from trackmod.core.instruments.instrument import Instrument
+from trackmod.core.instruments.transfer import combine, extract, units
+from trackmod.core.instruments.unit import InstrumentUnit
+from trackmod.core.samples.depth import BitDepth
+from trackmod.core.samples.loop import Loop, LoopMode
+from trackmod.core.samples.sample import Sample
+from trackmod.core.songs.song import Song
+from trackmod.core.voices.convert import flattened, raised
+from trackmod.core.voices.voices import InstrumentVoices, SampleVoices, Voices
+from trackmod.limits.compliance import Compliance
+from trackmod.limits.error import LimitError
+from trackmod.limits.violation import Violation
+from trackmod.module.instrument import InstrumentFile
+from trackmod.module.protocol import TrackerModule
+from trackmod.trackers.it.instrument_file import ITInstrumentFile
+from trackmod.trackers.it.module import ITModule
+from trackmod.trackers.mod.module import MODModule
+from trackmod.trackers.registry import (
+    EXTENSIONS,
+    INSTRUMENT_EXTENSIONS,
+    MODULE_EXTENSIONS,
+    detected,
+    load_module,
+    load_voices,
+    parse_module,
+    parse_voices,
+)
+from trackmod.trackers.s3m.module import S3MModule
+from trackmod.trackers.st.module import STModule
+from trackmod.trackers.xm.instrument_file import XMInstrumentFile
+from trackmod.trackers.xm.module import XMModule
+from trackmod.wave.parser import load_sample, parse_sample
+from trackmod.wave.writer import save_sample, write_sample
+
+__version__ = importlib.metadata.version("trackmod")
+
+__all__ = [
+    "EXTENSIONS",
+    "INSTRUMENT_EXTENSIONS",
+    "MODULE_EXTENSIONS",
+    "BitDepth",
+    "Compliance",
+    "ITInstrumentFile",
+    "ITModule",
+    "Instrument",
+    "InstrumentFile",
+    "InstrumentUnit",
+    "InstrumentVoices",
+    "LimitError",
+    "Loop",
+    "LoopMode",
+    "MODModule",
+    "S3MModule",
+    "STModule",
+    "Sample",
+    "SampleVoices",
+    "Song",
+    "TrackerModule",
+    "Violation",
+    "Voices",
+    "XMInstrumentFile",
+    "XMModule",
+    "combine",
+    "detected",
+    "extract",
+    "flattened",
+    "load_module",
+    "load_sample",
+    "load_voices",
+    "parse_module",
+    "parse_sample",
+    "parse_voices",
+    "raised",
+    "save_sample",
+    "units",
+    "write_sample",
+]

trackmod/binary/bits.py

@@ -0,0 +1,35 @@
+from trackmod.spec.width import BITS_PER_BYTE
+
+
+class BitReader:
+    """Reads variable-width fields from a byte stream, least significant bit first.
+
+    A compressed waveform packs its values at a width that changes as it runs, so the reader keeps a
+    running buffer of whole bytes and hands out whatever width is asked for next. Bytes are drawn in as
+    the buffer runs dry, which is what makes one field cost a shift rather than a walk over its bits.
+    """
+
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+        self._index = 0
+        self._buffer = 0
+        self._available = 0
+
+    def take(self, width: int) -> int:
+        """The next ``width`` bits, as an unsigned integer.
+
+        Raises:
+            ValueError: when the stream holds fewer bits than were asked for.
+        """
+        while self._available < width:
+            if self._index >= len(self._data):
+                raise ValueError(f"the stream holds {self._available} bits, short of the {width} asked for")
+
+            self._buffer |= self._data[self._index] << self._available
+            self._index += 1
+            self._available += BITS_PER_BYTE
+
+        value = self._buffer & ((1 << width) - 1)
+        self._buffer >>= width
+        self._available -= width
+        return value

trackmod/binary/cursor.py

@@ -0,0 +1,101 @@
+from trackmod.binary.records.record import Record
+from trackmod.binary.records.values import ArrayValue, FieldValue
+
+
+class Cursor:
+    """Walks a module's bytes from front to back, which is how every format here is laid out.
+
+    A parser reads sections in the order the file stores them, so a cursor that remembers where it is
+    keeps every offset out of the parsing code.
+    """
+
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+        self._position = 0
+
+    @property
+    def position(self) -> int:
+        """How many bytes have been consumed."""
+        return self._position
+
+    @property
+    def remaining(self) -> int:
+        """How many bytes are left."""
+        return len(self._data) - self._position
+
+    @property
+    def at_end(self) -> bool:
+        """Whether every byte has been consumed."""
+        return self.remaining == 0
+
+    def take(self, count: int) -> bytes:
+        """Consume and return the next ``count`` bytes.
+
+        Raises:
+            ValueError: when fewer than ``count`` bytes remain.
+        """
+        chunk = self.peek(count)
+        self._position += count
+        return chunk
+
+    def byte(self) -> int:
+        """Consume and return the next byte, which is what a stream of markers and columns is read in.
+
+        Raises:
+            ValueError: when the data is spent.
+        """
+        return self.take(1)[0]
+
+    def peek(self, count: int) -> bytes:
+        """Return the next ``count`` bytes without consuming them.
+
+        Raises:
+            ValueError: when fewer than ``count`` bytes remain.
+        """
+        if count < 0:
+            raise ValueError(f"cannot read {count} bytes")
+
+        if count > self.remaining:
+            raise ValueError(f"needed {count} bytes at offset {self._position}, {self.remaining} remain")
+
+        return self._data[self._position : self._position + count]
+
+    def take_at_most(self, count: int) -> bytes:
+        """Consume and return up to ``count`` bytes, stopping where the data ends.
+
+        A file may state a section longer than it goes on to hold, and a player sounds the part that is
+        there rather than refusing the file, so a reader following one needs to do the same.
+        """
+        return self.take(min(count, self.remaining))
+
+    def peek_padded(self, count: int) -> bytes:
+        """Return the next ``count`` bytes, padded with zeroes where the data ends.
+
+        This reads a fixed record out of a file that stops inside it: the fields the data reaches are
+        the ones it stated, and the rest read as the zeroes an empty record holds.
+        """
+        held = self.peek(min(count, self.remaining))
+        return held + bytes(count - len(held))
+
+    def skip(self, count: int) -> None:
+        """Consume ``count`` bytes without returning them.
+
+        Raises:
+            ValueError: when fewer than ``count`` bytes remain.
+        """
+        self.take(count)
+
+    def seek(self, position: int) -> None:
+        """Move to an absolute byte offset.
+
+        Raises:
+            ValueError: when the offset falls outside the data.
+        """
+        if not 0 <= position <= len(self._data):
+            raise ValueError(f"offset {position} falls outside {len(self._data)} bytes")
+
+        self._position = position
+
+    def read(self, record: Record) -> dict[str, FieldValue | ArrayValue]:
+        """Consume one record's worth of bytes and unpack its described fields."""
+        return record.unpack(self.take(record.size))

trackmod/binary/layout.py

@@ -0,0 +1,12 @@
+from collections.abc import Sequence
+
+
+def offsets(blobs: Sequence[bytes], start: int) -> list[int]:
+    """Where each blob lands when they are laid end to end from ``start``."""
+    positions = []
+    position = start
+    for blob in blobs:
+        positions.append(position)
+        position += len(blob)
+
+    return positions

trackmod/binary/nibble.py

@@ -0,0 +1,46 @@
+from trackmod.spec.width import (
+    BYTE_MAX,
+    DECIMAL_BYTE_MAX,
+    DECIMAL_RADIX,
+    NIBBLE_BITS,
+    NIBBLE_MAX,
+)
+
+
+def split_nibbles(value: int) -> tuple[int, int]:
+    """Split a byte into its high and low nibbles.
+
+    Raises:
+        ValueError: when ``value`` does not fit in a byte.
+    """
+    if not 0 <= value <= BYTE_MAX:
+        raise ValueError(f"{value} does not fit in a byte")
+
+    return value >> NIBBLE_BITS, value & NIBBLE_MAX
+
+
+def join_nibbles(high: int, low: int) -> int:
+    """Combine two nibbles into a byte.
+
+    Raises:
+        ValueError: when either nibble exceeds four bits.
+    """
+    if not 0 <= high <= NIBBLE_MAX or not 0 <= low <= NIBBLE_MAX:
+        raise ValueError(f"nibbles {high}, {low} exceed four bits")
+
+    return (high << NIBBLE_BITS) | low
+
+
+def decimal_byte(value: int) -> int:
+    """The byte a tracker reads back as the decimal number ``value``, a digit to each nibble.
+
+    Amiga ProTracker read one parameter as though its two hexadecimal digits were decimal ones, and the
+    trackers that followed it kept the reading, so 16 is stored as ``0x16``.
+
+    Raises:
+        ValueError: when ``value`` needs more than two decimal digits.
+    """
+    if not 0 <= value <= DECIMAL_BYTE_MAX:
+        raise ValueError(f"{value} needs more than two decimal digits")
+
+    return join_nibbles(*divmod(value, DECIMAL_RADIX))

trackmod/binary/pcm/blocks.py

@@ -0,0 +1,20 @@
+from trackmod.core.samples.depth import BitDepth
+from trackmod.core.samples.sample import STEREO_CHANNELS
+
+
+def whole_frames(block: bytes, *, depth: BitDepth) -> bytes:
+    """The head of a stored block that holds whole frames, which is as far as a cut-short block sounds."""
+    return block[: len(block) - len(block) % depth.bytes_per_frame]
+
+
+def paired_channels(data: bytes, *, block: int, depth: BitDepth) -> tuple[bytes, bytes]:
+    """The two channel blocks of a stereo waveform, each read as far as both of them reach.
+
+    A stereo waveform holds each channel's frames in full, the left before the right, so a file stopping
+    inside the block holds all of the left channel and a part of the right. One frame is the pair of
+    amplitudes a player sounds together, so both channels are read to the length they share.
+    """
+    left = whole_frames(data[:block], depth=depth)
+    right = whole_frames(data[block : block * STEREO_CHANNELS], depth=depth)
+    held = min(len(left), len(right))
+    return left[:held], right[:held]

trackmod/binary/pcm/codec.py

@@ -0,0 +1,53 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from trackmod.binary.pcm.encoding import PcmEncoding
+from trackmod.binary.pcm.quantize import dequantize, quantize
+from trackmod.binary.pcm.sign import PcmSign, bias, dtype_for
+from trackmod.core.samples.depth import BitDepth
+
+
+def encode_pcm(
+    pcm: NDArray[np.float64],
+    *,
+    depth: BitDepth,
+    encoding: PcmEncoding,
+    sign: PcmSign,
+) -> bytes:
+    """Serialize float PCM in ``[-1, 1]`` to stored frames.
+
+    The amplitudes are placed in the stored range before they are differenced, which is the order the
+    two axes compose in: a player integrates in the width it reads, so the differences it sums are
+    between the values that width holds.
+
+    Deltas are taken in a width wider than the store and cast back, so a difference that overshoots the
+    stored range wraps exactly as the player's running sum unwraps it. The first stored delta is taken
+    against zero, which makes it the waveform's first stored amplitude.
+    """
+    amplitudes = quantize(pcm, depth) + bias(depth, sign=sign)
+    match encoding:
+        case PcmEncoding.ABSOLUTE:
+            stored = amplitudes
+        case PcmEncoding.DELTA:
+            stored = np.diff(amplitudes, prepend=0)
+
+    return stored.astype(dtype_for(depth, sign=sign)).tobytes()
+
+
+def decode_pcm(
+    data: bytes,
+    *,
+    depth: BitDepth,
+    encoding: PcmEncoding,
+    sign: PcmSign,
+) -> NDArray[np.float64]:
+    """Read stored frames back as float PCM in ``[-1, 1]``."""
+    dtype = dtype_for(depth, sign=sign)
+    stored = np.frombuffer(data, dtype=dtype)
+    match encoding:
+        case PcmEncoding.ABSOLUTE:
+            frames = stored
+        case PcmEncoding.DELTA:
+            frames = np.cumsum(stored, dtype=dtype)
+
+    return dequantize(frames.astype(np.int64) - bias(depth, sign=sign), depth)

trackmod/binary/pcm/encoding.py

@@ -0,0 +1,13 @@
+from enum import StrEnum, unique
+
+
+@unique
+class PcmEncoding(StrEnum):
+    """How a format lays a waveform's frames out on disk.
+
+    Absolute storage writes each frame's amplitude; delta storage writes successive differences and the
+    player integrates them with a running sum in the stored width.
+    """
+
+    ABSOLUTE = "absolute"
+    DELTA = "delta"

trackmod/binary/pcm/quantize.py

@@ -0,0 +1,19 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from trackmod.core.samples.depth import BitDepth
+
+
+def quantize(pcm: NDArray[np.float64], depth: BitDepth) -> NDArray[np.int64]:
+    """Map float PCM in ``[-1, 1]`` onto the signed integer range of ``depth``."""
+    scale = depth.scale
+    return np.clip(
+        np.round(np.asarray(pcm, dtype=np.float64) * scale),
+        -scale,
+        scale - 1,
+    ).astype(np.int64)
+
+
+def dequantize(frames: NDArray[np.int64], depth: BitDepth) -> NDArray[np.float64]:
+    """Map stored integer frames back onto float PCM in ``[-1, 1]``."""
+    return np.asarray(frames, dtype=np.float64) / depth.scale

trackmod/binary/pcm/sign.py

@@ -0,0 +1,39 @@
+from enum import StrEnum, unique
+from typing import Final
+
+from trackmod.core.samples.depth import BitDepth
+
+NO_BIAS: Final = 0
+
+
+@unique
+class PcmSign(StrEnum):
+    """Which stored value a frame of silence sits on.
+
+    Signed storage centers silence on zero, so a frame runs from ``-scale`` to ``scale - 1``. Unsigned
+    storage carries the same amplitudes shifted up by ``scale``, so silence sits in the middle of the
+    range and every stored value is positive.
+    """
+
+    SIGNED = "signed"
+    UNSIGNED = "unsigned"
+
+
+STORED_DTYPES: Final[dict[PcmSign, dict[BitDepth, str]]] = {
+    PcmSign.SIGNED: {BitDepth.EIGHT: "<i1", BitDepth.SIXTEEN: "<i2"},
+    PcmSign.UNSIGNED: {BitDepth.EIGHT: "<u1", BitDepth.SIXTEEN: "<u2"},
+}
+
+
+def dtype_for(depth: BitDepth, *, sign: PcmSign) -> str:
+    """The little-endian numpy dtype one stored frame occupies."""
+    return STORED_DTYPES[sign][depth]
+
+
+def bias(depth: BitDepth, *, sign: PcmSign) -> int:
+    """The amount that separates a stored frame from the signed amplitude it carries."""
+    match sign:
+        case PcmSign.SIGNED:
+            return NO_BIAS
+        case PcmSign.UNSIGNED:
+            return int(depth.scale)

trackmod/binary/records/field.py

@@ -0,0 +1,50 @@
+import struct
+
+from pydantic import BaseModel
+from pydantic import Field as ModelField
+
+from trackmod.schema.config import FROZEN
+
+
+class Field(BaseModel):
+    """One fixed field of a record: a :mod:`struct` value written at a byte offset.
+
+    ``code`` is a ``struct`` format for a single value, such as ``"<I"`` for a 32-bit word, ``"B"`` for a
+    byte, ``"b"`` for a signed byte, or ``"26s"`` for a fixed-length block the caller has already padded.
+    """
+
+    model_config = FROZEN
+
+    name: str = ModelField(min_length=1)
+    offset: int = ModelField(ge=0)
+    code: str = ModelField(min_length=1)
+
+    @property
+    def size(self) -> int:
+        """How many bytes the field occupies."""
+        return struct.calcsize(self.code)
+
+
+class ArrayField(BaseModel):
+    """A contiguous run of fixed-stride elements, such as a keyboard note map.
+
+    ``code`` is the ``struct`` format for one element and its packed size is the stride; each value is a
+    sequence unpacked into that element.
+    """
+
+    model_config = FROZEN
+
+    name: str = ModelField(min_length=1)
+    offset: int = ModelField(ge=0)
+    count: int = ModelField(ge=0)
+    code: str = ModelField(min_length=1)
+
+    @property
+    def stride(self) -> int:
+        """How many bytes one element occupies."""
+        return struct.calcsize(self.code)
+
+    @property
+    def size(self) -> int:
+        """How many bytes the whole run occupies."""
+        return self.stride * self.count

trackmod/binary/records/record.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import struct
+
+from pydantic import BaseModel
+from pydantic import Field as ModelField
+from pydantic import model_validator
+
+from trackmod.binary.records.field import ArrayField, Field
+from trackmod.binary.records.values import ArrayValue, FieldValue, RecordValues
+from trackmod.schema.config import FROZEN
+
+
+class Record(BaseModel):
+    """A fixed-size binary record described as data: a byte size plus the fields laid out within it.
+
+    Stating the layout declaratively keeps every byte offset in one place, so the serializers supply
+    field values and never arithmetic. Offsets a record leaves undescribed are reserved and stay zero
+    when packing.
+    """
+
+    model_config = FROZEN
+
+    size: int = ModelField(ge=0)
+    fields: tuple[Field, ...]
+    arrays: tuple[ArrayField, ...] = ()
+
+    @model_validator(mode="after")
+    def _contained(self) -> Record:
+        for field in self.fields:
+            if field.offset + field.size > self.size:
+                raise ValueError(f"field {field.name!r} runs past the {self.size}-byte record")
+
+        for array in self.arrays:
+            if array.offset + array.size > self.size:
+                raise ValueError(f"array {array.name!r} runs past the {self.size}-byte record")
+
+        return self
+
+    def pack(self, values: RecordValues) -> bytes:
+        """Serialize ``values`` into exactly :attr:`size` bytes.
+
+        Raises:
+            KeyError: when a described field has no value.
+            TypeError: when an array field is given a single value rather than a sequence.
+        """
+        buffer = bytearray(self.size)
+        for field in self.fields:
+            struct.pack_into(field.code, buffer, field.offset, values[field.name])
+
+        for array in self.arrays:
+            rows = values[array.name]
+            if isinstance(rows, (int, bytes)):
+                raise TypeError(f"array {array.name!r} needs a sequence of elements, got {type(rows).__name__}")
+
+            for index, row in enumerate(rows):
+                struct.pack_into(
+                    array.code,
+                    buffer,
+                    array.offset + index * array.stride,
+                    *row,
+                )
+
+        return bytes(buffer)
+
+    def unpack_at(self, data: bytes, offset: int) -> dict[str, FieldValue | ArrayValue]:
+        """Read this record from ``offset``, filling it out with zeroes where the data stops inside it.
+
+        A file states where each of its records sits, and one stating an offset it never reaches is read
+        to the end of what it holds -- the fields the data covers are the ones it stated, and the rest
+        read as the zeroes an empty record holds.
+        """
+        return self.unpack(data[offset : offset + self.size].ljust(self.size, b"\0"))
+
+    def unpack(self, data: bytes) -> dict[str, FieldValue | ArrayValue]:
+        """Read every described field out of ``data``.
+
+        Raises:
+            ValueError: when ``data`` is shorter than the record.
+        """
+        if len(data) < self.size:
+            raise ValueError(f"record needs {self.size} bytes, got {len(data)}")
+
+        values: dict[str, FieldValue | ArrayValue] = {}
+        for field in self.fields:
+            (value,) = struct.unpack_from(field.code, data, field.offset)
+            values[field.name] = value
+
+        for array in self.arrays:
+            values[array.name] = tuple(
+                struct.unpack_from(
+                    array.code,
+                    data,
+                    array.offset + index * array.stride,
+                )
+                for index in range(array.count)
+            )
+
+        return values

trackmod/binary/records/values.py

@@ -0,0 +1,44 @@
+from collections.abc import Mapping, Sequence
+
+FieldValue = int | bytes
+ArrayValue = Sequence[Sequence[int]]
+RecordValues = Mapping[str, FieldValue | ArrayValue]
+
+
+def read_int(values: RecordValues, name: str) -> int:
+    """Read one unpacked field as an integer.
+
+    Raises:
+        TypeError: when the field holds a block of bytes or a run of elements instead.
+    """
+    value = values[name]
+    if not isinstance(value, int):
+        raise TypeError(f"field {name!r} holds {type(value).__name__}, expected an integer")
+
+    return value
+
+
+def read_bytes(values: RecordValues, name: str) -> bytes:
+    """Read one unpacked field as a fixed-length byte block.
+
+    Raises:
+        TypeError: when the field holds an integer or a run of elements instead.
+    """
+    value = values[name]
+    if not isinstance(value, bytes):
+        raise TypeError(f"field {name!r} holds {type(value).__name__}, expected a byte block")
+
+    return value
+
+
+def read_rows(values: RecordValues, name: str) -> ArrayValue:
+    """Read one unpacked array field as its run of elements.
+
+    Raises:
+        TypeError: when the field holds a single value instead.
+    """
+    value = values[name]
+    if isinstance(value, (int, bytes)):
+        raise TypeError(f"field {name!r} holds {type(value).__name__}, expected a run of elements")
+
+    return value

trackmod/binary/text.py

@@ -0,0 +1,31 @@
+from trackmod.spec.text import ENCODING, PADDING, REPLACEMENT
+
+
+def encode_name(text: str, length: int) -> bytes:
+    """Encode ``text`` to exactly ``length`` bytes, null-padded, truncating anything longer.
+
+    Tracker name fields are fixed-width and a player reads the whole width, so a name is padded rather
+    than terminated. Characters outside the tracker character set become ``?``.
+    """
+    raw = text.encode(ENCODING, errors=REPLACEMENT)[:length]
+    return raw + PADDING * (length - len(raw))
+
+
+def decode_name(raw: bytes) -> str:
+    """Read a fixed-width name field back, dropping the padding a writer added."""
+    return raw.split(PADDING, 1)[0].decode(ENCODING, errors=REPLACEMENT)
+
+
+def encode_text(text: str) -> bytes:
+    """Encode ``text`` as a block of its own length, closed by the terminator a reader stops at.
+
+    A block a header points at with an offset and a length is as long as its content, so the terminator
+    is what states where the text ends within the length the header reserves for it. Characters outside
+    the tracker character set become ``?``.
+    """
+    return text.encode(ENCODING, errors=REPLACEMENT) + PADDING
+
+
+def decode_text(raw: bytes) -> str:
+    """Read a terminated text block back, up to where its terminator closes it."""
+    return raw.split(PADDING, 1)[0].decode(ENCODING, errors=REPLACEMENT)