Diagnostics & CLI
quickthumb can check a design for common layout and legibility problems without rendering a file: from Python with canvas.diagnose(), or from the terminal with quickthumb lint.
To check a design in Python, start with the example below. For a JSON file,
install the CLI and run quickthumb lint. Use
quickthumb doctor to check export dependencies, or
quickthumb render to write an output. The detailed
finding rules and other CLI commands are below.
canvas.diagnose()
Returns a DiagnosticReport whose findings list contains Diagnostic entries. An empty list means the checks found no issues; it does not guarantee visual quality or catch every problem. Review the rendered result as well.
from quickthumb import Canvas
with open("spec.json", encoding="utf-8") as f:
canvas = Canvas.from_json(f.read())
for finding in canvas.diagnose().findings:
print(finding.severity, finding.code, finding.message)
Each Diagnostic has stable human-readable fields and optional structured fields for automation:
| Field | Type | Description |
|---|---|---|
code |
str |
One of "off-canvas", "tiny-text", "text-overflow", "text-clipped", "missing-glyph", "low-contrast", "layer-overlap", "layer-hidden", "edge-crowding", "near-alignment", "caption-safe-area", "caption-timing", "caption-overlap", "caption-reading-time", "clip-stretch", or "motion-path-unused-handle" |
severity |
str |
"warning" or "error" |
layer_index |
int |
Index of the offending layer in canvas.layers |
message |
str |
Human-readable explanation with the measured values |
layer_id |
str \| None |
Stable measured layer id, such as "layer:3" or "layer:3:0" for group children |
layer_name |
str \| None |
Layer name when the layer model exposes one |
bbox |
dict \| None |
Measured canvas-space bounding box with x, y, width, and height |
related_layers |
list[str] |
Layer ids involved in the finding |
measured |
dict |
Raw rule-specific values, such as contrast ratio, font size, or canvas dimensions |
suggestion |
str \| None |
Repair hint when the rule can provide one |
What gets checked
| Code | Trigger |
|---|---|
off-canvas |
A layer's bounding box falls partly or fully outside the canvas |
motion-path-unused-handle |
An incoming handle on the first position keyframe or outgoing handle on the last has no adjacent segment |
tiny-text |
Text smaller than 2.5% of the canvas height, likely unreadable at thumbnail size |
text-overflow |
A single word is wider than the layer's max_width and cannot be wrapped |
text-clipped |
Wrapped text extends past the canvas or its declared text box |
missing-glyph |
The selected font renders one or more characters as a missing-glyph placeholder |
low-contrast |
Text color has a contrast ratio under 2.0 against the composited layers below it |
layer-overlap |
Two visible layers overlap substantially enough to obscure one another |
layer-hidden |
A visible layer is fully covered by later opaque layers |
edge-crowding |
A visible layer is too close to a canvas safe margin or platform overlay |
near-alignment |
Related, unrotated layers have measured x/y starts within three pixels but are not exactly aligned |
caption-safe-area |
A video caption sits inside the canvas safe-area margin |
caption-timing |
A video caption ends after its clip does, so it is never seen |
caption-overlap |
Two video captions share both a moment and a rendered background |
caption-reading-time |
A cue is on screen under 0.8s, or runs past 20 display columns a second, leaving too little time to read it. Wide scripts such as Korean and Japanese count two columns per character while joiners and combining marks count none, and a cue that outlives its clip is measured over the part of it that is actually seen |
clip-stretch |
A clip plays slower than 0.5x or faster than 2x of its own rate. Usually it is being stretched to fit a scene, but a deliberate slow-motion or timelapse beat is reported the same way |
With an LLM
Send the findings back to the model as specific edits to make, rather than asking for a new design. See AI Workflow.
Near-alignment checks compare rendered layer positions to spot unintended 1–3 pixel misalignments.
Contrast and Alignment Checks
- Contrast checks sample text against the composited background beneath it, including any
Backgroundpill effects attached to the text layer. - Near-alignment flags layers that are almost aligned (within 3px) so you can snap them cleanly without guessing coordinates.
The quickthumb CLI
The CLI requires the cli extra:
quickthumb inspect
Inspect a Canvas or Deck JSON spec without writing an export:
quickthumb inspect spec.json
quickthumb inspect deck.json --format json
quickthumb inspect deck.json --target video --fps 24 --max-samples 100
quickthumb inspect spec.json --reduced-motion --var title="Hello"
Text output includes ordered page/layer bounds, per-layer motion durations and event counts,
capability/fallback rows, observed assets, and layout diagnostics.
--format json emits exactly the Python
inspect_document() result envelope, including version
and document kind. It has the same page ordering and common fields for both
document kinds, so scripts can consume it without guessing the input type.
--target selects a capability family (raster, html, pptx, or video);
omitting it reports all four. --fps and --max-samples control bounded motion
property observations, not image-frame generation. --reduced-motion inspects
the accessible static policy. --var KEY=VALUE follows the other spec commands.
Inspection can resolve fonts/assets or decode media for measurement. It reports
observed asset states and does not perform a separate prefetch or readiness
check. Motion-inspection duration is not an encoded-video duration; use the
Python sample() timeline for canonical frame and playback timing.
Findings are informational: successful inspection exits 0 even with warnings.
Input, validation, and missing-asset errors exit 1; rendering/export-category
errors (including an empty Deck's motion inspection) exit 2. With JSON output,
these errors use the existing {"errors": [...]} structured envelope. Use
lint --fail-on to gate on diagnostics and doctor to check environment readiness.
Argument-parsing errors, such as --fps abc, still use Typer's standard text
on stderr and exit 2; the JSON error envelope applies after argument parsing.
quickthumb lint
Checks a JSON spec for the same findings as diagnose():
quickthumb lint spec.json
quickthumb lint spec.json --format json
quickthumb diagnose spec.json --format json
[warning] layer 3: tiny-text: text size 14px is below 18px (2.5% of canvas height) ...
[warning] layer 4: low-contrast: text contrast ratio 1.47 against the layers below it ...
With --format json, lint prints a machine-readable payload:
{
"summary": {
"diagnostic_count": 1,
"error_count": 0,
"warning_count": 1
},
"diagnostics": [
{
"code": "tiny-text",
"severity": "warning",
"layer_index": 3,
"message": "text size 14px is below 18px ...",
"layer_id": "layer:3",
"bbox": {"x": 80, "y": 64, "width": 120, "height": 17},
"related_layers": ["layer:3"],
"measured": {"font_size": 14, "threshold": 18.0},
"suggestion": "increase text size to at least 18px"
}
]
}
lint exits with a status that CI can act on:
| Exit code | Meaning |
|---|---|
0 |
No issues found |
1 |
Invalid spec (bad JSON, validation error, missing asset, invalid option) |
2 |
Rendering failure |
3 |
Findings reported |
diagnose is an alias for lint. Both commands accept the same automation options:
quickthumb lint spec.json --fail-on error
quickthumb lint spec.json --ignore edge-crowding --ignore missing-glyph
--fail-on warning (the default) exits 3 for any remaining finding. --fail-on error
allows warnings while still failing on errors, and --fail-on never always exits 0 after
printing the findings. --ignore removes matching diagnostic codes from both the output and
the exit-status calculation. Invalid specs with --format json emit an errors list of
structured error details rather than a traceback.
JSON inputs must declare a top-level kind discriminator (canvas or deck). Deck findings
include slide_index and retain
the originating layer id, bounding box, measurements, related layers, and suggestion.
quickthumb diff
Compare a rendered image with a golden image before accepting a visual change:
quickthumb diff golden.png output.png
quickthumb diff golden.png output.png --format json --output diff.png
The comparison combines an average perceptual hash with pixel-level metrics.
By default, per-channel differences of up to 2 are ignored, but any pixel that
exceeds that tolerance fails the comparison. The default perceptual-hash
similarity threshold is 0.95. Tighten or relax those values for a particular
renderer:
quickthumb diff golden.png output.png \
--threshold 0.98 \
--pixel-tolerance 1 \
--max-diff-ratio 0.005
Use --format json for CI or agent pipelines. --max-diff-ratio can allow a
small fraction of pixels to differ, and --output writes a pixel-difference
image for visual inspection. Exit codes are:
| Exit code | Meaning |
|---|---|
0 |
Images match within the configured tolerances |
1 |
Images differ, inputs are invalid, or output cannot be written |
The same comparison is available as a Python assertion:
from quickthumb import assert_image_similar
assert_image_similar(
"golden.png",
"output.png",
threshold=0.95,
)
The assertion returns an ImageDiff with image sizes, changed-pixel counts,
normalized mean error, perceptual hashes, and similarity metrics when callers
need to report more detail.
quickthumb render
Renders a JSON spec to an image file:
quickthumb render spec.json -o thumbnail.png
quickthumb render spec.json -o thumbnail.webp --format WEBP --quality 90
quickthumb render spec.json -o debug.png --debug
| Option | Description |
|---|---|
-o, --output |
Output file path (default output.png) |
--format |
PNG, JPEG, or WEBP |
--quality |
Compression quality: JPEG 1–95, WebP 1–100; not a rendering-quality control |
--debug |
Overlay public layer-id bounding boxes on raster output |
--var KEY=VALUE |
Substitute $KEY placeholders in the spec (repeatable) |
--error-format |
text (default) or json; see Structured Errors |
render exits 1 for invalid specs, missing assets, and invalid options, and 2 for
export failures such as an unsupported output format.
quickthumb watch
Re-renders the spec every time the file changes, which is handy while adjusting a layout by hand:
watch takes the same options as render except --error-format; failures are printed as
text and watching continues.
quickthumb doctor
Discovers packages, tools, source requirements and output permissions before an export:
The workflow is one of png, jpeg, webp, gif, svg, html, pdf, pptx, mp4,
webm, or mov. With --spec, the spec's plugin renderers, fonts, SVG/video layers, background removal,
and remote assets add their own requirements. -o checks that the output location is writable
(nothing is created).
Each finding is ok, warning (an optional limitation, such as a missing font or an
unusable asset cache), or error (a required failure, such as a missing quickthumb[pdf] extra,
ffmpeg, an unregistered plugin, or an unwritable output). Every warning and error includes a
fix/remedy. Plugins are checked against the registry of the CLI process, which only has plugins registered
at import time, so a spec that uses code-registered plugins will report them as unregistered.
Exit code is 0 when no required check failed and 1 otherwise.
A successful report is not an export or fidelity certificate. Package discovery
does not prove that native Cairo can load, and finding FFmpeg does not prove
that its build has the encoder your output needs. doctor does not render or
compare output. Run the intended export and inspect its receipt and file; use
an explicit fidelity policy or quickthumb diff when visual comparison matters.
quickthumb serve
Runs a local HTML slideshow server with live reload. With no source argument it
looks for slides.py, slides.json, slides.html, or slides.htm in that
order:
quickthumb serve
quickthumb serve examples/investor_deck.py
quickthumb serve deck.json --port 4040 --no-open
A Python source should define one module-level Deck or Canvas as deck,
slides, or canvas. A JSON source must declare kind: "canvas" or kind: "deck";
Canvas documents contain layers, while Deck documents contain a top-level slides list.
Use --host and --port to change the listening
address, --no-open to suppress the initial browser window, and repeat
--var KEY=VALUE for JSON template substitutions.
The audience view is /. Presenter mode is selected by the ?presenter query:
Presenter mode uses the same light theme as the preview: current slide and notes
on the left, next slide and pause/resume/reset timer on the right, and simple
navigation below. Slide previews retain their original proportions. Its navigation and per-slide animation progress
are broadcast to audience tabs opened from the same server and restored on
reload. Audience-only navigation remains local. Add notes in Python with
.slide(canvas, notes="...") or as a notes string on a JSON slide.
Timeline scrubber
Open the raster timeline while authoring Python or JSON documents:
quickthumb serve examples/timeline_preview.py --timeline
quickthumb serve deck.json --timeline --no-open
The timeline is also available at http://localhost:3030/timeline alongside
an ordinary serve session. The default remains the HTML presentation, including
slide navigation, click-triggered animations and synchronized presenter controls.
Presentation and Inspect motion share the same slide selection and thumbnail
navigation. Presentation keeps the slide central at its original aspect ratio;
Inspect motion opens a frame-scrubbing panel below it. Presenter opens the
synchronized speaker view, while Present opens the HTML slide fullscreen.
Motion notes explain when HTML output is static or approximated. These controls
are local authoring tools and are not added to exported HTML.
Standalone HTML has no source document to sample; use its Python or JSON source
for the timeline instead.
Inspection shows export-renderer frames without playback, audio or editing. Its seek position is independent of presenter/audience synchronization.
- Drag the time slider, enter seconds, or click a slide/transition/motion boundary
- Proxy limits the output's longest edge to 640 pixels (1080×1920 becomes 360×640), preparing reusable layer imagery and compositing ordinary motion on reduced surfaces. Later mixed-size slides fit that same output rectangle
- Full shows native first-slide dimensions, using the same standard-quality
canonical timeline sampler as
Canvas.sample(time=...)/Deck.sample(time=...) - Source saves reload the timeline, preserving the selected resolution and time in the URL fragment and clamping the time if the new timeline is shorter
- Only one browser frame request runs at a time; rapid seeks replace pending work with the latest choice. The displayed-frame label continues to identify the old frame until the requested frame is ready. Broken edits show an error and recover after the next save
The timeline scrubber renders instantaneous frame previews matching your export timing:
- Proxy mode: Renders downscaled frames (up to 640px) for smooth, rapid seeking.
- Full mode: Renders full-resolution frames matching standard export quality.
- Note that audio playback is disabled during timeline scrubbing.
Local Security
quickthumb serve runs local Python and JSON files on your machine. Keep the default loopback address (127.0.0.1) when previewing untrusted content.
Variable substitution
The JSON-based commands accept --var to fill $KEY (or ${KEY}) placeholders before parsing:
Unresolved placeholders cause exit code 1. $theme.* references are not variables; they are resolved by the theme block inside the spec itself.