A Product Video You Can Rebuild with One Command
Screen recordings go stale when the UI changes, and re-recording one by hand is tedious. slidecast turns slides, recorded clips and a narration script into a narrated MP4, with a drivable recorder that moves a visible cursor and fails the build when the frame slices a button in half. The 1.5-minute jobwatch tour is built with it, on made-up data, and rebuilt with one command when the UI moves.
TL;DR
A demo video is a document that nobody keeps up to date, because updating it means re-recording it. slidecast treats the video as a build. You bring HTML slides, optional recorded clips and the words; it screenshots each slide with a headless browser, speaks the narration with a pluggable text-to-speech voice, and stitches the result into one MP4 with ffmpeg. Change a sentence or a screen, run the build again, get a new video.
mlx extrasay, or silenceIt’s on PyPI and at github.com/vinayvobbili/slidecast.
What it is, in a few lines
1
2
3
4
5
6
from slidecast import Reel, MLXKokoroTTS
reel = Reel(width=1280, height=720, tts=MLXKokoroTTS(voice="af_heart"))
reel.add("<!doctype html><h1>Hello</h1>", "Hello, and welcome.")
reel.add_clip("scan.webm", "Click Scan, and every question gets a cited draft.")
reel.render("out.mp4", make_poster=True)
A slide is any HTML you like: slidecast has no opinion about how it looks. Each slide is padded to fit its narration exactly when the voice reports a duration. A recorded clip plays through, and if the narration runs longer, its last frame holds until the voice finishes; the clip is letterboxed, never stretched. Every piece is swappable: the voice (anything with synthesize(text, path)), the renderer, and the ffmpeg steps, which take an injectable runner so the command lines can be tested without running ffmpeg.
How the jobwatch tour is built
The 1.5-minute tour on jobwatch’s home page is built with slidecast. It’s a screen recording of the real jobwatch ui, running on a seeded demo of invented companies (Acme, Globex, Initech, Umbrella, Hooli). Nothing reads a real watchlist, reaches a job board or calls a model. One command, scripts/videos/make-videos, records and renders it (Kokoro narration needs Apple Silicon), and --dry takes a screenshot after each action to check framing without making a video.
The story has a fixed shape, which slidecast ships as defaults:
- A silent three-second title card.
- The problem, as an animated scene, before the solution.
- A tagline at the turn from one to the other.
- The walkthrough, each clip held as long as its narration.
- The title card again, with the tagline. Never a fade to black.
The “problem” scene is a page of CSS animation. add_animated pauses every animation and steps it frame by frame through the Web Animations API, so the same page renders identically on every run. A timer-driven script wouldn’t, which is why the animation has to start from CSS.
The recorder that behaves like a person
The part I like best is slidecast.recorder.Recorder. It drives a Playwright page and shows what a viewer needs: a cursor that glides to each target before it acts, a ripple on every click, a dotted path for a drag. The overlay is injected into the page, so it’s in the recording and nowhere else.
1
2
3
4
with Recorder.open(browser, "http://127.0.0.1:8765/#settings", "settings.mp4") as rec:
rec.click("text=Save settings") # glide, ripple, click
rec.type("#name", "Jordan")
rec.hold_until(8.0) # a scene as long as its narration
After every action it runs a framing check, find_clipped(page), and raises ClippedError if the edge of the frame slices a visible element in two: a sticky tab bar cut off after a scroll, a button, an input, a heading. A bad take fails the build instead of reaching the video, which is the reason a rebuild is safe to run unattended.
Checks, captions and a cache
slidecast check out.mp4fails if the last half second has black frames, or if the first card runs over four seconds before any voice. A reel with a title card runs the same check at the end ofrender.- Pronunciation is data, not editing. Kokoro says “PDFs” right when it’s written as one word but spells out “P D Fs”, so slidecast joins a spelled-out plural back into its word before speaking it. A
pronunciationsdictionary covers words the voice still gets wrong, and the on-screen captions keep what you wrote. - A cache. Narration and built segments are keyed on the text, voice, settings and the slide’s screenshot, so after editing two slides of a long reel only those two are spoken and encoded again.
- Captions. jobwatch’s build writes a WebVTT file for each video from the narration and the length of each rendered segment, spread a sentence at a time over the spoken line, at most 80 characters a cue. That lives in jobwatch’s
scripts/videos/captions.py, not in slidecast itself. - An upload copy.
slidecast youtube out.mp4writes a 2x copy (2560x1600 from a 1280x800 reel) because YouTube re-encodes everything, and a 1280x800 file lands in its softer 720p tier. It’s Lanczos scaling, so it can’t add detail the slides don’t have; for the sharpest text, design at 2x.
What I’d take from it
The lesson wasn’t about video. It was that a demo you can’t regenerate is already out of date, and that the checks that matter are the boring ones: the frame cuts nothing in half, the video doesn’t end on black, the voice isn’t cut off by the next slide (slidecast check --min-gap). Put them in the build and nobody has to watch the video to know.
1
2
3
pip install 'slidecast[mlx,playwright,yaml]'
playwright install chromium
slidecast render reel.yaml -o out.mp4 --poster
You also need ffmpeg on the PATH, or the slidecast[ffmpeg] extra’s bundled binary.
- Source: github.com/vinayvobbili/slidecast
- PyPI: pypi.org/project/slidecast
- Used by: jobwatch, whose tour and tutorials are built this way
