# 🎬 doc-to-video：将 Markdown 一键变成专业视频

> 让 AI Agent 自动把技术文档变成带配音旁白的 1080p 视频，零门槛，10 分钟搞定。

---

##  一句话介绍

**doc-to-video** 是一个 OpenClaw/QClaw Agent Skill，能把任意 Markdown 技术文档自动转换成带自然人声旁白的专业视频。整个流程：内容分析 → 配音生成 → 视觉渲染 → 音视频合并，全部自动化。

---

## 解决了什么问题？

写技术文档很费时间，把文档做成视频更费时间。

传统的视频制作流程：
- 写旁白脚本 → 人工配音 → 剪辑 → 加字幕 → 导出
- 即使有工具，也需要手动操作，过程碎片化

**doc-to-video** 把这个流程压缩成一条命令：

```bash
# 安装 skill
skillhub install doc-to-video

# 开始制作视频
# （由 AI Agent 自动完成：分析文档 → 生成配音 → 渲染场景 → 合并音视频）
```

技术文档 → 专业视频，全程无需人工干预。

---

## 效果预览

本 skill 已在三个真实项目中验证：

| 项目 | 视频 | 时长 | 场景数 | 文件 |
|------|------|------|--------|------|
| Docker Registry 使用指南 | `docker-registry-guide-final.mp4` | ~153s | 9个 | 3.2MB |
| Docker Registry 搭建记录 | `deploy-docker-registry-final.mp4` | ~207s | 16个 | 5.1MB |
| Solidity Nomad 多签教程 | `solidtidy-final.mp4` | ~210s | 11个 | 6.2MB |

视频风格：深色主题，代码高亮，渐入动画，章节标签，专业感强。

---

##  技术架构

```
Markdown 文档
     │
     ▼
┌─────────────────────────┐
│  edge-tts                │
│  Python · 中文自然人声   │  ← XiaoxiaoNeural / YunjianNeural
│  zh-CN-XiaoxiaoNeural   │
└────────┬────────────────┘
         │ .m4a 音频文件
         ▼
┌─────────────────────────┐
│  FFmpeg atempo           │  ← 无损加速，匹配目标时长
│  两级级联，音质保真      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Remotion                │
│  React · TypeScript      │  ← 场景组件，帧率 30fps
│  1920×1080 全高清       │
└────────┬────────────────┘
         │ MP4（无声）
         ▼
┌─────────────────────────┐
│  FFmpeg 合并             │  ← 去原音 + 嵌入配音
│  H.264 + AAC            │
└────────┬────────────────┘
         │
         ▼
   带配音的 MP4 视频 ✅
```

**为什么用 FFmpeg 而非 Remotion 内置音频？**

Remotion 的 `<Audio>` 组件在多场景场景下不稳定（React Error #130）。FFmpeg atempo 无损加速，可精确控制时长，音质可控，是更可靠的方案。

---

## 核心技术亮点

### 1. 音视频帧级同步

这是视频配音最常见也最难解决的问题。大多数方案靠估算帧数，导致音视频不同步。

**doc-to-video 的解法：两步确认法**

```
Step 1: 渲染一次视频 → ffprobe 确认实际帧数
Step 2: 用实际帧数反推帧边界 → 更新代码 → 重渲染 → 合并
```

帧边界公式：
```
某场景开始帧 = round(该场景前累计秒数 / 音频总秒数 × 实际渲染总帧数)
```

### 2. FFmpeg atempo 无损加速

配音语速约 120–150 字/分钟，而视频时长通常控制在 3–4 分钟。通过 atempo 两级级联加速：

```bash
# 示例：原始 360s → 目标 210s，加速比 1.714
# sqrt(1.714) ≈ 1.31，两级相乘 = 1.31 × 1.31 = 1.716
ffmpeg -i combined_raw.mp3 \
  -filter:a "atempo=1.31,atempo=1.31" \
  -codec:a aac -b:a 128k combined_final.m4a
```

### 3. 场景组件化设计

每个视频场景对应一个 React 组件，基于 `useCurrentFrame()` 判断当前帧，自动切换场景：

```tsx
const F = [0, 266, 1096, 1780, 2730, 3545, 4093, 4610, 5215, 5715, 6130];

export const Scene: React.FC = () => {
  const f = useCurrentFrame();
  if (f < F[1])  return <CoverScene p={prog(f, 0, 40)} />;
  if (f < F[2])  return <Chapter1Scene p={prog(f, F[1], 40)} />;
  // ...更多场景
  return <EndScene p={prog(f, F[F.length-1], 40)} />;
};
```

---

## 快速上手

### 安装

```bash
# 安装 skill
skillhub install doc-to-video

# 确认依赖
pip3 install edge-tts
brew install ffmpeg        # macOS
# apt install ffmpeg       # Ubuntu/Debian
```

### Step 1：编写配音脚本

复制 `generate_audio.py`，填入旁白文本：

```python
SCENES = [
    ("00_title",    "欢迎观看本教程..."),
    ("01_chapter1", "第一章，介绍背景知识..."),
    ("02_chapter2", "第二章，讲解核心概念..."),
]

VOICE = "zh-CN-XiaoxiaoNeural"  # 女声，自然流畅

# 运行
python3 generate_audio.py
```

### Step 2：拼接 + 加速音频

```bash
# 生成文件列表
cat > audio/file_list.txt << 'EOF'
file 'audio/00_title.m4a'
file 'audio/01_chapter1.m4a'
file 'audio/02_chapter2.m4a'
EOF

# 拼接
ffmpeg -y -f concat -safe 0 -i audio/file_list.txt \
  -codec:a libmp3lame -qscale:a 2 audio/combined_raw.mp3

# 加速（目标 210s / 原始秒数 = 加速比）
ffmpeg -y -i audio/combined_raw.mp3 \
  -filter:a "atempo=1.31,atempo=1.31" \
  -codec:a aac -b:a 128k audio/combined_final.m4a
```

### Step 3：渲染视频

```bash
cd /path/to/workspace

# 首次渲染：确认实际帧数
./node_modules/.bin/remotion render \
  my-project/src/index.tsx MyVideo out/temp.mp4

# ffprobe 确认帧数（关键步骤！）
ffprobe -v error -select_streams v:0 \
  -show_entries stream=nb_frames -of csv=p=0 out/temp.mp4
# → 假设输出 6295，用此值更新帧边界

# 用精确帧数重新渲染
./node_modules/.bin/remotion render \
  my-project/src/index.tsx MyVideo out/final_video.mp4
```

### Step 4：合并音视频

```bash
# 去原音 + 嵌入配音
ffmpeg -y -i out/final_video.mp4 -an -c:v copy /tmp/noaudio.mp4
ffmpeg -y -i /tmp/noaudio.mp4 -i audio/combined_final.m4a \
  -c:v copy -c:a aac -b:a 128k -shortest \
  out/final_with_audio.mp4

# 验证同步
ffprobe -v error -show_streams out/final_with_audio.mp4 \
  | grep -E "codec_type|duration"
```

---

## 视觉组件设计规范

| 组件 | 用途 | 关键样式 |
|------|------|---------|
| `CodeBlock` | 代码展示 | `#0d1117` 背景，`#79c0ff` 文字，等宽字体 |
| `StepItem` | 步骤流程 | 彩色编号圆圈 + 文字 |
| `ProblemCard` | 问题排查 | 红色标题，原因+解决布局 |
| `BulletItem` | 要点列表 | 图标 + 内容 |
| `Tag` | 章节标签 | 圆角胶囊，投影光晕效果 |

**动画原则：**
```tsx
function ease(t: number) { return t * t; }  // easeIn 曲线

// 渐入 + 上浮动画
<div style={{
  opacity: ease(p),                               // 0→1
  transform: `translateY(${(1-ease(p))*30}px)`,   // 下→上
}}>
```

---

## 参数参考

| 参数 | 推荐值 | 说明 |
|------|--------|------|
| 帧率 | 30 fps | 标准视频帧率 |
| 分辨率 | 1920×1080 | 16:9 全高清 |
| 目标时长 | 180–210 秒 | 3–3.5分钟，适合观看 |
| 加速比 | 1.3–2.0× | 过大影响音质 |
| atempo 级联 | 两级相乘≈目标加速比 | 每级不超过 2.0 |
| 每段旁白 | 100–300 字 | 对应场景内容 |
| 动画时长 | 30–40 帧 | ~1–1.3秒 |
| 音频码率 | 128k AAC | 清晰度与体积平衡 |
| 推荐 voice | zh-CN-XiaoxiaoNeural | 女声，自然流畅 |

---

## 适用场景

- **技术博客视频化**：把写的文章转成视频，扩大传播渠道
- **项目文档演示**：给 README、架构文档配上旁白，方便分享
- **课程制作**：把讲稿自动化生成视频初稿，减少后期剪辑
- **Bug 复盘**：把事故分析文档做成视频，方便团队回顾
- **API 文档演示**：Swagger/OpenAPI 文档 → 操作演示视频

---

## 常见问题

**Q：音频比视频快/慢？**
A：这是最常见问题。原因是帧边界基于估算帧数。解决方法：先渲染一次 → ffprobe 确认实际帧数 → 用实际帧数重新计算帧边界 → 更新代码 → 重渲染。

**Q：FFmpeg 合并后音频只有几 KB？**
A：原视频有静音音频轨道，`-shortest` 保留了原轨道。必须先用 `-an` 去掉原音再合并。

**Q：atempo 加速后人声变调？**
A：单级 atempo 超过 2.0 会变调。用两级级联，例如 3.5x：`atempo=1.87,atempo=1.87`。

**Q：edge-tts 无网络？**
A：macOS 可用系统语音：`say -v Tingting -r 175 "旁白内容"`，然后 `ffmpeg -i audio.aiff audio.mp3`。

---

## 项目结构

```
skill-doc-to-video/
├── SKILL.md              ← 完整使用文档
├── generate_audio.py     ← 配音生成脚本模板
```

---

让 AI Agent 自动把技术文档变成带配音旁白的 1080p 视频，零门槛，10 分钟搞定。

doc-to-video：将 Markdown 一键变成专业视频

人工智能

doc-to-video 是一款 AI 自动化工具，可将 Markdown 技术文档快速转换为带自然人声配音的 1080p 视频。支持全流程自动化，包括内容解析、语音生成、视觉渲染和音视频合成，大幅提升技术内容视频化效率，适用于教程、文档演示及在线课程制作。

TypeScript

AI Agent

Docker

Python

Ubuntu

Debian

Agent

2026采购季 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

doc-to-video：将 Markdown 一键变成专业视频-腾讯云开发者社区-腾讯云

doc-to-video：将 Markdown 一键变成专业视频

doc-to-video：将 Markdown 一键变成专业视频

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐