Produce a silent, looping MP4 (default 1920x1080, 30 fps, 60-135 s) suitable for a conference stand, a lobby screen, a reception kiosk, a LinkedIn post, or an embedded slide in a deck.
The output is a rendered animation, not a slideshow export. Every frame is painted in Python, so layout, timing, and easing are fully under your control.
Execution model — do the work, don't hand out instructions
You have Python and a shell. Never tell the user to open an editor or run the script themselves. You:
- Write a single self-contained script at
work/booth_video.py. - Install dependencies if missing:
pip install pillow imageio imageio-ffmpeg numpy(imageio-ffmpegships its own ffmpeg binary — no system install needed). - Render preview PNGs and show them to the user.
- Only after previews look right, run the full render.
- Report the output path.
All paths are relative to the current working directory:
{CWD}/
work/
booth_video.py
preview/scene_1.png ...
output/
booth_loop.mp4
Write intermediate frames to the system temp directory, not the working folder. Rendering thousands of PNGs into a cloud-synced folder (OneDrive, Dropbox, iCloud) will stall the render and thrash the sync client.
Design defaults
Use these unless the user supplies a brand palette. Ask for their colours if the video is customer-facing; don't invent a brand.
| Canvas | 1920x1080, 30 fps |
| Duration | 60-135 s |
| Background | deep navy #0A1628 |
| Accents | #0078D4 primary, #B4009E secondary |
| Cards | #112244, 18 px corner radius, ~86% alpha |
| Type | humanist sans, generous whitespace |
| Motion | 0.5 s fade in, 0.3 s fade out per scene, smooth-step easing |
Dark, low-saturation background with two saturated accents reads well on a bright show floor and survives poor monitor calibration.
Script architecture
One file. A render_frame(t, total) function that returns a Pillow Image for time
t in seconds, and a scene table:
SCENES = [
(0.0, 8.0, scene_hook),
(8.0, 22.0, scene_problem),
(22.0, 40.0, scene_how_it_works),
# ...
(108.0, 120.0, scene_cta),
]
def render_frame(t, total):
img = Image.new("RGBA", (W, H), BG)
draw = ImageDraw.Draw(img)
for start, end, fn in SCENES:
if start <= t < end:
fn(draw, img, t - start, end - start)
return img
Time-relative scene functions (local_t, duration) make it trivial to reorder or
retime scenes later without touching their internals.
Animation helpers — always include these
def ease_in_out(t): return t * t * (3 - 2 * t)
def lerp(a, b, t): return a + (b - a) * t
def clamp(v, lo, hi): return max(lo, min(hi, v))
def fade(t, start, end): return clamp((t - start) / (end - start + 1e-6), 0.0, 1.0)
Combine them: alpha = ease_in_out(fade(local_t, 0, 0.5)) * (1 - fade(local_t, dur - 0.3, dur))
gives a clean in/out envelope for any element.
Cross-platform font loading
Never hardcode a single font path — it will fail on another machine. Probe a candidate list per weight and fall back gracefully:
import os
from PIL import ImageFont
FONT_DIRS = [
"C:/Windows/Fonts", # Windows
"/usr/share/fonts/truetype/dejavu", # Linux
"/usr/share/fonts/truetype/liberation", # Linux
"/System/Library/Fonts/Supplemental", # macOS
"/Library/Fonts", # macOS
]
CANDIDATES = {
"light": ["segoeuil.ttf", "HelveticaNeue.ttc", "DejaVuSans-ExtraLight.ttf", "arial.ttf"],
"regular": ["segoeui.ttf", "Helvetica.ttc", "DejaVuSans.ttf", "LiberationSans-Regular.ttf", "arial.ttf"],
"semibold": ["seguisb.ttf", "DejaVuSans-Bold.ttf", "LiberationSans-Bold.ttf", "arialbd.ttf"],
"bold": ["segoeuib.ttf", "DejaVuSans-Bold.ttf", "LiberationSans-Bold.ttf", "arialbd.ttf"],
"mono": ["consola.ttf", "Menlo.ttc", "DejaVuSansMono.ttf", "cour.ttf"],
}
def get_font(weight, size):
for name in CANDIDATES.get(weight, CANDIDATES["regular"]):
for d in FONT_DIRS:
p = os.path.join(d, name)
if os.path.exists(p):
try:
return ImageFont.truetype(p, size)
except OSError:
continue
return ImageFont.load_default()
Print which font actually resolved on the first call. A silent fall back to
load_default() produces a tiny bitmap font and a video that looks broken —
you want to know before the full render, not after.
Z-order rule — the one that bites
Pillow paints in call order: later calls sit on top. Draw connectors before the things they connect.
For any hub-and-spoke, node-and-edge, or step-and-arrow layout, split into two passes:
# Pass 1 — background layer: every connector
for item in items:
draw.line([hub_xy, item.xy], fill=LINE, width=2)
# Pass 2 — foreground layer: every node
draw_hub(draw, hub_xy)
for item in items:
draw_card(draw, item.xy, item.label)
Interleaving the two passes draws lines across cards and through label text. This is the single most common defect in generated diagrams-in-motion, and it is invisible until you look at a rendered frame — which is why previews are mandatory.
Scene planning
Design for someone walking past at 3 m who gives you eight seconds.
- Hook (0-8 s) — one bold headline, one idea. No body copy. If a passer-by can't get the point from this scene alone, the video has already failed.
- Body scenes (8 s onward) — one concept per scene, 10-18 s each. Card layouts, animated counters, progress bars, typed-text reveals. Never more than ~25 words on screen at once.
- CTA (last 8-12 s) — what to do next, plus a name, booth number, or short URL.
End the CTA so it cuts cleanly back to the hook — the loop point should be invisible. Either fade fully to background colour, or make the first and last frames identical.
Contrast rules
- Dark card on dark background is unreadable on a show floor. For any chat, answer, or quote UI, put the response on a white or near-white card with dark text.
- Never place accent-coloured text on the accent-coloured fill.
- Check contrast on a preview PNG, not in your head. Show-floor lighting and cheap panels both crush shadow detail.
Preview before rendering
Full renders take minutes. Preview takes seconds. Always:
if PREVIEW:
os.makedirs("work/preview", exist_ok=True)
for i, (start, end, _) in enumerate(SCENES, 1):
mid = (start + end) / 2
render_frame(mid, TOTAL).convert("RGB").save(f"work/preview/scene_{i}.png")
raise SystemExit
Display every preview inline to the user with markdown image syntax and get confirmation before the full render. URL-encode any spaces in the path.
Render loop
import imageio, numpy as np
writer = imageio.get_writer(
output_path, fps=FPS, codec="libx264",
output_params=["-crf", "18", "-pix_fmt", "yuv420p"],
)
for idx in range(int(TOTAL * FPS)):
t = idx / FPS
writer.append_data(np.array(render_frame(t, TOTAL).convert("RGB")))
if idx % max(1, int(TOTAL * FPS / 20)) == 0:
print(f"{100 * idx / (TOTAL * FPS):.0f}%", flush=True)
writer.close()
-pix_fmt yuv420p is not optional — without it the file will not play in QuickTime,
PowerPoint, or most hardware media players, even though VLC handles it fine.
Iteration
After the first render, offer to tweak and accept plain-language feedback ("slower orbit", "bigger headline", "green instead of magenta"). Edit the script, re-render the affected scene as a preview PNG first, then re-render the video. Never re-render the full video to check a colour change.
Quality checklist before delivering
- Resolved a real TrueType font, not
load_default() - No text overflowing a card boundary or the canvas
- No label collisions in radial / orbit layouts
- All connectors drawn before all nodes (z-order)
- Readable contrast on every scene's preview PNG
- Loop point is seamless — last frame flows into first
- Encoded with
yuv420p; plays outside VLC - Reasonable file size (< 200 MB for ~120 s)
- Reported the absolute output path to the user