Skip to content
Back to search

demo-video-voiceover

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sps014--demo-video-voiceover/badge.svg)](/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

i

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
  1. ---
  2. name: demo-video-voiceover
  3. 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.
  4. ---
  5. # Demo video voice-over
  6. 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).
  7. ## Defaults (do not ask)
  8. - Voice: Gemini TTS via Vertex, voice `Charon`, calm product-demo style.
  9. - Waits (spinners, "working on it", progress bars): sped up to about 1.5 s with a "Processing... (sped up)" label. Not cut.
  10. - 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.
  11. - Stills longer than 2 s inside kept parts are squeezed to 1 s automatically.
  12. - 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.
  13. - Output 1920 wide, 30 fps, H.264 + AAC, in a working folder outside any git repo: `~/Desktop/demo-edit-<short-name>/`.
  14. - Apply user notes such as "I showed X at the end, it should be at the start" by reordering segments.
  15. ## Tools
  16. 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`).
  17. 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`.
  18. 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.
  19. ## Workflow
  20. ```
  21. - [ ] 1. Prepare working folder and contact sheets
  22. - [ ] 2. Learn the product (repo/docs if given)
  23. - [ ] 3. Map the recording and find exact boundaries
  24. - [ ] 4. Write edit_list.json
  25. - [ ] 5. Write script.json and generate voice
  26. - [ ] 6. Render preview and check sync; fix and repeat
  27. - [ ] 7. Render final, check, clean up, report
  28. ```
  29. **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.
  30. **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.
  31. **3. Map and find boundaries.** From the sheets, label each stretch: action (keep), waiting (fast), noise (drop). Then pin exact times with
  32. `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:
  33. - 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`;
  34. - transient windows that flash in (file converters, "Opening…" dialogs, update popups); keep them inside `fast` or `drop` stretches;
  35. - the last frame: the closing line holds on it, so end on a clean, representative screen (no half-open windows).
  36. **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).
  37. **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).
  38. **6. Preview and check.**
  39. `uv run S/render.py WORKDIR --preview` then `uv run S/check.py WORKDIR --preview`, and read `WORKDIR/check/sync.jpg`.
  40. - Every frame in sync.jpg must show what its line talks about. If not, move the boundary (step 3) rather than rewording.
  41. - `WARNING ... needs Ns of hold` means the line is longer than its footage: shorten the line, or attach it to an earlier segment.
  42. - `OVERLAP` should never happen; `silent gap` over ~8 s: add or lengthen a line, or tighten the segment.
  43. - 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).
  44. - Edit JSON files with Python or the editor, not sed (formatting changes break patterns).
  45. **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.
  46. ## Additional resources
  47. - JSON formats, an example edit list and script, timing rules: [reference.md](reference.md)
README.md · README · 106 lines
  1. # demo-video-voiceover
  2. An agent skill that turns a raw screen recording into a client-ready product demo:
  3. - **AI voice-over** with Gemini TTS on Vertex AI, written to match what is on screen
  4. - **Waits sped up** (spinners, "working on it", progress) to ~1.5 s with a *Processing... (sped up)* label
  5. - **Noise cut**: errors and retries, OS popups, file-picker fumbling, rapid switching
  6. - **Reordering**: e.g. move the part where you showed the input files to the start
  7. - **Sync checks**: frame at every narration line, still-frame and overlap detection
  8. 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.
  9. ## Install
  10. 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.
  11. | Agent | Personal (all projects) | Project only (commit it with the repo) |
  12. |---|---|---|
  13. | Cursor | `~/.cursor/skills/demo-video-voiceover` | `.cursor/skills/demo-video-voiceover` |
  14. | Codex (CLI, IDE extension, app) | `~/.agents/skills/demo-video-voiceover` (older versions: `~/.codex/skills/`) | `.agents/skills/demo-video-voiceover` |
  15. | Claude Code | `~/.claude/skills/demo-video-voiceover` | `.claude/skills/demo-video-voiceover` |
  16. ```bash
  17. # Cursor
  18. git clone https://github.com/sps014/demo-video-voiceover ~/.cursor/skills/demo-video-voiceover
  19. # Codex
  20. git clone https://github.com/sps014/demo-video-voiceover ~/.agents/skills/demo-video-voiceover
  21. # Claude Code
  22. git clone https://github.com/sps014/demo-video-voiceover ~/.claude/skills/demo-video-voiceover
  23. ```
  24. Restart the agent (or start a new session) after installing. Update later with `git -C <that folder> pull`.
  25. ### Codex
  26. Once installed, Codex lists the skill under `/skills`. Ask normally, or name it:
  27. ```text
  28. $demo-video-voiceover make a client demo of ~/Desktop/recording.mov with a voice-over
  29. ```
  30. 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.
  31. ### Any other agent
  32. Any harness that can read files and run shell commands can use it, even without built-in skill support:
  33. 1. Clone the repo anywhere, e.g. `~/skills/demo-video-voiceover`.
  34. 2. Point the agent at it from its instructions file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, a system prompt, ...):
  35. ```markdown
  36. ## Demo videos
  37. When I share a screen recording and ask for a demo, voice-over or clean-up, read
  38. ~/skills/demo-video-voiceover/SKILL.md and follow it. Its scripts are in
  39. ~/skills/demo-video-voiceover/scripts/ and run with `uv run`.
  40. ```
  41. 3. Or, one-off, start the prompt with: "Read ~/skills/demo-video-voiceover/SKILL.md and follow it for this recording: ...".
  42. 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.
  43. ## Requirements
  44. - [uv](https://docs.astral.sh/uv/): scripts declare their dependencies inline, `uv run` installs them on first use
  45. - `ffmpeg` and `ffprobe` (`brew install ffmpeg`, `apt install ffmpeg`)
  46. - Vertex AI access for the voice:
  47. ```bash
  48. gcloud auth application-default login
  49. mkdir -p ~/.config/demo-video-voiceover
  50. cat > ~/.config/demo-video-voiceover/.env <<'EOF'
  51. GOOGLE_GENAI_USE_VERTEXAI=True
  52. GOOGLE_CLOUD_PROJECT=your-project-id
  53. GOOGLE_CLOUD_LOCATION=global
  54. EOF
  55. ```
  56. ## Scripts
  57. All take a working folder (`WORKDIR`) and are run with `uv run scripts/<name>.py`.
  58. | Script | Does |
  59. |---|---|
  60. | `prepare.py VIDEO WORKDIR` | links the source, makes labelled contact sheets (1 frame / 5 s), detects still spans |
  61. | `frames.py VIDEO OUT.jpg 412:430:1 ...` | grid of frames at given times, for pinning exact screen changes |
  62. | `tts.py WORKDIR` | one Gemini TTS clip per line in `script.json` (only changed lines) |
  63. | `render.py WORKDIR [--preview]` | builds `demo.mp4` from `edit_list.json` + `script.json`, cached per piece |
  64. | `check.py WORKDIR [--preview]` | overlaps, silent gaps, long stills, and a sync contact sheet |
  65. File formats and script-writing guidance: [reference.md](reference.md).
  66. ## Manual use
  67. ```bash
  68. S=~/.cursor/skills/demo-video-voiceover/scripts
  69. W=~/Desktop/demo-edit-myapp
  70. uv run $S/prepare.py "Screen Recording.mov" $W
  71. # write $W/edit_list.json and $W/script.json (see reference.md)
  72. uv run $S/tts.py $W
  73. uv run $S/render.py $W --preview && uv run $S/check.py $W --preview
  74. uv run $S/render.py $W # final: $W/demo.mp4
  75. ```
  76. ## License
  77. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.