afikbae/paper2video / .claude/skills/voiceover
voiceover
VerifiedGenerate, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.8 KB |
SKILL.md
View on GitHub---
name: voiceover
description: 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
```bash
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`)
| provider | needs | notes |
|---|---|---|
| `openrouter` | `OPENROUTER_API_KEY` in `.env` | default; model `google/gemini-3.1-flash-tts-preview`, voices such as Charon, Puck, Kore, Fenrir, Aoede |
| `gemini` | `GEMINI_API_KEY` | Google AI Studio directly; same voices |
| `say` | macOS | robotic but free; good for timing drafts |
| `silent` | nothing | ~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:
```bash
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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |