Skip to content

docs: make the README a product page, with generated screenshots - #51

Merged
smb merged 3 commits into
mainfrom
docs/issue-43-screenshots
Sep 5, 2026
Merged

smb merged 3 commits into
mainfrom
docs/issue-43-screenshots

Conversation

@smb

@smb smb commented Sep 5, 2026

Copy link
Copy Markdown
Collaborator

Closes #43.

Stacked on #47. The base is fix/english-provider-labels, because the
screenshots have to show the English provider labels that #47 introduces.
GitHub will retarget this to main when #47 merges.

What changed

The README leads with the product. What MatteLoop does, what comes out, and
that nothing leaves the machine — all before the first command. The developer
half survives intact further down: running from source, the check commands, the
diagnostic flags, the cache-migration note, and the pointer to
docs/building.md. The licence section is untouched.

rembg is credited in the body, by name and link, with a sentence saying what
is used from it — the catalog, the session classes, the approach, and the
weights. The individual model architecture authors stay in
THIRD_PARTY_NOTICES.md, pointed to rather than repeated.

Three screenshots, generated rather than collected. scripts/screenshots.py
decodes assets/demo/golden-retriever.mp4 with the application's own PyAV path,
segments it with the pinned rembg model, and captures real Qt widgets. The
README documents how to regenerate them, so a layout change cannot leave them
quietly wrong.

The fixture-rotation contract moved to docs/testing-fixtures.md, where the
people who need it are, with nothing lost.

What the script drives for real, and what it seeds

Real: the decoded source frame, the segmentation cutout, every widget, the model
catalog, and the timeline facts derived from the clip.

Seeded: the images reach the window through an immutable state snapshot rather
than by starting the asynchronous preview job; the output directory is a neutral
demo path; and the model dialog is pointed at a throwaway cache root holding one
sparse placeholder, so the picture is identical on every machine instead of
reflecting whoever ran it last. The script's own docstring says the same thing,
so nobody later mistakes it for an end-to-end test.

The script touches no application code — git diff against the README commit
shows nothing under src/ or tests/. It is not imported by the test suite and
does not run during it.

Test plan

  • uv run ruff check ., uv run mypy src, QT_QPA_PLATFORM=offscreen uv run pytest -q and scripts/check_guardrails.py all pass.
  • Running the capture script twice from clean produces byte-identical screenshots.
  • The real user model cache is neither read nor written by the capture.
  • Every link the README makes resolves to a file that exists.

🤖 Generated with Claude Code

smb and others added 3 commits September 5, 2026 09:50
Add a developer-only Qt capture script that decodes the bundled demo frame, runs the pinned segmentation model, and captures real application widgets in three documented states.

Keep the seeded output directory neutral, force English numeric formatting for every capture, and size the model dialog to the full model list and footer controls.

Refresh the committed hero, model manager, and expanded Transform screenshots while retaining the repository copy of the demo clip.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The README explained how to run the repository, not what the program is.
A reader met the supported platforms, the uv commands, the cache
migration rules and the fixture-rotation contract before learning that
MatteLoop turns a local video into a transparent animated WebP. That
order is now reversed: what it does, what comes out, and that nothing
leaves the machine, all before the first command.

Three screenshots carry what prose cannot. The main window shows a
source with its crop rectangle beside the finished cutout on a
transparency checkerboard; the Transform section shows trim, crop and
resize; the model manager shows the catalog with what is cached and what
is left over from an older runtime. They are generated by
scripts/screenshots.py rather than collected by hand, and the README
says how to regenerate them, so a layout change cannot leave them
quietly wrong.

rembg is credited in the body rather than only in the notices. The model
catalog, the session classes and the whole approach to background
removal come from it, and the weights are its release artifacts; a
reader deserves to learn that where they will actually see it. The
individual model architecture authors stay in THIRD_PARTY_NOTICES.md,
pointed to rather than repeated.

The developer half survives intact, further down: running from source,
the three check commands, the diagnostic flags, the cache migration
note, and the pointer to docs/building.md. The licence section is
untouched. The synthetic fixture rotation contract moved to
docs/testing-fixtures.md, where the people who need it are, with nothing
lost.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Drive the existing model-manager cache scan against a temporary cache root while leaving the application dialog API unchanged.

Seed that root with one sparse catalog-sized placeholder for the active BiRefNet General Lite model, and keep the displayed path fixed to a fictional current-product cache location for stable public screenshots. The capture removes the temporary root after rendering.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Base automatically changed from fix/english-provider-labels to main September 5, 2026 09:22
@smb
smb merged commit 81b63ea into main Sep 5, 2026
7 checks passed
@smb
smb deleted the docs/issue-43-screenshots branch September 5, 2026 09:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The README explains how to run the repository, not what MatteLoop is

1 participant