Skip to content
quickthumb
All documentation

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.

deck = Deck.from_aspect_ratio("16:9", 1280)   # default 1280×720

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().

result = deck.export("slides.png")
print(result.written_paths)

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.

html = deck.to_html()
deck.render("slides.html")

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:

for finding in deck.diagnose().findings:
    print(finding.slide_index, finding.code, finding.message)
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.

spec = deck.to_json()
restored = Deck.from_json(spec)

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.