Skip to content

afikbae/paper2video / .claude/skills/voiceover

voiceover

Verified

Generate, audition, regenerate or fix narration audio for a paper video from narration.json (stage 4 of paper-to-video). Use for text-to-speech, changing voice or pace, mispronunciations, clips flagged LOW, or adding a voice-over on top of an existing video.

Voice-over

uv run scripts/generate_voice.py P                         # all segments; unchanged ones are skipped
uv run scripts/generate_voice.py P --only 03-method,07-results
uv run scripts/generate_voice.py P --force                 # regenerate all
uv run scripts/generate_voice.py P --audition Charon,Puck,Kore,Fenrir --only 01-title   # -> audio/audition/
uv run scripts/generate_voice.py P --provider say          # free offline draft (macOS)
uv run scripts/generate_voice.py P --provider silent       # silence of estimated length, for timing only

Output: P/audio/<id>.wav (24 kHz mono) and <id>.json (text hash, voice, duration, similarity). A clip is regenerated automatically when its text, voice, model, style or provider changes.

Providers (tts.provider in narration.json, or --provider)

providerneedsnotes
openrouterOPENROUTER_API_KEY in .envdefault; model google/gemini-3.1-flash-tts-preview, voices such as Charon, Puck, Kore, Fenrir, Aoede
geminiGEMINI_API_KEYGoogle AI Studio directly; same voices
saymacOSrobotic but free; good for timing drafts
silentnothing~2.6 words/s of silence

.env is looked up in the project folder, the current folder, then the repo root. Never print or commit keys.

Pace and style

tts.style is a natural-language instruction prepended to every text. Gemini TTS follows it and does not speak it; other models may read it aloud, and the transcription check will catch that. Per-segment overrides: {"id": "...", "text": "...", "tts": {"voice": "Puck"}}.

Verification

With verify.model set and an OpenRouter key, each clip is transcribed back and compared word for word with the script; below min_similarity it retries up to retries times and keeps the best take. Clips still below the threshold are listed under NEEDS ATTENTION with what was heard. Fixes: rephrase the sentence, spell a term the way it sounds, or split long sentences. Rewording usually works best. Listen to flagged clips before accepting them.

Voice-over on an existing video

Either add a narration segment to narration.json and reference its id from a clip item in timeline.json ("narration": "<id>", see the video-editing skill), or do it directly:

uv run scripts/videotools.py dub in.mp4 P/audio/04-demo.wav out.mp4 --offset 1.0 --duck 0.2

The original audio drops to --duck (0.2 = 20 %) while the voice speaks; the last frame is held if the voice outlasts the video (--no-extend to cut instead).

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall