Development

Architecture

src/musiscape/
  io.py           Collection / Album / Track — folder-shaped data model
  features.py     per-track interpretable descriptors (cached features.json)
  corpus.py       album stats, PCA landscape, similarity, tonal spread
  categorize.py   k-means + silhouette, self-describing signatures
  figures.py      fingerprints, landscape, affinity (CVD-safe palette)
  thumbnails.py   16 card styles, contact sheets, posters
  report.py       everything → per-collection README.md
  cli.py          probe|extract|fingerprint|landscape|categorize|report|
                  thumbnails|poster

Shared machinery lives in ambiscape.music (pulse clarity, fifths-circle statistics, TARTYP thresholds) — musiscape depends on ambiscape>=0.16 and never re-implements those.

Testing

pytest tests/ — end-to-end on a synthetic two-album collection (plucked vs. drone) whose ground truth is known: features must separate the albums, clustering must recover them, every card style must render, the report must build. Synthetic fixtures caught real bugs during development; keep them adversarial.

Release process

CI (ci.yml) runs the suite on Python 3.10 and 3.12 on every push. Releases: bump version in pyproject.toml, commit, tag vX.Y.Z, push, create a GitHub release — python-publish.yml builds and uploads to PyPI via trusted publishing (environment pypi, no tokens). Docs deploy to GitHub Pages from main via docs.yml (mkdocs-material + mkdocstrings).

Roadmap

• Full-TARTYP classes: homogeneous (Hn/Hx), pedals, eccentric large objects — ≈ Thoresen's fifteen cardinal cases; drones deserve better than "held N".
• [tags] extra: mutagen-based metadata enrichment.
• Optional embedding-based categorisation ([embed]) alongside the interpretable mode.
• Arc-diagram and keyscape tuning options; per-album TARSOM summaries.