check-voiceover
Skill2 starsChanged 29 days agoMITView on GitHub
Check that a generated or recorded voiceover actually says the script - skipped phrases, wrong numbers, stray repeats, garbled names and paragraphs read at an impossible pace, with timestamps - then pick the best generated take per paragraph and shorten long pauses without stretching speech. Use right after TTS or recording, for "check the voiceover", "did the AI voice skip anything", "compare audio to script", "pick the best take", "the narration has long pauses", or before syncing visuals to narration.
- Installs packages
In this repository13 other files it gives its agents.
- channel-pulseSkill
- check-renderSkill
- check-thumbnailSkill
- find-topicSkill
- localizeSkill
- make-shortsSkill
- morph-clipsSkill
- produce-videoSkill
- research-factsSkill
- retention-by-sceneSkill
- setupSkill
- upload-privateSkill
- write-scriptSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 42
Run voice_check.py on the joined audio.
- Distinctive: line 64
Only the changed paragraphs need new audio.
- Very specific: line 67
When the check and your ears disagree, or before you build captions, read references/failure-modes.md: the recognizer inventing words at …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Check the voiceover
Text-to-speech skips words, reads "12.5" as "125", repeats phrases and sometimes reads a paragraph over and over. Listening for that across ten minutes is slow and unreliable; comparing a transcript with the script is fast and exact.
$SKILL below is this skill's folder.
Run
python $SKILL/scripts/voice_check.py script.md voice/narration.srtThe second argument is a transcript (SRT, VTT or Whisper JSON) or the audio file itself. Audio needs
pip install faster-whisper; any transcript from your editor, Descript or Whisper works too. A template script
with {placeholders} must be compiled to plain text first. Write one paragraph per line in script.md: every
line is a paragraph, and all three scripts here number paragraphs the same way.
Read the result
- FAIL: a number that differs, a skipped run of three or more words, or a paragraph paced outside 100-300 words per minute: too slow is a repeat loop, too fast a swallowed sentence. Regenerate or re-record that paragraph; do not "fix it in the edit".
- WARN: other differences (often the recognizer mishearing a name), or a pace outside 150-215 wpm. A slow WARN is a question, not a verdict: a dense paragraph can honestly read slowly. Listen to those timestamps.
- Pace needs word timings (Whisper JSON with words, or the audio). The bands are tuned for generated voices;
for a recorded voice pass
--wpm-band 130,190. - The report (
qa/voice-check.json) lists every paragraph;failing_paragraphsis what to regenerate. Exit 1 blocks the next station.
Generated voice
- Generate paragraph by paragraph into
voice/paragraphs/p001.wav,p002.wav, ... (python $SKILL/scripts/pick_takes.py script.md --listprints the numbered paragraphs). Follow the TTS input rules inreferences/failure-modes.md. Join the files in order without adding generated silence. - Run
voice_check.pyon the joined audio. Note the failing paragraphs. - Regenerate only those, three or four takes each with new seeds (a fixed seed repeats the same mistake),
into
voice/candidates/<paragraph number>/<any name>.wav. - Pick:
Takes are ranked by word fidelity; a take only counts when every number and name of the paragraph is heard exactly and its pace is plausible. With ffmpeg on PATH, a take whose timbre (spectral centre) is more than 15% from the rest of the narration is vetoed too (python $SKILL/scripts/pick_takes.py script.md voice/candidates --apply voice/paragraphs--timbre-drift PCT,--no-timbre). Exit 1 names the paragraphs with no usable take: back to step 3. Three rounds is normal. If one name fails in every take, change the TTS input instead of adding takes. - Join again, then shorten long pauses (speech is never stretched; a new file is written):
python $SKILL/scripts/trim_silence.py voice/narration.wav --measure python $SKILL/scripts/trim_silence.py voice/narration.wav - Final
voice_check.pyon the trimmed file. Trim before the final transcription and alignment: every timing after the first cut moves.
After a fix
Only the changed paragraphs need new audio. Timings after them shift, so re-run this check and anything that depends on word timings (captions, animations tied to words, chapter timestamps).
When the check and your ears disagree, or before you build captions, read references/failure-modes.md: the
recognizer inventing words at seams, cutting and patching audio, TTS input rules, and captions.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

