trackmod 0.2.0__tar.gz

trackmod-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+.claude/
+.idea/
+.ipynb_checkpoints/
+.mypy_cache/
+.pytest_cache/
+.venv/
+.venv-build/
+.vscode/
+dist/
+
+*.pyc
+*.pyo
+*.coverage
+*.coverage.*
+
+*.mod
+*.xm
+*.s3m
+*.it

trackmod-0.2.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# TrackMod
+
+## v0.2.0 [2026-09-25]
+
+* Added support for Amiga ProTracker and Soundtracker (`.mod`) and Scream Tracker 3 (`.s3m`).
+* Added saving and loading sounds as `.wav` files, keeping loops, tuning, volume and panning.
+* Supported modules that go beyond their tracker's original limits.
+* Fixed FastTracker 2 modules losing or mixing up sounds when saved, and names with special characters changing.
+* Fixed modules failing to open: cut-off files, very long patterns and out-of-range values now load.
+* Improved the documentation.
+* Published on PyPI: `pip install trackmod` (Python 3.12 or newer).
+
+## v0.1.0 [2026-09-05]
+
+The first working version of TrackMod, for Impulse Tracker and FastTracker 2.
+
+* Added reading and writing of Impulse Tracker (`.it`) and FastTracker 2 (`.xm`) modules, including notes, effects, volumes and Impulse Tracker's song message and channel and pattern names.
+* Added conversion of a song between the two formats.
+* Added instruments with export to `.iti` or `.xi`.
+* Added sounds, including stereo, loops and reading of Impulse Tracker's compressed sounds.
+* Added size budgeting to plan how many sounds fit.

trackmod-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jakim (Stage Magician)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trackmod-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: trackmod
+Version: 0.2.0
+Summary: Read, write and convert tracker music modules: Impulse Tracker, FastTracker 2, ProTracker, Scream Tracker 3 and Soundtracker
+Project-URL: Homepage, https://github.com/JakimPL/TrackMod
+Project-URL: Repository, https://github.com/JakimPL/TrackMod
+Project-URL: Documentation, https://github.com/JakimPL/TrackMod/tree/main/docs
+Project-URL: Changelog, https://github.com/JakimPL/TrackMod/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/JakimPL/TrackMod/issues
+Author-email: "Jakim (Stage Magician)" <jakimpl@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chiptune,fasttracker,impulse-tracker,it,mod,module,music,protracker,s3m,scream-tracker,soundtracker,tracker,xm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.1
+Requires-Dist: pydantic>=2.7.4
+Description-Content-Type: text/markdown
+
+# TrackMod
+
+[![PyPI](https://img.shields.io/pypi/v/trackmod.svg)](https://pypi.org/project/trackmod/)
+[![Python](https://img.shields.io/pypi/pyversions/trackmod.svg)](https://pypi.org/project/trackmod/)
+[![License](https://img.shields.io/github/license/JakimPL/TrackMod.svg)](https://github.com/JakimPL/TrackMod/blob/main/LICENSE)
+[![CI](https://github.com/JakimPL/TrackMod/actions/workflows/ci.yml/badge.svg)](https://github.com/JakimPL/TrackMod/actions/workflows/ci.yml)
+
+A tracker module is a complete piece of music in one file. It holds the notes, the effects and the recorded
+sounds together. TrackMod reads these files, gives you what is inside, and writes them back.
+
+TrackMod supports five formats:
+
+| Tracker | Module | Single instrument |
+|---|---|---|
+| Impulse Tracker | `.it` | `.iti` |
+| FastTracker 2 | `.xm` | `.xi` |
+| Amiga ProTracker | `.mod` | — |
+| Scream Tracker 3 | `.s3m` | — |
+| Soundtracker | `.mod` | — |
+
+All five formats share one model of a song. This lets you:
+
+* open a file written by one tracker and save it for another,
+* check whether a song fits a format before you write it.
+
+TrackMod does not play audio. It gives you the notes, the settings and the waveforms. Use a player to hear
+them.
+
+## What you can do with it
+
+* Read a module and get the song inside: its patterns, their order, the instruments and the waveforms.
+* Write a song in any of the five formats.
+* Check the file size and find values the format cannot store, before you write.
+* Convert a song from one format to another.
+* Save an instrument as an `.iti` or `.xi` file.
+* Save a waveform as a `.wav` file.
+
+## Installing
+
+TrackMod needs Python 3.12 or newer. Install it from PyPI:
+
+```bash
+pip install trackmod
+```
+
+or add it to a [uv](https://docs.astral.sh/uv/) project:
+
+```bash
+uv add trackmod
+```
+
+This also installs the two libraries TrackMod uses, `numpy` and `pydantic`.
+
+## Reading a file
+
+```python
+from pathlib import Path
+
+from trackmod import load_module
+
+module = load_module(Path("song.it"))
+print(module.song.name)
+print(module.song.patterns[0].cell(row=0, channel=3))
+```
+
+TrackMod reads the format from the file contents, not from its name. A file with a wrong or missing
+extension still opens.
+
+## Writing a song
+
+Pass a song to a format class. You get a module, which can:
+
+* tell you how large the file will be,
+* list the values the format cannot store,
+* write the file.
+
+```python
+from pathlib import Path
+
+from trackmod import Compliance, ITModule
+
+module = ITModule.from_song(song, compliance=Compliance.CANONICAL)
+print(module.size().total)     # how many bytes the file will take
+print(module.violations())     # values the format cannot store, empty when the song is writable
+module.save(Path("song.it"))
+```
+
+`Compliance` sets how strict the check is. See [`docs/reference/limits.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/reference/limits.md).
+
+To write the same song in another format, use another class:
+
+```python
+from trackmod import XMModule
+
+XMModule.from_song(song, compliance=Compliance.EXTENDED).save(Path("song.xm"))
+```
+
+## Saving instruments and waveforms
+
+```python
+from pathlib import Path
+
+from trackmod import Compliance, ITInstrumentFile, load_module, save_sample, units
+
+sounds = Path("sounds")
+for path in Path("modules").iterdir():
+    module = load_module(path)
+    for index, unit in enumerate(units(module.song.voices)):
+        instrument = ITInstrumentFile.from_unit(unit, compliance=Compliance.CANONICAL)
+        instrument.save(sounds / f"{path.stem}-{index:02d}.iti")
+
+    for index, sample in enumerate(module.song.voices.samples):
+        save_sample(sample, sounds / f"{path.stem}-{index:02d}.wav")
+```
+
+`units` gives you every instrument with the waveforms it plays. It works the same for all five formats.
+
+Each `.wav` file keeps the loop points, the tuning, the volume, the panning and the auto-vibrato. You can
+open these files in a tracker or in any audio editor.
+
+## Documentation
+
+See [`docs/`](https://github.com/JakimPL/TrackMod/tree/main/docs):
+
+* [`docs/guide/`](https://github.com/JakimPL/TrackMod/tree/main/docs/guide) — how to do each task,
+* [`docs/reference/`](https://github.com/JakimPL/TrackMod/tree/main/docs/reference) — the song model and the format limits,
+* [`docs/formats/`](https://github.com/JakimPL/TrackMod/tree/main/docs/formats) — the byte layout of each format.
+
+Start at [`docs/README.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/README.md). What changed in each release is in
+[`CHANGELOG.md`](https://github.com/JakimPL/TrackMod/blob/main/CHANGELOG.md).
+
+## Development
+
+[`docs/contributing/development.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/contributing/development.md) covers the tools, the tests
+and the checks a change passes, and [`docs/contributing/releasing.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/contributing/releasing.md)
+covers how a release reaches PyPI.
+
+## License
+
+TrackMod is released under the [MIT License](https://github.com/JakimPL/TrackMod/blob/main/LICENSE).

trackmod-0.2.0/README.md

@@ -0,0 +1,140 @@
+# TrackMod
+
+[![PyPI](https://img.shields.io/pypi/v/trackmod.svg)](https://pypi.org/project/trackmod/)
+[![Python](https://img.shields.io/pypi/pyversions/trackmod.svg)](https://pypi.org/project/trackmod/)
+[![License](https://img.shields.io/github/license/JakimPL/TrackMod.svg)](https://github.com/JakimPL/TrackMod/blob/main/LICENSE)
+[![CI](https://github.com/JakimPL/TrackMod/actions/workflows/ci.yml/badge.svg)](https://github.com/JakimPL/TrackMod/actions/workflows/ci.yml)
+
+A tracker module is a complete piece of music in one file. It holds the notes, the effects and the recorded
+sounds together. TrackMod reads these files, gives you what is inside, and writes them back.
+
+TrackMod supports five formats:
+
+| Tracker | Module | Single instrument |
+|---|---|---|
+| Impulse Tracker | `.it` | `.iti` |
+| FastTracker 2 | `.xm` | `.xi` |
+| Amiga ProTracker | `.mod` | — |
+| Scream Tracker 3 | `.s3m` | — |
+| Soundtracker | `.mod` | — |
+
+All five formats share one model of a song. This lets you:
+
+* open a file written by one tracker and save it for another,
+* check whether a song fits a format before you write it.
+
+TrackMod does not play audio. It gives you the notes, the settings and the waveforms. Use a player to hear
+them.
+
+## What you can do with it
+
+* Read a module and get the song inside: its patterns, their order, the instruments and the waveforms.
+* Write a song in any of the five formats.
+* Check the file size and find values the format cannot store, before you write.
+* Convert a song from one format to another.
+* Save an instrument as an `.iti` or `.xi` file.
+* Save a waveform as a `.wav` file.
+
+## Installing
+
+TrackMod needs Python 3.12 or newer. Install it from PyPI:
+
+```bash
+pip install trackmod
+```
+
+or add it to a [uv](https://docs.astral.sh/uv/) project:
+
+```bash
+uv add trackmod
+```
+
+This also installs the two libraries TrackMod uses, `numpy` and `pydantic`.
+
+## Reading a file
+
+```python
+from pathlib import Path
+
+from trackmod import load_module
+
+module = load_module(Path("song.it"))
+print(module.song.name)
+print(module.song.patterns[0].cell(row=0, channel=3))
+```
+
+TrackMod reads the format from the file contents, not from its name. A file with a wrong or missing
+extension still opens.
+
+## Writing a song
+
+Pass a song to a format class. You get a module, which can:
+
+* tell you how large the file will be,
+* list the values the format cannot store,
+* write the file.
+
+```python
+from pathlib import Path
+
+from trackmod import Compliance, ITModule
+
+module = ITModule.from_song(song, compliance=Compliance.CANONICAL)
+print(module.size().total)     # how many bytes the file will take
+print(module.violations())     # values the format cannot store, empty when the song is writable
+module.save(Path("song.it"))
+```
+
+`Compliance` sets how strict the check is. See [`docs/reference/limits.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/reference/limits.md).
+
+To write the same song in another format, use another class:
+
+```python
+from trackmod import XMModule
+
+XMModule.from_song(song, compliance=Compliance.EXTENDED).save(Path("song.xm"))
+```
+
+## Saving instruments and waveforms
+
+```python
+from pathlib import Path
+
+from trackmod import Compliance, ITInstrumentFile, load_module, save_sample, units
+
+sounds = Path("sounds")
+for path in Path("modules").iterdir():
+    module = load_module(path)
+    for index, unit in enumerate(units(module.song.voices)):
+        instrument = ITInstrumentFile.from_unit(unit, compliance=Compliance.CANONICAL)
+        instrument.save(sounds / f"{path.stem}-{index:02d}.iti")
+
+    for index, sample in enumerate(module.song.voices.samples):
+        save_sample(sample, sounds / f"{path.stem}-{index:02d}.wav")
+```
+
+`units` gives you every instrument with the waveforms it plays. It works the same for all five formats.
+
+Each `.wav` file keeps the loop points, the tuning, the volume, the panning and the auto-vibrato. You can
+open these files in a tracker or in any audio editor.
+
+## Documentation
+
+See [`docs/`](https://github.com/JakimPL/TrackMod/tree/main/docs):
+
+* [`docs/guide/`](https://github.com/JakimPL/TrackMod/tree/main/docs/guide) — how to do each task,
+* [`docs/reference/`](https://github.com/JakimPL/TrackMod/tree/main/docs/reference) — the song model and the format limits,
+* [`docs/formats/`](https://github.com/JakimPL/TrackMod/tree/main/docs/formats) — the byte layout of each format.
+
+Start at [`docs/README.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/README.md). What changed in each release is in
+[`CHANGELOG.md`](https://github.com/JakimPL/TrackMod/blob/main/CHANGELOG.md).
+
+## Development
+
+[`docs/contributing/development.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/contributing/development.md) covers the tools, the tests
+and the checks a change passes, and [`docs/contributing/releasing.md`](https://github.com/JakimPL/TrackMod/blob/main/docs/contributing/releasing.md)
+covers how a release reaches PyPI.
+
+## License
+
+TrackMod is released under the [MIT License](https://github.com/JakimPL/TrackMod/blob/main/LICENSE).

trackmod-0.2.0/docs/README.md

@@ -0,0 +1,50 @@
+# Documentation
+
+TrackMod reads and writes tracker modules through one shared model of a song. These documents cover it from
+three sides: how to use the library, what the model holds, and what each format can store.
+
+## Guides
+
+How to do each task.
+
+| Document | What it covers |
+|---|---|
+| [`guide/reading.md`](guide/reading.md) | Open a file and read what is inside it |
+| [`guide/writing.md`](guide/writing.md) | Write a song to a file in a format you choose |
+| [`guide/converting.md`](guide/converting.md) | Convert a song from one format to another |
+| [`guide/instruments.md`](guide/instruments.md) | Take instruments out of a module and save them as files |
+| [`guide/samples.md`](guide/samples.md) | Read the waveforms and save them as audio |
+| [`guide/budgeting.md`](guide/budgeting.md) | Find out how large a file will be before you write it |
+
+## Reference
+
+The shared model and its limits.
+
+| Document | What it covers |
+|---|---|
+| [`reference/model.md`](reference/model.md) | Songs, patterns, voices, samples, instruments, timing |
+| [`reference/limits.md`](reference/limits.md) | Capabilities, compliance levels, and where every bound comes from |
+| [`reference/effects.md`](reference/effects.md) | The effect column, and the one vocabulary each format spells its own way |
+| [`reference/volume.md`](reference/volume.md) | The volume column: one vocabulary, and what each format's byte reaches |
+
+## Formats
+
+The byte layout of each format. See [`formats/README.md`](formats/README.md) for the five side by side, and
+for the fields they disagree about.
+
+| Document | Format |
+|---|---|
+| [`formats/it.md`](formats/it.md) | Impulse Tracker, `.it` |
+| [`formats/xm.md`](formats/xm.md) | FastTracker 2, `.xm` |
+| [`formats/mod.md`](formats/mod.md) | Amiga ProTracker, `.mod` |
+| [`formats/s3m.md`](formats/s3m.md) | Scream Tracker 3, `.s3m` |
+| [`formats/st.md`](formats/st.md) | Soundtracker, the fifteen-sample `.mod` layout |
+
+## Working on TrackMod
+
+| Document | What it covers |
+|---|---|
+| [`contributing/architecture.md`](contributing/architecture.md) | How the packages are layered, and what each one owns |
+| [`contributing/documentation.md`](contributing/documentation.md) | How these documents are written |
+| [`contributing/development.md`](contributing/development.md) | The tools, the tests and the gates a change passes |
+| [`contributing/releasing.md`](contributing/releasing.md) | How a tag becomes a release on PyPI |

trackmod-0.2.0/docs/contributing/architecture.md

@@ -0,0 +1,103 @@
+# Architecture
+
+The decisions the library's own shape rests on: how the packages are layered, what each one owns, and
+which of them may read which.
+
+## Layers
+
+The library is layered downward: every package reads its own layer and the ones above it in this table.
+
+| Package | Owns |
+|---|---|
+| `trackmod/spec` | Constants every layer shares: the pitch numbering, level ranges, the volume-column grid, the grid sentinel, integer widths, the tracker clock, the tracker character set, this library's own name and version |
+| `trackmod/utils` | Arithmetic the timing lattice leans on: the divisors of a number, and the two of them nearest a candidate |
+| `trackmod/schema` | Pydantic plumbing: the frozen model config, the constrained scalar aliases, the numpy array annotations |
+| `trackmod/limits` | The capability vocabulary, bounds, compliance levels, violations |
+| `trackmod/core` | The format-agnostic music: notes, patterns, samples, instruments, envelopes, voices, songs, timing |
+| `trackmod/binary` | Byte-level machinery: declarative records, a cursor, fixed-width text, PCM quantization and encoding |
+| `trackmod/wave` | The RIFF audio container: its chunk layouts, and a sample written and read as a `.wav` |
+| `trackmod/module` | What a format binding offers: the size report, the storage table, how far a file's values reach, and the `TrackerModule` and `InstrumentFile` protocols |
+| `trackmod/trackers/<lineage>` | What a family of formats inherited from the one that settled it: the Amiga period tables, the fixed cell, the thirty-byte sample record |
+| `trackmod/trackers/<format>` | One format each: its constants, its record layouts, its packers, parsers, size model, module class and instrument-file class |
+
+`tests/test_boundaries.py` reads the import graph and holds this order, so knowing where a name lives is
+knowing what may reach it.
+
+## The package root
+
+`trackmod/__init__.py` carries what a caller needs to **open a file, reach the music inside it, and write
+it back out**. Everything else is imported from the module that defines it.
+
+```python
+from trackmod import Compliance, ITModule, load_module, save_sample, units
+from trackmod.core.patterns.builder import PatternBuilder
+from trackmod.trackers.s3m.settings import S3MSettings
+```
+
+Patterns, cells, envelopes, timing, the settings models, the effect catalogs, the storage and size
+reports and everything under `binary` keep their module paths. They belong to callers building songs
+rather than reading them, and the root stays a surface a newcomer can read in one screen. The root stands
+above every layer and reads all of them; every other `__init__.py` is empty.
+
+## A format package
+
+Each format package repeats the same internal shape, so knowing one is knowing the next:
+
+```
+<format>/
+  spec/         constants only: identity sizes ranges defaults flags cells effects storage capacities
+  layout/       the record layouts, as data: file pattern sample instrument envelope
+  effects/      the command enumeration and the catalog that spells the shared vocabulary
+  patterns/     packer, parser, and the size model that is their exact counterpart
+  samples/      waveform and header serialization
+  instruments/  header serialization, keymaps, envelopes, the standalone instrument file
+  detection limits timing settings sizing writer parser module
+```
+
+The last line is what every format has: what its bytes state about themselves, its capacities read at one
+level, its clock, its own settings, its size model, and the pair that writes and reads a whole file behind
+the module class.
+
+A package holds the subdirectories its own format keeps records for. The three that keep no instrument
+records — Amiga ProTracker, Scream Tracker 3 and Soundtracker — have no `instruments/` and no envelopes,
+and the two Amiga layouts read their `patterns/` and `samples/` from the lineage that holds both.
+
+Each format then adds the files its layout calls for: `note`, `fade`, `checks` and `instrument_file` where
+a format keeps instrument records, `dialect` and `tag` for the four characters that name an Amiga layout,
+`parapointers` and `placement` for the paragraphs Scream Tracker 3's blocks open on, `tuning` where a
+header states a transposition rather than a rate, and `version` where a file numbers its writer.
+
+## Lineage packages
+
+A lineage package sits beside the formats in the same shape and holds what a family of them shares.
+`amiga/` is the one this library has: the period tables, the four-byte cell, the thirty-byte sample record
+and the eight-bit waveform that Ultimate Soundtracker settled and every tracker on that machine kept,
+together with the walk that reads a file of either and the checks that grade a song for both. Its own
+files carry the same names — `reading`, `writing`, `sizing`, `checks`, `note`, `tuning` beside `spec/`,
+`layout/`, `patterns/` and `samples/` — so the shape above reads the same there.
+
+A format package owns every decision its own file layout makes, and every import it makes reaches its
+lineage or a layer beneath it. Two formats sharing a decision because one inherited it from the other
+share it through the lineage, which owns it outright; where they disagree, the lineage takes the answer as
+an argument, so each of them keeps its own. `tests/test_boundaries.py` holds that line.
+
+## Validating versus repairing
+
+> **A validator constrains what the library writes. A parser repairs what it reads, and says so.**
+
+| Situation | Mechanism | Where it is documented |
+|---|---|---|
+| A quantity past what a format holds | `Violation`, collected into one `LimitError` | [`../reference/limits.md`](../reference/limits.md), and the format's capacities |
+| Content with no encoding at all | `ValueError` where it is met | the format document's refusals table |
+| A value a real file states that the model holds no room for | drawn into range, gathered in `Repairs`, reported once as a `RepairWarning` | the format document, under the section that reads it |
+
+A bound says *use a smaller number*. A `ValueError` says *this idea has no home here, express it another
+way*. A repair says *the file stated something odd, and this is what was heard*.
+
+## Types
+
+- Every validated or serialized type is a **frozen** Pydantic model. Bounds live in `Field(...)`
+  constraints, and cross-field rules in `model_validator(mode="after")`.
+- Constants live in `spec/` packages and nowhere else, so the constants read as the specification.
+- Protocols are preferred to base classes, and composition to inheritance. `Reaching` is the one mixin,
+  carrying no fields, no construction and no format knowledge, which is what earns it the exception.

trackmod-0.2.0/docs/contributing/development.md

@@ -0,0 +1,91 @@
+# Development
+
+## The tools
+
+```
+make format     # isort + black
+make lint       # mypy --strict + pylint
+make test       # pytest
+make test-docs  # the examples in docstrings, through --doctest-modules
+make coverage   # pytest with a coverage report
+make build      # the sdist and the wheel in dist/, checked with twine
+```
+
+Dependencies are managed with `uv`, and the package is built with `hatchling`. Every command above runs
+through `uv run`, so a checkout needs no environment of its own.
+
+`pre-commit` runs the same checks on the files a commit touches: trailing whitespace, final newlines,
+YAML and TOML syntax, `isort`, `black`, `zizmor` over the GitHub Actions workflows, `mypy`, `pylint` and
+`make test-docs`, with the full test suite as a pre-push hook. Install it once with
+`uv run pre-commit install`, and run it over everything with `uv run pre-commit run --all-files`.
+
+## Typing
+
+`mypy` runs in `--strict` mode over `src/trackmod`, with the pydantic plugin and `init_typed`. Every
+signature states its input and return types, including `None`, and generic types are filled in:
+`dict[str, int]` rather than a bare `dict`. A cast or an `ignore` is for an untyped or mistyped
+third-party boundary, and nothing else.
+
+## Linting
+
+`pylint` runs over `src/trackmod` with `fail-under=9.9` and the `pylint_pydantic` plugin. Docstring
+requirements for modules, classes and functions are off, because the library carries no module docstrings
+and states class and function intent in its own words rather than to a checker.
+
+Duplicate-code reporting is off, because the five format packages repeat one shape on purpose and every
+remaining report is that shape. What two formats share for a reason belongs to their lineage, and
+`tests/test_boundaries.py` is what holds the line instead.
+
+Both `black` and `isort` run at a line length of 120, `isort` under the `black` profile with `trackmod`
+as the first-party package.
+
+## Tests
+
+The test tree mirrors the source tree: `tests/binary`, `tests/core`, `tests/limits`, `tests/module`,
+`tests/wave` and `tests/trackers/<format>`, with the shared fixtures — a song, its voices, an envelope,
+the waveform helpers — in `tests/conftest.py`.
+
+Three suites sit at the top level and cross those boundaries:
+
+| Suite | What it holds |
+|---|---|
+| `tests/test_formats.py` | One property stated once for every format, through a `Binding` per format |
+| `tests/test_package.py` | What the package root offers, and the loops the guide shows, end to end |
+| `tests/test_boundaries.py` | The import graph: the layer order, and what a format or lineage package may read |
+
+`filterwarnings = ["error"]` means a stray `RepairWarning` fails a test rather than printing, so a parser
+that starts repairing something new is caught where it happens. Coverage gates at 90 percent.
+
+## Style
+
+- Keep code modular around clear ownership boundaries, and prefer subpackages to large modules.
+- A function with several meaningful steps splits into helpers with one responsibility each.
+- Names are written out: `note`, not `n`.
+- Default values are for what is rarely changed, and each one is a `Final` constant at module level.
+- Let failures crash unless the code can recover meaningfully. Bare `except` and `except Exception` are
+  out; an error-handling block covers only what can fail.
+- The library carries no module docstrings and no code comments. Class and function docstrings state
+  intent; the domain and format narrative lives in these documents. A comment is for a tensor shape, a
+  third-party quirk, or an invariant the code cannot show on its own.
+- An example in a docstring is written as a doctest, so `make test-docs` runs it. Write one only where it
+  is self-contained: `filterwarnings = ["error"]` applies there too, so an example that trips a
+  `RepairWarning` fails.
+
+## Continuous integration
+
+[`ci.yml`](../../.github/workflows/ci.yml) runs on every push to `main` and every pull request:
+
+| Job | What it runs |
+|---|---|
+| Checks | Every `pre-commit` hook over the whole tree, `make coverage` and `make build` |
+| Tests | The suite on Linux, Windows and macOS, under Python 3.12, 3.13 and 3.14 |
+| Lowest dependencies | The suite on the oldest `numpy` and `pydantic` that `pyproject.toml` allows |
+
+Every job installs from `uv.lock` and fails when the lock is out of date, except the lowest-dependencies
+job, which resolves the floors afresh. The actions are pinned to commit hashes, and Dependabot proposes
+new pins once a month. Releases have their own workflow, described in [`releasing.md`](releasing.md).
+
+## Commit messages
+
+One line, in the form *Did: what* — `Added: the fifteen-sample Soundtracker layout`, `Fixed: the
+truncations that read as silence`, `Rewrote: the README in plain English`.