Developer screencasts: terminal, code, browser

When a generic recorder meets a page of code#

Teaching a developer something means putting three surfaces on screen that most screen recorders were never tuned for: an editor packed with small colored text, a terminal that is really a stream of characters pretending to be a picture, and a browser showing the result. A recorder built for a webinar or a talking head treats all three as generic pixels, and all three fall apart in their own way. This is the format problem specific to a developer-education screencast, and it sits downstream of the pillar question of when video earns a place in docs at all. Assume it has earned one. The next question is how to capture code so it still teaches after it has been through a codec.

Why a codec eats your code before your reader does#

Start with the compression, because it decides everything else. YouTube's own recommendation for a 1080p SDR upload at 30fps is H.264 in an MP4 at 8 Mbps¹. H.264 stores color at 4:2:0, which means the two chroma channels are "each subsampled at a factor of 2 both horizontally and vertically"², discarding three quarters of the color samples and bleeding color across borders. Syntax highlighting is precisely the content that suffers: fine, saturated, high-contrast-edged text, where the purple that marks a keyword and the green that marks a string differ mostly in the channel the codec throws away first. Your theme looks crisp in the editor and muddy in the export, and nothing about your recorder caused it.

Font size compounds the loss. Editors run at 12 to 14px on the author's high-DPI display, and the reader almost never watches at the size the author saw.

Recorded on	Delivered at	A 14px glyph becomes	Verdict
2560px display, full screen	1920px player	~10.5px	marginal, thin stems smear
2560px display, full screen	640px blog embed	~3.5px	unreadable
Zoomed to a ~900px region	1920px player	~30px	survives compression

Two moves fix it, and both happen before you record. Raise the editor font to 18 to 22px, and zoom to the region so a 1080p frame carries 60 to 80 columns instead of 200. WCAG treats 18pt (about 24px) as "large text," the size at which a 3:1 contrast ratio is enough where smaller text needs 4.5:1³. That threshold is a useful target for a screencast too, because it is roughly the size at which H.264 keeps a glyph's strokes intact. While you are there, choose a theme whose token colors clear 4.5:1 against the background; the low-contrast pairs a designer reaches for are the first casualties of 4:2:0.

The terminal is text, so capture it as text#

The terminal is the one surface you can escape the codec on entirely. asciinema records a session as newline-delimited JSON⁵, storing the characters and control sequences rather than pixels, so a reader can "pause the player and copy-paste the content you want. It's just text after all"⁴. vhs takes the scripted route: a .tape file it bills as "terminal GIFs as code," replaying typed commands and rendering to GIF, MP4, or WebM at a font size you Set yourself⁶. The full tradeoff among asciinema, a raw recording, and tape-driven replay, scored on file size, editability, and whether viewers can copy the commands, is a decision of its own.

For a screencast the binding constraint is compositional. An asciinema player is a web widget, not a video track, so it will not live inside the same MP4 as your browser footage. That leaves two honest paths: render the terminal with vhs and cut the clip into the timeline, where you control the font and it survives compression, or keep the browser as video and place the asciinema cast beside it as the copyable companion. What you should not do is point a general-purpose recorder from a Camtasia-alternatives roundup at a 12px terminal and hope the prompt reads; those tools capture a talking head well and a wall of monospace poorly.

Show the code or say the code, one rule per line#

The habit that quietly wrecks coding screencasts is reading the code out loud. When narration recites text the viewer is already reading, the two channels compete instead of combine, and both slow down. The voice should carry what the frame cannot: intent, the reason for a choice, the one number in the output that matters.

On screen	What the voice does	Why
The one or two lines that change, zoomed and held	names the change and its purpose	the eye reads syntax faster than you can speak it
Imports, boilerplate, unchanged context	one sentence, then scroll past	dwelling on it teaches nothing
A command and the output it prints	shows both, narrates the effect	the lesson is the result, not the keystrokes
The reasoning behind a decision	holds the frame still	let the ear take the concept while the eye rests
A long file	shows the diff, not the whole file	the change is the content, the file is context

The rule underneath the table: show what is faster to see than to say, and say what is faster to hear than to read.

One timeline, three surfaces#

A dev screencast teaches in an order: set the stage in the terminal, show the code that does the work, cut to the browser result. Move between surfaces with a hard cut, not a pan or a zoom across the desktop. A cut reads as "new context, look here," while a slow pan reads as "same thing, keep watching" and spends the viewer's attention on travel. Zoom each surface to the region that matters and never show the full desktop, both because the desktop is where notifications and clutter live and because a full-screen 1080p editor is exactly the unreadable case the compression section warned about. Move fast through the mechanical parts, the typing and the waiting, and slow down on the moment a decision becomes visible.

Our own engine, aidemo, captures the browser surface deterministically from a storyboard, which covers the third of those three layers but not the first two: it is browser-only, so a terminal or a native editor never enters its frame, and you would pair it with vhs for those. It is worth naming that limit plainly, because a tool that captures one surface well is not a tool that captures a whole screencast.

Keeping a code screencast from lying next release#

A code screencast can break in two places a UI-only demo cannot. The browser layer drifts like any product footage when the interface moves. The code layer drifts on its own: a renamed flag, a changed response shape, or a new default breaks the terminal and editor content silently, and the frame still looks plausible while the narration now describes a command that errors. That second failure is the worse one, because it is invisible in review; a stale button at least looks wrong on sight.

API and SDK quickstarts rot fastest of all, which is the argument for making an API-docs video regenerate from the same fixtures the docs are tested against. The model that holds once you have more than a handful of tutorials is regeneration rather than re-recording (keeping a tutorial library current), and a coding agent can author the spec so the re-render rides the same release that changed the code. aidemo regenerates its browser layer from a committed storyboard instead of a fresh take, though the storyboard is agent-authored and edited as text, with no drag-and-drop timeline anywhere in the loop. Extend the same discipline to the other two surfaces: drive the terminal from a vhs tape and pull the code from the same fixtures your tests run, so all three layers rebuild together on the commit that changed them, or fail loudly instead of shipping a screencast that teaches a command that no longer exists.

Sources#

FAQ#

What font size should I use for a coding screencast?#

Big enough that the smallest glyph survives the codec, not the size you code at. On a 2560px display recorded full-screen, a 14px editor font lands near 10.5px in a 1080p player and about 3.5px in a 640px blog embed, well past legible. Raise the editor to 18 to 22px and zoom to 60 to 80 columns so the delivered glyph sits near WCAG's 18pt large-text mark, which is roughly where H.264 stops smearing the strokes.

Can viewers copy the commands out of a terminal screencast?#

Not out of a video; a codec turns your terminal into pixels. If copyable commands matter, record the terminal with asciinema, which stores the session as text and lets a viewer pause and copy-paste straight from the player. If you need the terminal inside a single MP4 alongside browser footage, render it with vhs at a font size you control and accept the commands are now unselectable, or embed the asciinema cast beside the video as the copyable companion.

How do I keep a programming tutorial video up to date?#

Treat it as something that rebuilds, not something you re-shoot. A code screencast drifts on two fronts, the UI it shows and the code it runs, and the code half fails silently when a flag or response changes. Derive each surface from source: the browser from a committed storyboard, the terminal from a vhs tape, the code from the same fixtures your tests use, so a change that breaks the demo either regenerates it or turns the build red.

This article was researched and drafted with AI assistance and reviewed by the aidemo maintainers. Tool capabilities and prices change — check vendor docs before deciding. How we research and correct our articles →