Sleeveproof

Sleeveproof is a local command-line tool for reviewing album-art variants. It turns a folder of designs into dark, labelled PNG contact sheets, a machine-readable manifest, and a Markdown review index.

It is deliberately separate from Coverforge: use Sleeveproof to compare options first, then use Coverforge to preflight and export the approved master for delivery.

What it does

• Finds PNG, JPEG, WebP, and TIFF artwork recursively and natural-sorts it (v2 comes before v10).
• Preserves aspect ratio: each thumbnail is contained and never cropped.
• Bakes EXIF orientation and flattens transparency onto an explicit matte.
• Labels each tile with its number, filename, dimensions, and source size.
• Paginates large batches; the default is 20 variants per page (4 × 5).
• Writes manifest.json and INDEX.md beside the PNG pages.

Sleeveproof never edits, renames, uploads, or deletes source artwork.

Install

Requires Python 3.11 or newer and uv.

For a command available from your shell:

uv tool install --from . sleeveproof

For development from this checkout:

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

Build a review pack

sleeveproof build ./FT010-variants \
  --output ./FT010-proof \
  --title "FATE THROUGH 010" \
  --columns 4 --rows 5

The output is a new directory:

FT010-proof/
├── fate-through-010-contact-sheet-01.png
├── fate-through-010-contact-sheet-02.png  # only when needed
├── INDEX.md
└── manifest.json

INDEX.md is the readable review list. manifest.json records the exact input file, dimensions, byte size, page, and grid position for every rendered variant, plus warnings for unreadable images.

Options

sleeveproof build INPUT_DIR --output OUTPUT_DIR [options]

--title TEXT                 Header and report title (default: input directory name)
--columns N                  Grid columns, 1–12 (default: 4)
--rows N                     Grid rows, 1–12 (default: 5)
--thumb-size PX              Square thumbnail canvas, 96–1200 (default: 360)
--background #RRGGBB         Page background (default: #101116)
--matte #RRGGBB              Alpha matte / thumbnail background (default: #16181f)
--label-colour #RRGGBB       Label text colour (default: #ece7dd)

Safety behaviour

• The output directory must not already exist.
• The output directory cannot be inside the source directory.
• Pages and reports are made in a temporary sibling directory and renamed only after the entire package succeeds.
• If a supported image is unreadable, it is skipped and recorded as a warning. If no usable image remains, the command exits with code 2 and creates no final proof package.

Verify changes

.venv/bin/python -m pytest -q

---

Part of Gabriel Tools + Code — a public catalog of audio products, studio utilities, design systems, software and repositories by Gabriel García Alonso:

Open the full catalog →

Related free tools: theme-contrast · htmlshot · 50 dark themes for Claude Code.