Markdown Technical Documentation to Narrated Video

Problem It Solves

Technical docs are easy to read but harder to share as training material. A short narrated video can be more useful, but screen recordings and manual editing often make the pacing uneven, and Remotion animation frames do not always match TTS duration automatically. This skill turns a Markdown technical document into a 1920×1080 MP4 with H.264 video and AAC audio, focusing on structured content, natural narration, and reliable audio-video sync.

How It Works

The workflow is broken into repeatable steps:
- Content segmentation: split Markdown into scenes, with about 100–300 words or characters per narration segment.
- Voice generation: use edge-tts, for example zh-CN-XiaoxiaoNeural, then concatenate and adjust speed with FFmpeg and atempo.
- Visual rendering: build Remotion components such as VideoScene, CodeBlock, StepItem, and ProblemCard for a dark technical visual style.
- Audio-video merge: render the video first, inspect actual nb_frames with ffprobe, recalculate scene boundaries, update durationInFrames and frame arrays, then re-render to reduce drift.

Boundaries and Caveats

This is best suited to 3–3.5 minute tutorials with roughly 9–16 scenes, such as Docker Registry or Solidity multisig guides. Keep in mind that durationInFrames is not an exact rendered frame count, single atempo values above 2.0 may alter pitch, and if the source video contains a silent audio track, remove it with -an before merging. If edge-tts is unavailable, system voices can be used as a fallback, but quality and stability may be lower.