Add a Narrated Demo Video to Your GitHub README
Published · Updated · Jakub Kuźnicki
Update policy: product facts, cited sources, and checked output evidence are revalidated when they change. See the author methodology.
A README with a static screenshot undersells a CLI
A README that only shows a code block and a screenshot makes a visitor guess whether the tool actually does what the words say. A short demo clip closes that gap in seconds, but the usual advice, record your screen, upload to a video host, paste an embed, is three extra tools for something that should take one. I tested the shorter path: draw the quickstart with Scribe and drop the export straight into the README.
The fixture: a five-line quickstart
# Quickstart
Install the CLI.
Run the setup command.
Drop the exported clip into the README and commit it.This is what the article embeds so you can inspect the drawing at full resolution: a heading, then three short instructions, drawn in order. For a real README, though, the file you actually want is not this MP4.
MP4 is for the article; GIF is for the README
Scribe's studio has a second export button next to Download video: a GIF export built specifically for README, Slack, Discord and X embeds, where a viewer expects something that just plays without clicking a player control. It's signed in, like the MP4 path, but unmetered (it doesn't spend one of your daily export credits) and unbranded (no end card, even on FREE). The FREE tier caps a GIF at a 480px short edge, 12 fps and 10 seconds; a longer recording plays faster to fit rather than getting cut off. Premium raises that ceiling to a 1080px short edge, 15 fps and 20 seconds.
For a README specifically, that trade-off is the right one: a GIF is the one clip format every Markdown renderer plays inline with zero extra markup, no player chrome, no autoplay policy to fight. An uploaded MP4 can work too on hosts that render it inline, but a GIF is the safer default when you don't control where the README gets mirrored.
The actual steps
- Write the shortest sequence that proves the tool works: install, one command, one visible result. Five lines is plenty.
- Paste it into Scribe as plain text or code, preview it, and only then click the GIF export instead of Download video.
- Drag the downloaded .gif into your README.md's edit view; GitHub uploads it and inserts the Markdown image syntax automatically.
- Commit the README change alongside the code, so the demo never drifts out of sync with what the repository actually does.
None of this needs a webcam, a microphone or a separate screen recorder. The narration is the pen drawing the same words a reader would otherwise read silently; it earns its place by adding pace and sequence, not by adding a voice.
When it's not worth the extra file
A one-line CLI with no visible output doesn't need a clip: a code block says everything a GIF would. Save the export for a quickstart with a visible before/after, a UI, or a sequence long enough that a reader benefits from watching the order rather than reconstructing it from a numbered list.
Try it on your own quickstart
Preview is free and doesn't require an account; sign in only when you're ready to export. Start on Scribe, read the documentation use case for the rest of the paste-and-preview flow, and check pricing for what a FREE versus Premium export includes.
For a companion piece on turning a pull request diff into a similar clip, see turn a git diff into a hand-drawn walkthrough video; for a longer documentation excerpt handled the same way, read turn technical documentation into a short video.