Cataloguebook

Cataloguebook is an offline, local reference builder for an independent label or multi-release artist project. It turns one TOML file into a readable catalogue, a structured release register, a separate link register, and a manifest—without opening any platform page or changing any live service.

It complements Releaseledger, which prepares one release handoff. Cataloguebook tracks a sequence of declared release records across a label or project. It does not inspect or update Bandcamp, SoundCloud, a distributor, a shop, streaming service, or website.

Every generated human-readable file begins with:

DECLARED CATALOGUE - PUBLICATION, LINK, RIGHTS, AND AVAILABILITY STATUS UNVERIFIED

A released status, a URL, and a date are author-entered reference fields. They do not prove correct metadata, upload, processing, public availability, playable media, link freshness, rights clearance, ownership, royalty status, or acceptance.

What it does

• validates label name/prefix and a series of declared release records;
• requires unique catalogue numbers and a nonempty suffix after the declared label prefix;
• validates ISO dates, controlled release statuses/formats, and safe HTTP(S) link syntax;
• creates CATALOGUE.md, catalogue.csv, link_register.csv, and manifest.json in a new output directory;
• retains the user’s declared release order rather than inventing a chronology or catalogue-number sequence.

What it does not do

• no network, browser, platform, distributor, shop, payment, rights, or publishing integration;
• no link fetch, authentication, upload, release creation, status update, notification, website edit, or metadata submission;
• no technical/audio/artwork quality verdict, public-page verification, recipient acknowledgement, legal or royalty advice.

Install

Requires Python 3.11 or later.

uv tool install .

For local development:

uv venv
uv pip install --python .venv/bin/python -e '.[dev]'

Use

Start from the fictional example and replace every field with current, checked information for the actual catalogue you want to reference.

cp examples/catalogue-example.toml my-catalogue.toml
cataloguebook check my-catalogue.toml
cataloguebook check my-catalogue.toml --json
cataloguebook build my-catalogue.toml --output ./catalogue-reference

check does not write anywhere. build creates a new output directory atomically and refuses to overwrite an existing one.

Contract format

[label]
name = "Label name"
catalogue_prefix = "EX"
requirements_basis = "Internal reference - recheck each destination manually."

[[releases]]
catalogue_number = "EX001"
artist = "Artist name"
title = "Release title"
release_date = "2026-10-10"
status = "planned" # planned, announced, released, archived
formats = ["digital"] # digital, vinyl, cassette, cd, other
notes = "Optional declaration"

[[releases.links]]
label = "Declared release page"
url = "https://example.com/release"
checked_on = "2026-08-13"

The local catalogue_prefix uses uppercase letters/digits with optional internal hyphens. Every catalogue number must begin with it and then include a suffix. This validates a naming rule only; it never guesses a number, order, release date, destination, format, or state.

Links are not required because planned/archived records may not have a public destination. When you add a link, checked_on records the date you personally reviewed it; Cataloguebook does not fetch it or verify that it remains current.

Output

catalogue-reference/
├── CATALOGUE.md
├── catalogue.csv
├── link_register.csv
└── manifest.json

The output contains only declared fields and no absolute source path, platform response, page content, authentication state, payment/rights data, or proof of publication.

Development

uv run pytest
uv build

All examples and tests use fictional data and example.org links only.

Licence

MIT

---

---

Part of the Gabriel Tools + Code catalog — browse all tools, products, repositories, and services.

Free and open source: theme-contrast (WCAG contrast checking for colour themes) · htmlshot (HTML → exact-size PNG/PDF) · 50 dark themes for Claude Code.

Hologram People soundware and Gabriel audio/product work are linked from the master catalog above.

Mixing and mastering enquiries — public preview.