Skip to content
quickthumb
All documentation

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 Background pill 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:

pip install "quickthumb[cli]"

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:

quickthumb watch spec.json -o preview.png

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:

quickthumb doctor pdf -o out/thumbnail.pdf
quickthumb doctor mp4 --spec spec.json --format json

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:

http://localhost:3030/?presenter

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:

quickthumb render template.json -o ep42.png \
  --var TITLE="EPISODE 42" \
  --var ACCENT="#B8FF00"

Unresolved placeholders cause exit code 1. $theme.* references are not variables; they are resolved by the theme block inside the spec itself.