Writing a training guide by hand is slow. You click through the process, take a screenshot at every step, crop it, paste it into a document, write what to do, then fix the formatting. A ten minute process can easily take an afternoon to document.
Recording a video of the same process takes ten minutes. So I built Clip2Guide: upload a narrated screen recording and get back a branded PDF guide, with the screenshots picked for you and a step by step written from what you said and what was on screen. It’s in regular use now, and the guides it produces only need light editing.
How it works
The whole thing is a small web app. You sign in, upload a video and watch it move through the stages:
- Transcribing. faster-whisper turns the narration into text with timestamps. It runs on the CPU, no graphics card needed.
- Detecting scenes. PySceneDetect finds the moments where the screen changes noticeably: a new window, a menu opening, a page loading.
- Capturing screenshots. ffmpeg grabs a frame at each of those moments.
- Building the guide. The transcript and the screenshots go to Claude, which works out the sequence of steps.
- Rendering the PDF. The steps are laid out in an HTML template, turned into a PDF with WeasyPrint, and the branded cover and closing pages are added.
Then you download the PDF. The page checks the status every few seconds, so you can see which stage it’s on.
Getting the AI to write a good guide
The step that makes or breaks it is the prompt that turns a transcript and a pile of screenshots into a guide. A few rules made a big difference:
- Every step has a short action title, one to three sentences, and the screenshot that best shows it. That keeps the output consistent from video to video.
- Skip the meeting chatter. Recordings often start with “can everyone see my screen?” and end with goodbyes. The guide starts at the first step that actually shows the product.
- Don’t invent anything. Every step has to be grounded in what was said or shown. If the narration goes quiet for a stretch, the guide relies on the screenshots and says so, rather than guessing at menu names that never appeared.
- Write it as a guide, not a story about the video. It never says “the presenter clicks…”. It just tells the reader what to do.
- Ask for JSON, not prose. The AI returns a title, a summary and a list of steps in a fixed shape, which the template turns into the PDF. No reformatting by hand.
Things I learned building it
Check your CPU for AVX2. My first test box kept crashing on the transcription step. The cause turned out to be its CPU, which didn’t support AVX2, an instruction set that the speech recognition library relies on. Anything modern has it, but on an older or virtualised CPU it’s worth checking first with grep avx2 /proc/cpuinfo.
Video processing is slow, so queue it. Transcription especially is heavy on the CPU, so uploads go onto a queue and a worker handles one video at a time. If several people upload at once, you can just run more workers with docker compose up --scale worker=3.
Cap the number of screenshots. A long video with lots of screen changes can produce hundreds of candidate frames. Clip2Guide caps it at 40 and spreads them evenly, which keeps the guide readable and the AI request a sensible size.
Silent videos make thin guides. The steps lean heavily on the narration. A screen recording with no talking still gets screenshots, but the instructions are much vaguer, so it’s worth talking through what you’re doing while you record.
Running it
It’s all in Docker Compose: a front end, an API, a worker for the video pipeline and Redis for the queue and sign in sessions. There’s no public sign up. An admin creates accounts from a settings page, and sessions are stored on the server, so removing a user signs them out straight away.
Was it worth building?
Yes. Writing guides by hand took ages, and now a recording becomes a finished guide in minutes instead of an afternoon. The AI doesn’t get every step perfect, so the guides need light editing, but editing a good first draft is far quicker than starting from a blank document.
What to read next
total 3
Got a question about this, or built something similar? Get in touch. New write-ups go out on the RSS feed and LinkedIn, everything I've built is on the projects page, and my free calculators and guides are on the tools page.