The two-host YouTube pipeline I described last week turns a JSON spec into an MP4 by rendering still images for each dialogue segment, running TTS, and using ffmpeg to concat the clips. The part that deserved more than a paragraph was the still-image renderer. Every frame is produced by slides.py, a 480-line Python module using Pillow. No browser, no Puppeteer, no headless Chromium, no screenshot API.

Here's how it works, what decisions I made along the way, and what I'd change.

Why render slides in Python at all

Three constraints made a purpose-built renderer the right call:

CI-only execution. Every video renders inside a GitHub Actions job triggered by a commit. Tools requiring a GUI, a running browser, or a persistent daemon don't fit. The single CI pipeline has to produce a deterministic PNG from data without any human in the loop.

Brand consistency at scale. The pipeline is automated — once a script goes in, the video comes out. Every frame needs the same background colour, font, header and footer chrome, and layout margins. Presentation tools drift when you're generating output programmatically rather than authoring by hand.

Zero ongoing cost. I'm running three directory sites for about $25/month. Every SaaS slide or video tool has a seat fee; Pillow doesn't.

The output: 1920×1080 PNG frames, deterministic from a JSON spec, rendering in under a second per frame on a standard GitHub Actions Ubuntu runner. The module uses Pillow (PIL Fork) throughout — specifically ImageDraw for vector primitives and ImageFont.truetype() for text.

The dispatch table design

The renderer supports eight slide kinds. Each maps to a Python function that takes a spec dict and returns a PIL.Image:

_RENDERERS = {
    "title":   slide_title,
    "bullets": slide_bullets,
    "table":   slide_table,
    "tool":    slide_tool,
    "outro":   slide_outro,
    "diagram": slide_diagram,
    "chart":   slide_chart,
    "image":   slide_image,
}

def render_one(spec: dict) -> Image.Image:
    fn = _RENDERERS.get(spec.get("kind", "bullets"))
    if fn is None:
        raise ValueError(f"unknown slide kind: {spec.get('kind')}")
    return fn(spec)

render_one() is the single entry point used by build_longform.py. Adding a new kind means one function and one dict entry — no conditionals to update, no subclasses. I tried a class hierarchy first (subclasses of a Slide base), but the render functions don't share mutable state. They take a dict and return an image. A dispatch table is the right level of abstraction.

Brand chrome: the shared foundation

Every slide starts by calling _chrome(img, draw, page=""), which draws four things before the content renderer touches the canvas:

• A 10px accent-blue bar across the top edge
• The brand logo mark (lazy-loaded PNG) and wordmark in the top-left
• A hairline at H - 78
• Site URLs in the footer and an optional page indicator at bottom-right

def _chrome(img, draw, page=""):
    draw.rectangle([0, 0, W, 10], fill=ACCENT)
    x = MARGIN
    logo = _brand_logo()
    if logo is not None:
        lg = logo.copy()
        lg.thumbnail((58, 58))
        img.paste(lg, (x, 36), lg)
        x += lg.width + 16
    draw.text((x, 42), BRAND, font=font(40, "bold"), fill=INK)
    # hairline + footer text below

The logo load is guarded by a module-level _LOGO_LOADED flag so the file check runs once per process. If the logo doesn't exist, chrome renders without it. This matters in CI where brand assets might not be present yet — the pipeline degrades to wordmark-only rather than crashing.

Font resolution is the most fragile piece. Pillow's ImageFont.truetype() requires a full path; it doesn't search system font directories. The fix is a candidate list per weight:

_FONT_CANDIDATES = {
    "bold": [
        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
        "/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf",
        "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
        "/Library/Fonts/Arial Bold.ttf",
    ],
    "regular": [...],
}

The Ubuntu runner (GitHub Actions standard image) has DejaVu at the first path. macOS has it at the third. If neither exists, the script exits with a clear error rather than silently using Pillow's built-in bitmap font, which looks terrible at 96px.

The eight slide kinds

title: Full-screen centred headline with optional subtitle in accent green. Text wrap is manual — draw.textlength() measures each candidate line until it fits within W - 2 * MARGIN, then breaks. Pillow has no built-in text wrapping.

bullets: Heading at top, 120px accent underline rule, bullet list below. Each bullet draws a filled 20px circle rather than a Unicode bullet character — glyphs missing from the font would silently disappear.

table: The most complex renderer. The first column gets 30% of the table width; the remaining columns split the rest equally. Header row renders on a dark panel background with accent-coloured column labels. Body rows alternate between two background shades. Values in the second column that start with a digit get highlighted in accent green — useful for GitHub star counts or benchmark numbers. Cell values that overflow their column width get truncated with an ellipsis.

tool: Single-tool highlight card. Name in 84px bold, optional logo pasted top-right via img.paste() with alpha mask, then "chip" badges for stars and license using draw.rounded_rectangle() with coloured outlines. Followed by a free-form editorial take paragraph.

outro: CTA slide. The URL sits inside an accent-coloured pill. This slide stays up during the subscribe callout at the end of every video.

diagram: Delegates to visuals.render_mermaid(), then pastes the output PNG into the branded scaffold via _paste_visual(). The Mermaid definition lives inline in the JSON spec.

chart: Delegates to visuals.render_chart(), which uses matplotlib.use("Agg") — the headless backend that doesn't need a display server.

image: Fetches a CC0 photo from the Openverse API, pastes it in the content area, and renders an attribution caption at the bottom in 24px muted text. The caption always appears even when the license is CC0 and attribution is legally unnecessary — it's a safeguard against Openverse's license data being slightly wrong.

The thumbnail renderer

YouTube thumbnails are separate from video frames: 1280×720, high-contrast, built for click-through on a small tile. render_thumbnail() is a distinct function in the same module:

def render_thumbnail(out_png, lines, sub="", host_png=None, accent_idx=None):
    TW, TH = 1280, 720
    img = Image.new("RGB", (TW, TH), BG)
    d = ImageDraw.Draw(img)
    d.rectangle([0, 0, TW, 12], fill=ACCENT)
    if host_png and os.path.isfile(host_png):
        h = Image.open(host_png).convert("RGBA")
        ratio = (TH + 110) / h.height
        h = h.resize((int(h.width * ratio), int(h.height * ratio)), Image.LANCZOS)
        img.paste(h, (TW - h.width + 30, TH - h.height + 50), h)
    n = max(1, len(lines))
    hsize = 150 if n <= 2 else 104
    ...

The host face is scaled to slightly taller than the frame height and anchored bottom-right, bleeding off the bottom edge — the same composition seen on most high-CTR tech thumbnails. Headline text lives on the left in 1-3 short lines. The accent_idx parameter highlights one line in accent green; when Claude Haiku generates the script, it outputs an integer index rather than repeating the text.

I previously used ffmpeg's overlay filter for thumbnail composition; switching to Pillow for longform thumbnails made exact positioning predictable without writing ffmpeg filter graph syntax.

Unlike OG images for articles — which use Playwright because they need real HTML rendering — thumbnails are simple enough that direct PIL drawing is faster and less brittle.

Headless Mermaid and matplotlib

The diagram and chart kinds delegate to visuals.py, which handles the two harder rendering cases.

Mermaid via mmdc: writes a temp .mmd file, builds a brand-matched theme config JSON, and calls the mmdc binary. Resolution order: node_modules/.bin/mmdc → PATH → npx @mermaid-js/mermaid-cli. In GitHub Actions, mmdc often runs as root, so the Puppeteer --no-sandbox flag is required. That gets passed via a puppeteer config JSON written to temp rather than a command-line arg (mmdc doesn't forward arbitrary CLI flags to Puppeteer directly).

matplotlib bars: matplotlib.use("Agg") lets you render charts without a display server. The chart uses the brand palette: navy background, accent-blue bars, accent-green for the top-highlighted entry. Value labels print inline to the right of each bar rather than using axis ticks, which gives better control over number formatting.

Both renderers write to a tempfile.mkstemp() file. _paste_visual() scales that file to fit the content area — between the heading and the chrome footer — and composites it onto the slide background.

What worked, and what I'd change

What worked: the dispatch table made it easy to add diagram, chart, and image after the first five kinds were stable. Each addition was isolated. No layout regressions across 40+ videos.

Font handling is fragile. The candidate-path list works on every runner I've tested. It would silently break if Ubuntu changed its DejaVu install path. The correct fix is committing the fonts as repo assets and referencing them by path relative to the script. This would eliminate the OS-path dependency entirely.

_paste_visual() mishandles portrait diagrams. Mermaid flowcharts that render tall and narrow get letterboxed with wide empty margins on the sides. The function scales to fit the content area height without considering whether the width constraint is tighter. A smarter version would compute min(box_w / vis.width, box_h / vis.height) rather than using PIL's thumbnail().

No CJK support. The word-wrap logic assumes space-delimited text. Japanese or Chinese titles would require Cairo/Pango or pre-rendering text as SVG. Not a current problem; a real architectural limit.

Whether more elaborate slide transitions (Ken Burns zoom, cross-fades) would improve watch time is something the analytics feedback loop will tell me eventually. Until then, still images keep ffmpeg concat trivially simple.

FAQ

Related: Two-host video pipeline with edge-tts and ffmpeg — Generating OG images with Playwright

Part of an ongoing 6-month experiment running three AI-curated directory sites. The technical claims here are real; this article was AI-assisted.