Deck
A Deck is an ordered collection of Canvas slides. Each slide renders exactly as it would on its own; the deck adds multi-output export on top of the same pipeline.
Slides retain the Canvas layer vocabulary and scene-local identities.
Creation
Deck(width=None, height=None, slides=None, theme=None)
from quickthumb import Canvas, Deck
deck = Deck() # empty, no default size
deck = Deck(1280, 720) # default slide size for unsized slides
deck = Deck(slides=[cover, body]) # from pre-built canvases
| Parameter | Type | Description |
|---|---|---|
width |
int \| None |
Default slide width. Provide with height or omit both. |
height |
int \| None |
Default slide height. |
slides |
list[Canvas] \| None |
Initial slides, in order. Each must be a Canvas. |
theme |
dict \| None |
Token groups shared with every slide's $theme.* references (slide-level themes win). Preserved across to_json()/from_json(). |
Deck.from_aspect_ratio(ratio, base_width)
Creates a deck whose default slide size comes from an aspect ratio string, mirroring Canvas.from_aspect_ratio.
Adding slides
Pass initial slides to the constructor (Deck(slides=[...])) and/or append them one at a time with .slide(canvas, transition=None, *, audio=None, duration=None, notes=None), which mutates the deck and returns self for chaining. When the deck has a default size, an unsized Canvas() inherits it; a canvas built with an explicit size keeps its own (and triggers a mixed-slide-size warning when it differs).
| Method | Description |
|---|---|
.slide(canvas, transition=None, *, audio=None, duration=None, notes=None) |
Append one Canvas; optional audio/duration configure narration, and notes appear only in HTML presenter mode |
deck = (
Deck(1280, 720)
.slide(
Canvas().background(color="#101820").text(content="Cover", size=96, color="#FFFFFF"),
audio="voice.wav",
duration=2.5,
notes="Introduce the central thesis.",
)
.slide(Canvas().background(color="#1A1A2E").text(content="Body", size=64, color="#FFFFFF"))
)
Adding an unsized canvas to a deck with no default size raises ValidationError: give the deck a size or size the canvas.
A deck is also a sequence: len(deck), deck[i], and iteration over slides all work. deck.slides and deck.notes return copies of the aligned slide and speaker-note lists, so mutating either returned list does not change the deck.
Export methods
.export(path, policy=None, *, format=None, quality=None, animation=None)
Writes the deck like render() and returns an ExportResult whose
written_paths lists numbered slide files for raster output, or one PDF, PPTX,
HTML, or animation file. The path may be a string or pathlib.Path; format,
quality, animation, and policy mean the same as in render().
See Recommended output API
for the result fields, the capability preflight, and how export() relates to
the methods below.
.render(path, format=None, quality=None, animation=None, policy=None)
Renders the deck, dispatching on the output extension. Returns the list of written file paths.
from quickthumb import GifOptions, VideoOptions
deck.render("deck.pdf") # one multi-page PDF (a page per slide)
deck.render("deck.pptx") # one multi-slide PPTX (a slide per slide)
deck.render("deck.gif") # one animation playing transitions between slides
deck.render(
"preview.gif",
animation=GifOptions(fps=8, max_size=(540, 960), colors=128),
)
deck.render("deck.html") # one self-contained HTML slideshow
deck.render("slides.png") # slides_01.png, slides_02.png, …
deck.render("slides.jpg", quality=85)
| Extension | Behavior |
|---|---|
.pdf |
Single multi-page PDF. Requires the pdf extra. |
.pptx |
Single multi-slide PPTX. Requires the pptx extra. |
.gif / .webm / .mov |
Single animation playing layer animations and slide transitions with default settings. WebM and MOV require ffmpeg (MOV uses prores_ks). |
.mp4 |
Animated timeline with optional per-slide narration; H.264/yuv420p video and AAC audio. Requires ffmpeg (and ffprobe for narration). For still slides, use static canvases and Cut() transitions. |
.html / .htm |
Single self-contained, animated HTML slideshow. |
.png / .jpg / .jpeg / .webp |
One file per slide as a zero-padded numbered sequence. |
| Parameter | Type | Default | Description |
|---|---|---|---|
path |
str |
— | Output path; raster names become <stem>_NN<ext> |
format |
str \| None |
None |
Case-insensitive raster encoding override ("PNG", "JPEG", "WEBP"); rejected with document/animated extensions. |
quality |
int \| None |
None |
Compression quality: JPEG 1–95, WebP 1–100; other targets reject it. |
animation |
GifOptions \| VideoOptions \| None |
None |
Format-specific options: GifOptions for GIF, VideoOptions for MP4/WebM/MOV. |
policy |
ExportPolicy \| None |
None |
Renderer policy, such as reduced_motion for animated, HTML, and PPTX output. Both render() and export() enforce unsupported_motion before writing. |
Warning
Passing quality with .pdf, .pptx, or animated output raises RenderingError, as does rendering an empty deck.
GifOptions and VideoOptions are available from quickthumb. GifOptions
controls GIF frame rate, hold, loop count, matte, proportional max_size, and palette
colors; VideoOptions controls MP4/WebM/MOV frame rate, hold, matte, soundtrack, and
audio looping. Supply its soundtrack as AudioTrack(path="music.mp3", loop=True).
VideoOptions(transparent=True) preserves alpha in VP9 WebM or ProRes 4444 MOV (strict
boolean, default False); all other output targets reject this option.
Both use a strict finite nonnegative hold (default 3 seconds), omitted from
serialized options when equal to its default. Both accept workers (a strict
integer from 1 to 8, default 1) and render_quality="standard" or "high" for rendering. See parallel animated rendering
for spawn setup and supported inputs. Format-specific options are rejected when used with the other animated format.
.to_html()
Returns a self-contained slideshow document. The normal audience view supports
click, Space, and arrow-key navigation. Opening the document from
quickthumb serve with the ?presenter query adds the current/next dashboard,
speaker notes, a pause/resume/reset timer, and synchronized audience controls.
Use quickthumb serve slides.py during development; Python sources expose the
deck as a module-level deck, slides, or canvas variable.
.to_pdf() / .to_pptx()
Return the deck as document bytes, one page/slide per canvas.
with open("deck.pdf", "wb") as f:
f.write(deck.to_pdf()) # requires quickthumb[pdf]
pptx_bytes = deck.to_pptx() # requires quickthumb[pptx]
.to_gif(...) / .to_webm(...) / .to_mov(...)
Return the deck as an animation: each slide plays its layer animations, holds its settled state, and its transition animates the change into it (see Animated GIF & video for the timing model). .to_webm()/.to_mov() require the ffmpeg binary on PATH (or named by QUICKTHUMB_FFMPEG).
gif_bytes = deck.to_gif(fps=20, hold=3.0, loop=0, matte="#000000")
webm_bytes = deck.to_webm(fps=30, hold=3.0)
overlay_bytes = deck.to_webm(fps=30, hold=3.0, transparent=True)
All animated byte methods accept keyword-only workers=1 and
render_quality="standard" ("high" enables supersampling). .to_gif() also accepts
max_size=None for proportional resizing and colors=None for the palette
size (2–256 when supplied). Existing positional parameters remain unchanged.
These controls also apply to .to_mp4(). Use static canvases and Cut() for still
narrated slides. File options and byte methods both use hold. Animated video
requires a positive default hold whenever a slide has neither narration nor an explicit duration;
zero is still valid for Deck GIF and silent image sequences. Deck GIF ignores
per-slide narration and explicit durations.
The keyword-only transparent flag on .to_webm() and .to_mov() skips only the export matte;
authored backgrounds stay visible. See transparent WebM
for codec, alpha decoding and transition details.
.to_mov() uses the same parameters and timing as .to_webm(), with fixed
ProRes 4444 video and AAC audio. It retains odd and one-pixel dimensions.
The RGBA source remains 8-bit; 16-bit alpha coding can decode with one-level
8-bit alpha differences, and color is lossy 4:4:4 YUV. See
ProRes MOV for the measured conversion limits
and encoder requirements. render() and export() accept .mov with
VideoOptions for both opaque and transparent output.
.export_image_sequence(output_directory, *, format="png", quality=None, matte=None, lossless=None, options=None, policy=None)
Write the animated timeline as independent PNG (default), JPEG or WebP files
plus manifest.json into a new directory under an existing parent.
ImageSequenceOptions(fps=30, hold=3, workers=1, render_quality="standard")
controls timing/compositing; method keywords select image encoding. JPEG
uses RGB on an opaque matte (white by default), with quality=1..95.
WebP preserves alpha and accepts lossless=True; lossy WebP accepts quality.
PNG and lossless WebP preserve the renderer's exact RGBA8 pixels. Opaque WebP
files may decode as RGB; manifest mode describes logical RGBA decoding.
The receipt reports actual frame count, timing, encoding and destination.
See image sequences for validation, per-format
metadata and atomic no-overwrite publication.
.to_mp4(...)
Return the same animated timeline as .to_webm() in an H.264 MP4 container,
including scheduled per-slide narration and an optional mixed soundtrack.
Animated MP4/WebM/MOV export supports at most 64 narrated slides per Deck; silent
slides do not count toward that operational FFmpeg input limit.
For a file export, use deck.export("deck.mp4",
animation=VideoOptions(soundtrack=AudioTrack(path="music.mp3", loop=True))).
It mixes the background track with each slide's audio narration during rendering.
Without explicit options, deck.export("deck.mp4") uses the same animated
timeline with default VideoOptions().
.diagnose()
Aggregates each slide's Canvas.diagnose() findings and adds deck-wide checks. Returns a DiagnosticReport whose findings list contains DeckDiagnostic entries:
| Field | Type | Description |
|---|---|---|
code |
str |
Slide codes (off-canvas, tiny-text, …) or mixed-slide-size |
severity |
str |
"warning" or "error" |
message |
str |
Human-readable description |
slide_index |
int \| None |
Originating slide, or None for deck-wide findings |
layer_index |
int \| None |
Originating layer within the slide, when applicable |
layer_id |
str \| None |
Stable originating layer id, including group-child ids |
layer_name |
str \| None |
Originating layer name when present |
bbox |
dict \| None |
Measured canvas-space bounding box |
related_layers |
list[str] |
Layer ids involved in the finding |
measured |
dict |
Rule-specific measured values |
suggestion |
str \| None |
Repair hint when available |
A mixed-slide-size warning is added when slides do not all share the same dimensions. The PDF path sizes each page to its slide, but PPTX export uses the first slide's size for the whole deck, so larger later slides are clipped by PowerPoint. Keep slides the same size when targeting .pptx.
.prefetch_assets() (optional)
Downloads every slide's remote assets up front and returns one deck-level
asset_manifest, like Canvas.prefetch_assets().
Rendering and exporting fetch assets themselves, so call it only to surface
network failures or stale cache entries before a long export.
JSON
.to_json() / Deck.from_json(json_str)
Round-trips the deck through canonical JSON, reusing each canvas's serialization. The shape is {"kind": "deck", "width": ..., "height": ..., "theme": {...}, "slides": [<canvas spec>, ...]}, where every slide carries "kind": "canvas"; width/height (the default slide size) and theme are emitted only when set. JSON-authored slides may omit dimensions when the deck supplies a default size; canonical serialization materializes those inherited dimensions. Per-slide transition, audio, duration, and notes fields are preserved alongside the canvas fields. A top-level theme is shared with every slide so slides can use $theme.* tokens, exactly like Canvas.from_json.
Note
As with Canvas.to_json(), decks containing .custom(fn) slides cannot be serialized unless those callbacks are registered. from_json() expects a JSON string, not a dict.