narrated-video-alignment

Aligns TTS narration and burned-in subtitles with chapter boundaries of an existing segmented video.

2|Updated Jan 2, 2026
One-click install
npx skills add https://github.com/ShineBreaker/Guix-configs --skill narrated-video-alignment-shinebreaker
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: narrated-video-alignment
Source: https://github.com/ShineBreaker/Guix-configs/tree/main/dotfiles/mutable/agents/hermes/.local/share/hermes/skills/media/narrated-video-alignment
Command: npx skills add https://github.com/ShineBreaker/Guix-configs --skill narrated-video-alignment-shinebreaker

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Finished videos (HyperFrames explainers, slide decks, screencasts) often have narration that drifts from the picture: the voiceover talks about the wrong chapter, runs shorter or longer than the visual segment, or crosses chapter title cards. This Skill repairs the audio and subtitle track of an already-rendered video without re-rendering the visuals. ## Core Features & Use Cases - Misalignment Diagnosis: Runs a 1fps frame probe to build a visual chapter inventory, then classifies the problem as topic drift, length drift, or boundary drift before rewriting anything. - Script Rewrite + TTS Alignment: Rewrites the voiceover script per visual chapter, then uses ffmpeg atempo compression or silence padding to fit each chapter's TTS audio to its target duration. - Subtitle Generation Without Whisper: Extracts sentence-level timings via ffmpeg silencedetect, reconciles phrase counts against the script, and burns SRT subtitles into the MP4 with the ffmpeg subtitles filter. - Use Case: A 14-minute Chinese course video has a TTS track 30 seconds short and subtitles showing "Day 05" while the screen shows "Day 04". This Skill probes the frames, rewrites the script to match the visuals, aligns each chapter's audio, and produces a final MP4 with accurate burned-in subtitles. ## Quick Start Ask the AI to fix the audio and subtitles of your rendered video so the narration matches what is on screen, for example: "My course video's voiceover is out of sync with the chapters — realign the narration and burn in corrected subtitles."

Frequently Asked Questions about narrated-video-alignment

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix audio and video out of sync in a rendered video?▼

First run a 1fps frame probe with ffmpeg to build a visual chapter inventory, then classify the mismatch as topic, length, or boundary drift. Rewrite the script to match the visuals, then use atempo compression or silence padding to fit each chapter's TTS audio to its target duration.

How to generate subtitles without Whisper?▼

Use ffmpeg silencedetect to find pauses in the TTS audio and convert them into sentence-level phrase timings. Reconcile the phrase count against the script's sentence count by merging or splitting, then emit an SRT file and burn it in with the ffmpeg subtitles filter.

How do I speed up TTS audio to fit a video chapter with ffmpeg?▼

Use the atempo filter with a factor of actual duration divided by target duration, valid in the 0.5 to 2.0 range for a single chain. For factors beyond 2.0, chain multiple atempo filters; if audio is too short, append silence generated with anullsrc instead.

Why does ffmpeg concat fail with No such file errors?▼

The concat demuxer resolves relative paths against the current working directory, not the list file location. Always write absolute paths into the concat list file, or set cwd to the working directory in the subprocess call.

When should I not use atempo to fix narration length?▼

Avoid atempo factors above roughly 1.5x because the voiceover starts sounding rushed and unnatural. In that case rewrite the script shorter instead of shipping heavily sped-up audio, and ask the user before accepting large speedups.