Add spoken narration to videos by generating scripts, using text-to-speech engines, and syncing audio lines with video timestamps.
- GitHub stars
- 11
- Files
- 4
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- —
What does the add-voiceover skill do?
add-voiceover is an agent skill. Add spoken narration to videos by generating scripts, using text-to-speech engines, and syncing audio lines with video timestamps.
Summary generated from the skill's SKILL.md.
About the add-voiceover skill
Adding spoken narration to screen recordings, demos, or walkthrough videos is what this skill enables. It allows developers to transform silent video files into narrated presentations by generating scripts designed for listening, producing audio through various text-to-speech engines, and syncing those lines to specific video timestamps. The process produces a final video file, individual audio clips for each line, and a subtitle file for video players.
Users can choose between several audio engines, including ElevenLabs for high-quality narration, Kokoro for a free local option, or custom commands via the VOICEOVER_TTS environment variable. The tool relies on ffmpeg and Node 22 to handle the heavy lifting of audio mixing and video processing. It distinguishes itself by focusing on natural pacing, where lines are timed to land just before an action occurs, and by using context-aware voicing to ensure intonation remains consistent across a script.
What an agent can do with it
- 1Narrate a product demoCreate a spoken walkthrough for a new software feature by syncing short script lines to specific video moments.
- 2Re-voice existing video contentReplace the current audio of a video with a different voice or improved narration.
- 3Fix robotic or out-of-sync audioTroubleshoot and correct voiceovers that sound unnatural, echo, or drift away from the visual timing.
- 4Generate subtitles for videosProduce a VTT subtitle file alongside the narrated video to improve accessibility.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the add-voiceover skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the add-voiceover skill in Plugin
/plugin marketplace add jamdotdev/skills /plugin install jam@jam-plugins
Install the add-voiceover skill in Claude Code
~/.claude/skills/add-voiceover/SKILL.md
$ npx degit jamdotdev/skills/skills/add-voiceover ~/.claude/skills/add-voiceoverInstall the add-voiceover skill in Claude Code (project)
.claude/skills/add-voiceover/SKILL.md
$ npx degit jamdotdev/skills/skills/add-voiceover .claude/skills/add-voiceoverInstall the add-voiceover skill in Codex
~/.agents/skills/add-voiceover/SKILL.md
$ npx degit jamdotdev/skills/skills/add-voiceover ~/.agents/skills/add-voiceoverInstall the add-voiceover skill in Gemini CLI
~/.gemini/skills/add-voiceover/SKILL.md
$ npx degit jamdotdev/skills/skills/add-voiceover ~/.gemini/skills/add-voiceoverInstall the add-voiceover skill in Claude.ai
npx degit jamdotdev/skills/skills/add-voiceover add-voiceover && zip -r add-voiceover.zip add-voiceover # claude.ai → Customize → Skills → + → Create skill → Upload a skill → add-voiceover.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablejamdotdev/skills/skills/add-voiceover is public and reachablegithub.com/jamdotdev/skills/tree/HEAD/skills/add-voiceover ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/jamdotdev/skills/commits ↗Pass
- No download-and-run or credential theft in scripts2 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/jamdotdev/skills/blob/HEAD/skills/add-voiceover/S ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/jamdotdev/skills/blob/HEAD/skills/add-voiceover/S ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 81 linesgithub.com/jamdotdev/skills/blob/HEAD/skills/add-voiceover/S ↗Pass
SKILL.md
View on GitHubAdd a voiceover
A good voiceover sounds like a colleague showing you something: short spoken lines, each one landing on the moment it talks about. Most bad ones come from a script written for reading, one long take of text-to-speech laid over the whole video, or an expressive voice with unstable settings.
Needs ffmpeg and Node 22 or later. The script is scripts/voiceover.mjs in this skill's folder and needs no packages.
1. Pick the voice
The script takes the first voice that is set up:
VOICEOVER_TTS: the team's own command.{out}is the.wavfile to write and{text}the line, also sent on stdin. Quote an argument that holds spaces (--voice="Jane Doe"); backslash escapes are not read.ELEVENLABS_API_KEY: ElevenLabs. Defaults: modeleleven_v4, voiceiP95p4xoKVk53GoZ742B, stability 0.5, similarity 0.75, speaker boost on, and each line voiced with the two lines around it as context so the intonation carries across.ELEVENLABS_VOICE_IDandELEVENLABS_MODEL_IDchange them; for a female voice use River,SAz9YHcvj6GT2YYXdXww. v4 has no speed or style setting: pace it with punctuation and line length.- Kokoro, a free local model, once installed (
~/.cache/kokoroholds its files) and Python 3 anduvare on PATH. Voiceam_michael;KOKORO_VOICEpicks another (af_heart,bf_emma,bm_george). - macOS
say, for drafts only.
When none of the first three is set up, ask the user once which they want:
- ElevenLabs: they set
ELEVENLABS_API_KEYin their own shell. Never ask them to paste the key into the chat or a file. It bills per character, so rehearse withELEVENLABS_MODEL_ID=eleven_flash_v2_5or Kokoro and voice the final cut with the default model. - Kokoro: free and local, a one-time download of about 340 MB. On a yes:
python3 <skill-dir>/scripts/kokoro.py --install. - The OS voice: nothing to set up, sounds robotic.
In CI or with no one to ask, use what is set up and never start the download.
2. Write the script for the ear
Write lines.json, one entry per spoken line:
[
{"say": "Hey, here's the new checkout flow, end to end.", "at": 0.5},
{"say": "I'll add a jar,", "at": 3.2},
{"say": "and place the order.", "at": 6.8},
{"say": "And it fails. Payment provider timeout.", "at": 9.1}
]
- One idea per line, 4 to 14 words. Split a sentence across the actions it describes: "I'll add a jar," then "go to checkout," then "and place the order."
- Say what the viewer should notice, not what the mouse does. "Every item lands in the list" beats "I click the input and type".
- Talk, don't announce: contractions, "so", "here's", first person. No sales lines.
- Tell a story in three parts: what this is, what happens, what it means. The last line lands the result.
- Write numbers and symbols the way they are said: "five-oh-three", "two seconds", "dot env". The voice reads "503" as "five hundred three".
- No captions burned into the video unless the user asks. The script writes
voiceover.vttfor players that show subtitles.
3. Time each line
at is the second the line starts. Start it about half a second before the action it names, so the word and the click land together.
- From a recording you just made: use the times the recorder wrote.
record-demowrites them tonarration.jsonin this format. - An existing video: list the moments the picture changes and look at a frame from each:
ffmpeg -i in.mp4 -vf "select='gt(scene,0.08)',showinfo" -f null - 2>&1 | grep -o 'pts_time:[0-9.]*' ffmpeg -v error -ss 9.1 -i in.mp4 -frames:v 1 at-9.1.png - No picture to match: leave
atout and the lines follow each other with a short breath.
To pace a recording by the voice instead, voice the lines first with no --video, and pass the lines.json it writes (each line with its seconds) to the recorder.
4. Voice and mix
node <skill-dir>/scripts/voiceover.mjs lines.json ./voiceover --video in.mp4
Output in ./voiceover: voiced.mp4 (the picture untouched, the narration raised by one fixed gain so it peaks at -1 dB; a video with its own sound keeps it, and both are lowered together if the mix would pass -1 dB), narration.wav, lines.json with each line's final at and seconds, one .wav per line, and voiceover.vtt. Each line is cached by its text and voice, so after editing one line a re-run voices only that line (with ElevenLabs, also the two on each side, which it hears as context), and switching the voice re-voices everything.
A line that would talk over the one before starts late, and the script prints which. Shorten one of the two lines, or move the later one, and run it again.
5. Check before you share
- Read the warnings. Late lines and narration cut at the end of the video both mean the script is too long for the picture.
- Loudness:
ffmpeg -i voiceover/voiced.mp4 -af volumedetect -f null - 2>&1 | grep -E 'mean|max'. Expect a max of -1 dB and a mean between -18 and -24 dB. Never level the voice withloudnorm, a compressor or other dynamic filters: they raise each word's tail and the voice sounds like it echoes. - Sync: extract a frame one second after each line's
atand check it shows what the line names. - Give the user one line's
.wavto listen to before they watch the whole video.
An echo comes from a dynamic leveler in the mix: compare one line's .wav with the same moment in the video, and if only the video echoes, remove the filter. A laugh, a pitch jump between lines, or a voice that speeds up comes from low stability or an expressive character voice: keep the default settings and pick a narration voice. Never fix sync by stretching the audio; move the line or re-record.
Files in this skill
4add-voiceover skill questions
How do I install the add-voiceover skill in Claude Code?
Run npx degit jamdotdev/skills/skills/add-voiceover ~/.claude/skills/add-voiceover. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the add-voiceover skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.