Add a 60-Second Explainer Video to Your Project README (No Camera, No Editing)

A visitor gives your repository a few seconds to decide whether it is worth reading, and a short explainer video can show what the project does faster than three paragraphs of README. GitHub plays MP4 files inside Markdown, so the video can sit at the top of the README.

Write the script first

One minute of narration at a normal speaking pace is about 150 words. Use this shape:

1. The problem, in one sentence a user would say.          (~20 words)
2. Who it is for.                                          (~15 words)
3. What the project does, as three short beats.            (~50 words)
4. One concrete example with real input and output.        (~45 words)
5. How to get started: the install command or the link.    (~20 words)

A filled-in example for an imaginary CLI tool:

You changed one config value and now three services fail at startup.
envcheck is for teams that keep settings in .env files.
It reads every service's env file, compares them with a schema,
and tells you which values are missing, misspelled, or the wrong type.
Run envcheck in the repo root. It finds that PAYMENT_TIMEOUT is "30s"
in one service and 30 in another, and shows both lines.
Install it with npm install -g envcheck, and run it before every deploy.

Time yourself reading it aloud. If it runs past 60 seconds, cut beat 2 first; the README already says who the project is for.

Turn the script into a video

A screen recording with your own voice, using OBS or the recorder that came with your OS, works best when the interface is the point, as with a desktop app or a dashboard. It needs a quiet room and a few takes.

Record your voice over a short deck in Keynote, PowerPoint, or Google Slides, then export it as video. The output is dependable, though it looks like a slide deck.

An AI explainer generator takes the script and returns a narrated, animated video. I work on GenPixy AI, which does this in the browser: you supply up to 5,000 characters of script, pick a Whiteboard or Color Board style, landscape or vertical, and a narration language. It returns an MP4 with hand-drawn scenes, burned-in captions, background music, an SRT file, and a thumbnail. Free videos are up to 60 seconds at 720p, which is enough for a README. This works for CLI tools, libraries, and APIs when there is no interface worth recording and the concept is what needs explaining.

Keep captions on. Many people watch with the sound off, and a README video does not autoplay with sound anyway.

Get the file under 10 MB

GitHub accepts videos up to 10 MB in Markdown on free plans and up to 100 MB on paid plans. One pass of ffmpeg usually gets a 60-second 720p explainer there:

ffmpeg -i explainer.mp4 \
  -vf "scale=1280:-2" \
  -c:v libx264 -crf 28 -preset slow \
  -c:a aac -b:a 96k \
  -movflags +faststart \
  readme-demo.mp4

-crf 28 trades a little sharpness for a much smaller file; drawings and flat colors compress very well, so the loss is hard to see. Raise it to 30 if the file is still too large. +faststart moves the index to the front of the file so the player can start before the whole file loads.

Some places, such as package registries and older docs sites, do not play video. For those, make a silent 10-second GIF of the strongest part:

ffmpeg -ss 5 -t 10 -i explainer.mp4 \
  -vf "fps=12,scale=720:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" \
  -loop 0 readme-demo.gif

Put the video in the README

Dragging the file into the README editor on github.com sometimes uploads it and sometimes does nothing. The issue editor always works:

1. Open a new issue in your repository.
2. Drag readme-demo.mp4 into the comment box. GitHub uploads it and inserts a https://github.com/user-attachments/assets/... link.
3. Copy that link and close the issue without submitting it.
4. Paste the link on its own line near the top of your README, then commit.

GitHub renders the link as a video player. Put one sentence above it that says what the project does, so people who skip the video still get the point.

Reuse it for the launch

The same script works for your launch post. A vertical cut belongs on X, LinkedIn, and Shorts, while the landscape one stays in the README and on the docs homepage. If you add a feature that changes the pitch, update the script and make the video again; it is cheaper than leaving an outdated demo at the top of your repository.