demo-video-voiceover
Turns a raw screen recording into a client-ready product demo video by adding an AI voice-over (Gemini TTS on Vertex), speeding up waiting/processing phases with a "Processing... (sped up)" label, cutting errors, popups and rapid switching, and reordering parts of the recording. Use when the user shares a screen recording (.mov/.mp4) and asks for a demo, voice-over, narration, cleaning up or tightening a video, or says "same as before" for another recording.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/sps014--demo-video-voiceover)HTML
<a href="/listings/sps014--demo-video-voiceover"><img src="/api/listings/sps014--demo-video-voiceover/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
The repo is the skill: clone it into the skills folder your agent reads. The agent picks it up from the `description` in `SKILL.md` whenever you hand it a recording and ask for a demo, voice-over or clean-up.
| Agent | Personal (all projects) | Project only (commit it with the repo) | |---|---|---| | Cursor | `~/.cursor/skills/demo-video-voiceover` | `.cursor/skills/demo-video-voiceover` | | Codex (CLI, IDE extension, app) | `~/.agents/skills/demo-video-voiceover` (older versions: `~/.codex/skills/`) | `.agents/skills/demo-video-voiceover` | | Claude Code | `~/.claude/skills/demo-video-voiceover` | `.claude/skills/demo-video-voiceover` |
# Cursor git clone https://github.com/sps014/demo-video-voiceover ~/.cursor/skills/demo-video-voiceover # Codex git clone https://github.com/sps014/demo-video-voiceover ~/.agents/skills/demo-video-voiceover # Claude Code git clone https://github.com/sps014/demo-video-voiceover ~/.claude/skills/demo-video-voiceover
Restart the agent (or start a new session) after installing. Update later with `git -C <that folder> pull`.
Codex
Once installed, Codex lists the skill under `/skills`. Ask normally, or name it:
$demo-video-voiceover make a client demo of ~/Desktop/recording.mov with a voice-over
Codex runs shell commands in a sandbox. Rendering needs `ffmpeg`, `uv` (which downloads packages on first run) and network access to Vertex AI for the voice, so allow network access for the session (for example `codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true`) or approve the commands when asked.
Any other agent
Any harness that can read files and run shell commands can use it, even without built-in skill support:
1. Clone the repo anywhere, e.g. `~/skills/demo-video-voiceover`. 2. Point the agent at it from its instructions file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, a system prompt, ...):
## Demo videos When I share a screen recording and ask for a demo, voice-over or clean-up, read ~/skills/demo-video-voiceover/SKILL.md and follow it. Its scripts are in ~/skills/demo-video-voiceover/scripts/ and run with `uv run`.
3. Or, one-off, start the prompt with: "Read ~/skills/demo-video-voiceover/SKILL.md and follow it for this recording: ...".
The agent needs to be able to view images (it reads contact sheets and sync frames to map the recording and check the result). Text-only models can still render from a hand-written `edit_list.json` and `script.json`, but can't do the sync check.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 66 lines
- ---
- name: demo-video-voiceover
- description: Turns a raw screen recording into a client-ready product demo video by adding an AI voice-over (Gemini TTS on Vertex), speeding up waiting/processing phases with a "Processing... (sped up)" label, cutting errors, popups and rapid switching, and reordering parts of the recording. Use when the user shares a screen recording (.mov/.mp4) and asks for a demo, voice-over, narration, cleaning up or tightening a video, or says "same as before" for another recording.
- ---
- # Demo video voice-over
- Turn a screen recording into a narrated, tightened demo. Apply the defaults below without asking; only ask when the recording itself is ambiguous (e.g. you cannot tell what the product does and no repo or docs are given).
- ## Defaults (do not ask)
- - Voice: Gemini TTS via Vertex, voice `Charon`, calm product-demo style.
- - Waits (spinners, "working on it", progress bars): sped up to about 1.5 s with a "Processing... (sped up)" label. Not cut.
- - Cut: error messages and retries, OS popups (app updates, permission dialogs), Finder/file-picker fumbling beyond the one pick, rapid back-and-forth switching, stopping the recording.
- - Stills longer than 2 s inside kept parts are squeezed to 1 s automatically.
- - Target: 1–2 sentences of 15–30 words per line, about 85–110 words per minute of final video, high-level features (what it does for the user), not UI mechanics.
- - Output 1920 wide, 30 fps, H.264 + AAC, in a working folder outside any git repo: `~/Desktop/demo-edit-<short-name>/`.
- - Apply user notes such as "I showed X at the end, it should be at the start" by reordering segments.
- ## Tools
- Run every script with `uv run` (each declares its own dependencies inline, so there is nothing to install). Needs `uv`, `ffmpeg`/`ffprobe` (any build; labels are Pillow overlays, so `drawtext` is not required) and, for the voice, Vertex AI access through Application Default Credentials. Scripts live in this skill's `scripts/` folder; run them, don't rewrite them. Below, `S` is that folder (e.g. `~/.cursor/skills/demo-video-voiceover/scripts`).
- Vertex settings (`GOOGLE_GENAI_USE_VERTEXAI=True`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`) come from the environment, `--env PATH`, `WORKDIR/.env` or `~/.config/demo-video-voiceover/.env`. If `tts.py` reports no credentials, ask the user for their project once and write `~/.config/demo-video-voiceover/.env`.
- Recording names often contain a narrow no-break space before "PM"; locate them with a glob (`ls Screen\ Recording*4.17.16*.mov`) and pass that path.
- ## Workflow
- ```
- - [ ] 1. Prepare working folder and contact sheets
- - [ ] 2. Learn the product (repo/docs if given)
- - [ ] 3. Map the recording and find exact boundaries
- - [ ] 4. Write edit_list.json
- - [ ] 5. Write script.json and generate voice
- - [ ] 6. Render preview and check sync; fix and repeat
- - [ ] 7. Render final, check, clean up, report
- ```
- **1. Prepare.** `uv run S/prepare.py VIDEO ~/Desktop/demo-edit-<name>` creates `source.mov`, `sheets/s_NN.jpg` (one frame per 5 s, labelled) and `freezes.txt`, and lists the longest stills. Read every contact sheet.
- **2. Learn the product.** If the user gives a repo URL, clone shallowly to `/tmp/<name>` (`gh repo clone owner/repo /tmp/<name> -- --depth 1`), read the README and the main workflow or prompt files for the feature names and steps, then `rm -rf` the clone when the script is written. Never state numbers or claims that are not on screen or in the docs.
- **3. Map and find boundaries.** From the sheets, label each stretch: action (keep), waiting (fast), noise (drop). Then pin exact times with
- `uv run S/frames.py source.mov /tmp/x.jpg 412:430:1` (or a list of times) and read the image. Pin these always:
- - the moment a result or message actually appears (it usually lags the "working" state by a few seconds); the line describing it must start at that moment, so start its segment there and make the time before it `fast`;
- - transient windows that flash in (file converters, "Opening…" dialogs, update popups); keep them inside `fast` or `drop` stretches;
- - the last frame: the closing line holds on it, so end on a clean, representative screen (no half-open windows).
- **4. edit_list.json.** Segments play in list order (that is how reordering works); a 0.25 s crossfade is added automatically wherever footage jumps. Format and an example: [reference.md](reference.md).
- **5. script.json + voice.** One line per narrated beat, each anchored to the segment where its screen starts (`"at": "<segment id>"`), plus an optional closing line with `"at": "end"`. Lines must follow segment order. Then `uv run S/tts.py WORKDIR` (only changed lines are regenerated).
- **6. Preview and check.**
- `uv run S/render.py WORKDIR --preview` then `uv run S/check.py WORKDIR --preview`, and read `WORKDIR/check/sync.jpg`.
- - Every frame in sync.jpg must show what its line talks about. If not, move the boundary (step 3) rather than rewording.
- - `WARNING ... needs Ns of hold` means the line is longer than its footage: shorten the line, or attach it to an earlier segment.
- - `OVERLAP` should never happen; `silent gap` over ~8 s: add or lengthen a line, or tighten the segment.
- - Stills reported with `voice: NONE` longer than 3 s: squeeze, speed up or drop that footage. Stills under a line during a sped-up wait are fine if something on screen still moves (counter, progress bar).
- - Edit JSON files with Python or the editor, not sed (formatting changes break patterns).
- **7. Final.** `uv run S/render.py WORKDIR` → `WORKDIR/demo.mp4`, then `uv run S/check.py WORKDIR`. Delete any repo clone. Report to the user: path, final vs original length, what was sped up, cut and reordered, anything that could not be fixed from the footage (e.g. a screen never shown), and that `script.json` / `edit_list.json` can be edited and re-rendered with the same commands.
- ## Additional resources
- - JSON formats, an example edit list and script, timing rules: [reference.md](reference.md)
README.md · README · 106 lines
- # demo-video-voiceover
- An agent skill that turns a raw screen recording into a client-ready product demo:
- - **AI voice-over** with Gemini TTS on Vertex AI, written to match what is on screen
- - **Waits sped up** (spinners, "working on it", progress) to ~1.5 s with a *Processing... (sped up)* label
- - **Noise cut**: errors and retries, OS popups, file-picker fumbling, rapid switching
- - **Reordering**: e.g. move the part where you showed the input files to the start
- - **Sync checks**: frame at every narration line, still-frame and overlap detection
- Hand the agent a recording ("make a demo of this with a voice-over") and it follows the workflow in [SKILL.md](SKILL.md) with sensible defaults, so you don't have to spell them out each time.
- ## Install
- The repo is the skill: clone it into the skills folder your agent reads. The agent picks it up from the `description` in `SKILL.md` whenever you hand it a recording and ask for a demo, voice-over or clean-up.
- | Agent | Personal (all projects) | Project only (commit it with the repo) |
- |---|---|---|
- | Cursor | `~/.cursor/skills/demo-video-voiceover` | `.cursor/skills/demo-video-voiceover` |
- | Codex (CLI, IDE extension, app) | `~/.agents/skills/demo-video-voiceover` (older versions: `~/.codex/skills/`) | `.agents/skills/demo-video-voiceover` |
- | Claude Code | `~/.claude/skills/demo-video-voiceover` | `.claude/skills/demo-video-voiceover` |
- ```bash
- # Cursor
- git clone https://github.com/sps014/demo-video-voiceover ~/.cursor/skills/demo-video-voiceover
- # Codex
- git clone https://github.com/sps014/demo-video-voiceover ~/.agents/skills/demo-video-voiceover
- # Claude Code
- git clone https://github.com/sps014/demo-video-voiceover ~/.claude/skills/demo-video-voiceover
- ```
- Restart the agent (or start a new session) after installing. Update later with `git -C <that folder> pull`.
- ### Codex
- Once installed, Codex lists the skill under `/skills`. Ask normally, or name it:
- ```text
- $demo-video-voiceover make a client demo of ~/Desktop/recording.mov with a voice-over
- ```
- Codex runs shell commands in a sandbox. Rendering needs `ffmpeg`, `uv` (which downloads packages on first run) and network access to Vertex AI for the voice, so allow network access for the session (for example `codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true`) or approve the commands when asked.
- ### Any other agent
- Any harness that can read files and run shell commands can use it, even without built-in skill support:
- 1. Clone the repo anywhere, e.g. `~/skills/demo-video-voiceover`.
- 2. Point the agent at it from its instructions file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, a system prompt, ...):
- ```markdown
- ## Demo videos
- When I share a screen recording and ask for a demo, voice-over or clean-up, read
- ~/skills/demo-video-voiceover/SKILL.md and follow it. Its scripts are in
- ~/skills/demo-video-voiceover/scripts/ and run with `uv run`.
- ```
- 3. Or, one-off, start the prompt with: "Read ~/skills/demo-video-voiceover/SKILL.md and follow it for this recording: ...".
- The agent needs to be able to view images (it reads contact sheets and sync frames to map the recording and check the result). Text-only models can still render from a hand-written `edit_list.json` and `script.json`, but can't do the sync check.
- ## Requirements
- - [uv](https://docs.astral.sh/uv/): scripts declare their dependencies inline, `uv run` installs them on first use
- - `ffmpeg` and `ffprobe` (`brew install ffmpeg`, `apt install ffmpeg`)
- - Vertex AI access for the voice:
- ```bash
- gcloud auth application-default login
- mkdir -p ~/.config/demo-video-voiceover
- cat > ~/.config/demo-video-voiceover/.env <<'EOF'
- GOOGLE_GENAI_USE_VERTEXAI=True
- GOOGLE_CLOUD_PROJECT=your-project-id
- GOOGLE_CLOUD_LOCATION=global
- EOF
- ```
- ## Scripts
- All take a working folder (`WORKDIR`) and are run with `uv run scripts/<name>.py`.
- | Script | Does |
- |---|---|
- | `prepare.py VIDEO WORKDIR` | links the source, makes labelled contact sheets (1 frame / 5 s), detects still spans |
- | `frames.py VIDEO OUT.jpg 412:430:1 ...` | grid of frames at given times, for pinning exact screen changes |
- | `tts.py WORKDIR` | one Gemini TTS clip per line in `script.json` (only changed lines) |
- | `render.py WORKDIR [--preview]` | builds `demo.mp4` from `edit_list.json` + `script.json`, cached per piece |
- | `check.py WORKDIR [--preview]` | overlaps, silent gaps, long stills, and a sync contact sheet |
- File formats and script-writing guidance: [reference.md](reference.md).
- ## Manual use
- ```bash
- S=~/.cursor/skills/demo-video-voiceover/scripts
- W=~/Desktop/demo-edit-myapp
- uv run $S/prepare.py "Screen Recording.mov" $W
- # write $W/edit_list.json and $W/script.json (see reference.md)
- uv run $S/tts.py $W
- uv run $S/render.py $W --preview && uv run $S/check.py $W --preview
- uv run $S/render.py $W # final: $W/demo.mp4
- ```
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.