subtitles

Burns corrected dictation transcripts onto video as frame-rendered subtitles via an approved HTML page.

Updated Nov 17, 2025
One-click install
npx skills add https://github.com/vzakharov/vovazakharov.com --skill subtitles-vzakharov
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: subtitles
Source: https://github.com/vzakharov/vovazakharov.com/tree/main/.claude/skills/subtitles
Command: npx skills add https://github.com/vzakharov/vovazakharov.com --skill subtitles-vzakharov

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Putting a speaker's corrected words onto their own recording is error-prone: recognizer output contains mis-hearings, corrections change word counts so timings drift, and automated rendering can produce a result nobody reviewed. This Skill defines a workflow that joins the corrected transcript to the original per-word timings and renders subtitles only from a page the operator has seen and approved. ## Core Features & Use Cases - Correction-aware timing join: Maps each corrected word onto the time span of its mis-heard counterpart from the saved Deepgram response, handling cases where corrections merge or split words. - Operator-controlled editorial decisions: Requires explicit choices about which stretches appear on video, whether silences are cut, and how the burn is styled. - Reviewable HTML deliverable: Produces a self-contained HTML page with the video and CSS-animated words that the operator opens locally, adjusts by hand, and approves before rendering. - Deterministic frame rendering: Uses headless Chromium walking the page frame by frame with ffmpeg muxing, driven by frame number rather than wall-clock time. - Use Case: After transcribing a dictated video with corrected text in writing/<project>/dictations/<slug>.md, invoke /subtitles <dictation file> to produce a new video file with the corrected words burned onto the picture. ## Quick Start Run /subtitles on the corrected dictation file for your recording and answer the three questions about which stretches to include, whether to cut silences, and how the burn should look.

Frequently Asked Questions about subtitles

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

FAQPage Schema
How do I add subtitles to a video from a corrected transcript?

Invoke /subtitles with the corrected dictation file after the recording has been transcribed. The workflow joins your corrected words to the saved per-word timings, builds an HTML preview page for your approval, then renders the frames into a new video file.

Why do subtitles drift out of sync after transcript corrections?

Corrections change the word count, so matching timings by index misaligns everything downstream. The fix is joining each corrected word onto the time span its mis-heard counterpart occupied, collapsing or expanding spans as the correction requires.

Can I re-run speech recognition to get word timings for subtitles?

No. The saved Deepgram response is the only valid timing source because the corrections were made against that exact response. A fresh transcription produces a different set of words, invalidating the correction join.

How do I render an HTML animation into a video file?

Drive the animation off the frame number rather than the clock, walk the page frame by frame in headless Chromium, and mux the captured frames with ffmpeg. Clock-driven animations render differently across passes, so the output would not match the approved page.

Should subtitle preview pages embed video as a data URI or a file path?

A relative file path is best for editing because it allows frame-accurate scrubbing and works offline. A raw URL makes the page shareable as one file but may not play in all browsers, while a data URI inflates size by about a third and delays first paint.