API Reference
Use Canvas to author a scene and Deck to sequence scenes. Both implement the
same document operations; individual layer pages describe their authoring fields.
Supported public surface
Import documented authoring types and result models from quickthumb, and audio
analysis from the documented quickthumb.audio module. A name
being importable from another module does not make it a supported entry point.
| Surface | Supported use |
|---|---|
| Authoring | Canvas, Deck, documented layer/effect models, motion tracks, transitions and option models |
| Document operations | validate(), inspect(), diagnose(), prefetch_assets(), sample() and export() on either document kind; inspect_document() for generic consumers |
| Results | Typed reports, ExportResult, CanonicalFrame / FrameSequence, and ImageSequence* results; serialize them with model_dump_json() |
| JSON | to_json(), Canvas.from_json(), Deck.from_json(), canvas_json_schema() and document_json_schema() |
| Audio authoring | quickthumb.audio.analyze_audio() and AudioAnalysis; bake source-clock onset times and RMS-driven scale into numeric motion |
| Specialist output | Documented render(), render_frame(), to_*() and export_image_sequence() methods when their return type or controls fit the task |
export() is the recommended file boundary: it preflights capability policy and
returns written paths and diagnostics. Specialist methods have their own return
values and do not all enforce that policy; see output API.
Keep format-specific options at that boundary rather than calling exporters directly.
Modules beginning with _, renderer/context objects, and timeline compilation
helpers are implementation details. They can change or disappear without a
supported lifecycle. Use sample() to consume frames instead of coordinating a
compiler and renderer. The reference pages and generated schema describe the
installed version's supported fields; public does not mean frozen across versions.
One document workflow
This uses the same layer data in Python, canonical JSON and a Deck, with no renderer objects or optional dependencies:
from quickthumb import Canvas, Deck, Document, ExportResult
canvas = Canvas(320, 180).background(color="#102030").shape(
"rectangle", position=(24, 24), width=80, height=40, color="#42CEB7",
id="badge", motion_key="brand", anchor=(0, 0),
)
restored = Canvas.from_json(canvas.to_json())
document: Document = Deck(slides=[restored])
result: ExportResult = document.export("slides.png")
print(result.written_paths) # Numbered paths are reported by the result.
print(document.sample().frames[0].sha256)
Shared layer vocabulary
Canvas layers use the same fields when carried by a Deck slide or canonical
JSON. A Deck adds slide order, transitions, narration and notes; it does not
rename layer fields. Python tuples become JSON arrays, enum values become
strings, and each layer has a type discriminator.
| Field or concept | Meaning |
|---|---|
id |
Optional identifier unique within a Canvas scene, including group descendants. Each Deck slide has its own identity scope. |
motion_key |
Optional matching key across scenes for Morph transitions; distinct from a scene-local id. |
position, width, height |
Authored placement and size, in pixels or percentage strings where the layer accepts them. Percentages resolve against the canvas; consult the layer reference for required fields and sizing rules. |
align |
The point of a layer's layout box placed at position; also controls text alignment. See Align. |
rotation, anchor |
Rotation is in degrees. anchor=(x, y) is a normalized 0–1 pivot for canonical motion, distinct from layout alignment. Static rotation has its own framing; see transform anchors. |
opacity |
Layer opacity from 0 to 1 where supported. |
animation |
A preset or AnimationSpec containing typed tracks and timing. Position tracks are offsets from authored placement; scale tracks transform the outer object, while ImageZoomTrack changes image content inside its frame. |
| Group | Auto-layout owns child placement. Use .group() for rows/columns rather than positioning each child. |
parent / null |
Advanced, scene-local transform hierarchy for top-level animatable layers. Child placement is parent-local; percentage coordinates still resolve against the canvas. This is separate from group layout. See parent transforms. |
Not every layer accepts every field: backgrounds, outlines, nulls and drawable
layers have different roles. Their reference pages and the JSON schema
are the field-level contract. Plugin registrations
declare parameters and can supply rendering callbacks through an explicit
PluginRegistry; parsing JSON does not package or install those callbacks.
Pages
| Page | What it covers |
|---|---|
| Canvas | Creating a canvas, every layer method, checks, and export methods |
| Deck | Several canvases as one PDF, PPTX, HTML slideshow, video, or image sequence |
| Document inspection | inspect_document() and generic Canvas/Deck sampling consumers |
| Background | .background(): colors, gradients, and images |
| Text | .text() and TextPart: text and rich text |
| Image | .image(): placed images and cut-outs |
| Shape | .shape(): rectangles, ellipses, pills, triangles, stars, polygons |
| Path | .path(): filled/stroked SVG path data and bounded motion |
| SVG | .svg(): icons and logos from SVG files |
| Video | .video(): video clips, captions, and audio |
| Group | .group(): auto-layout rows and columns |
| Outline | .outline(): a border around the canvas |
| Data visualizations | .chart() and .qr_code() |
| Effects | Stroke, Shadow, Glow, Filter, Background, Grain, Duotone, InnerShadow, BackdropBlur |
| Enums & Gradients | Align, BlendMode, FitMode, LinearGradient, RadialGradient, TextFillImage |
Error types
| Exception | When raised |
|---|---|
ValidationError |
Invalid arguments passed to a layer builder (raised immediately) |
RenderingError |
Failure during .render(), .to_base64(), or .to_data_url() |