---
name: "auto-video-generator"
description: "智能自动化视频生成。上传此Skill后，首次使用时会自动检测并引导安装所需软件（Playwright、FFmpeg、Edge TTS）。支持PRD文档、原型页面或文字描述作为输入，自动生成带自然语音解说的演示视频。核心能力：Edge TTS神经语音（抖音同款）、场景化音画严格同步、Vue组件交互录制、内部滚动容器支持、声音克隆可选。"
---

# Auto Video Generator | 自动化视频生成器 v2

## 🚀 快速开始（3步）

### 第1步：上传 Skill
1. 下载 `auto-video-generator.zip`
2. 打开 Trae → 设置 → 规则和技能 → + 创建
3. 拖拽上传 zip 包 → 选择"全局" → 确认

### 第2步：首次使用自动引导
首次说"生成演示视频"时，AI 会自动检测并提示：
```
🔍 检测到需要安装以下软件：
   1. Playwright（浏览器自动化）
   2. FFmpeg（视频处理）
   3. Edge TTS（自然语音合成）

💡 点击"一键安装"或手动安装：
   [一键安装] [查看教程]
```

### 第3步：开始使用
安装完成后，直接说：
- "生成演示视频"
- "帮我制作产品教程"
- "录制原型演示"
- "用我的声音生成视频"

---

## 📋 前置依赖说明

本 Skill 需要以下软件支持：

| 软件 | 用途 | 自动安装 | 手动安装 |
|------|------|---------|---------|
| **Node.js** | 运行环境 | ❌ 需预先安装 | [下载](https://nodejs.org/) |
| **Playwright** | 浏览器录屏/逐帧截图 | ✅ 自动 | `pip install playwright` |
| **FFmpeg** | 视频合并/音频同步 | ✅ 自动 | `winget install FFmpeg` |
| **edge-tts** | Edge神经语音（推荐） | ✅ 自动 | `pip install edge-tts` |
| **Windows SAPI** | 备用语音引擎 | ✅ 已内置 | 无需安装 |

### 一键安装脚本（按系统选择）

#### Windows 用户
**双击运行**：`安装依赖.bat`

#### macOS / Linux 用户
```bash
chmod +x install-mac.sh && ./install-mac.sh
# 或
chmod +x install-linux.sh && ./install-linux.sh
```

### 手动安装（如果自动脚本失败）

**Windows**：
```bash
pip install playwright edge-tts
npx playwright install chromium
winget install --id=Gyan.FFmpeg -e
```

**macOS**：
```bash
pip install playwright edge-tts
npx playwright install chromium
brew install ffmpeg
```

---

## 🎤 语音方案（核心改进）

### 方案对比

| 方案 | 自然度 | 成本 | 特点 | 推荐场景 |
|------|--------|------|------|---------|
| **Edge TTS 神经语音** | ⭐⭐⭐⭐⭐ | 免费 | 微软Edge同款，抖音常用 | **默认首选** |
| Windows SAPI | ⭐⭐ | 免费 | 内置，机械感强 | 备用方案 |
| Fish Audio | ⭐⭐⭐⭐⭐ | 免费/付费 | 支持声音克隆 | 想用自己的声音 |
| CosyVoice | ⭐⭐⭐⭐⭐ | 开源免费 | 阿里开源，情感表达强 | 本地部署 |

### Edge TTS 语音选择指南

**中文女声（推荐）**：
| 语音ID | 名称 | 风格 |
|--------|------|------|
| `zh-CN-XiaoxiaoNeural` | 晓晓 | 年轻女性，活泼自然（**默认**） |
| `zh-CN-XiaoyiNeural` | 晓伊 | 温柔知性 |
| `zh-CN-XiaomengNeural` | 晓梦 | 新闻播报风格 |

**中文男声**：
| 语音ID | 名称 | 风格 |
|--------|------|------|
| `zh-CN-YunxiNeural` | 云希 | 年轻男性，自然亲切 |
| `zh-CN-YunjianNeural` | 云健 | 成熟稳重 |

**使用方式**：
```python
import edge_tts
communicate = edge_tts.Communicate('你的文案', 'zh-CN-XiaoxiaoNeural', rate='-5%')
await communicate.save('output.mp3')
```

### 声音克隆（使用自己的声音）

**Fish Audio 流程**：
1. 注册 [fish.audio](https://fish.audio) 获取 API Key
2. 上传一段你的录音（10秒以上）
3. 获取声音模型 ID
4. 在脚本中指定你的声音：
```python
communicate = edge_tts.Communicate(text, voice='your-voice-model-id')
```

**GPT-SoVITS（本地开源）**：
1. 克隆仓库：`git clone https://github.com/RVC-Boss/GPT-SoVITS`
2. 录制参考音频（3~10秒）
3. 微调模型后导出为 ONNX
4. 通过 API 调用生成语音

---

## 🎬 音画同步技术方案（核心机制）

### 问题背景
传统视频生成常见问题：
- ❌ 视频画面不随讲解变化（一直显示同一页）
- ❌ 讲趋势图时画面已经滚到五峰图
- ❌ 语音和视频时长不匹配

### 解决方案：场景化录制 + 时长匹配

```
┌─────────────────────────────────────────────┐
│           视频生成流程 (v2)                  │
│                                             │
│  Step 1: 定义场景列表                        │
│    ├── 场景1: {name, text, action}          │
│    ├── 场景2: {name, text, action}          │
│    └── ...                                  │
│         ↓                                   │
│  Step 2: 按场景生成语音 + 获取每段时长        │
│    ├── 场景1语音: 27.2s                     │
│    ├── 场景2语音: 14.8s                     │
│    └── ...                                  │
│         ↓                                   │
│  Step 3: 按时长逐帧录制视频                   │
│    ├── 执行场景1 action → 截图27.2s×FPS帧   │
│    ├── 执行场景2 action → 截图14.8s×FPS帧   │
│    └── ...                                  │
│         ↓                                   │
│  Step 4: FFmpeg合并 ( -shortest )          │
│    输出: 音画完美同步的视频                    │
└─────────────────────────────────────────────┘
```

### 核心代码模式

```python
SCENES = [
    {
        "name": "开场-KPI卡片",
        "text": "这段语音只描述当前画面可见的内容...",
        "action": "scroll_top",       # 页面操作指令
    },
    {
        "name": "下钻到车队",
        "text": "点击第一客运公司进行下钻...",
        "action": "drill_fleet",      # Vue交互操作
    },
]

async def generate_scene_audios():
    scene_durations = []
    for idx, scene in enumerate(SCENES):
        # Edge TTS 生成语音
        communicate = edge_tts.Communicate(scene['text'], VOICE)
        await communicate.save(f'narration_{idx}.mp3')
        # ffprobe 获取精确时长
        duration = get_audio_duration(f'narration_{idx}.mp3')
        scene_durations.append(duration)

async def capture_frames(scene_durations):
    for idx, scene in enumerate(SCENES):
        dur = scene_durations[idx]
        # 先执行页面操作（滚动/点击/下钻等）
        await run_action(page, scene["action"])
        # 再按语音时长截图（确保画面与语音匹配）
        await save_frames(dur)
```

### 关键原则

1. **每段语音只描述当前画面可见内容** —— 不做跨场景描述
2. **先执行操作，再开始截图** —— 确保画面已更新
3. **使用 `-shortest` 参数合并** —— 以较短者为基准裁剪

---

## 🔧 Vue 组件交互录制

### 直接调用 Vue 实例方法

对于 Vue 单页应用，通过 JavaScript 直接调用实例方法触发交互：

```javascript
// 下钻到车队
await page.evaluate(() => {
    const el = document.querySelector('.route-efficiency-v2-container');
    const vm = el.__vue__;
    vm.drillDownToFleet(vm.companyData[0]);
})

// 切换Tab
await page.evaluate(() => {
    document.querySelector('.route-efficiency-v2-container').__vue__
        .routeAnalysisActiveTab = 'threeLow';
})

// 展开面板
await page.evaluate(() => {
    document.querySelector('.route-efficiency-v2-container').__vue__
        .matrixExpanded = true;
})
```

### 内部滚动容器处理

很多现代 Web 应用使用内部滚动容器而非 `window.scrollTo`：

```python
# 错误：window.scrollTo 不起作用
await page.scroll_to(1000)

# 正确：控制内部滚动容器的 scrollTop
async def scroll_wrapper(page, target_y):
    await page.evaluate(f'''() => {{
        const wrapper = document.querySelector('.content-scroll-wrapper');
        if (wrapper) wrapper.scrollTop = {target_y};
    }}''')

# 或者滚动到特定元素
async def scroll_to_element(page, selector, offset=-60):
    await page.evaluate(f'''() => {{
        const el = document.querySelector('{selector}');
        const wrapper = document.querySelector('.content-scroll-wrapper');
        if (el && wrapper) wrapper.scrollTop = el.offsetTop + {offset};
    }}''')
```

---

## 💡 使用示例

### 示例1：基于 PRD + 原型（推荐）

**场景**：你有 PRD 文档和 HTML 原型

**操作**：
1. 确保目录中有：
   - `xxx_PRD.md` 文档
   - `prototype/xxx.html` 原型文件

2. 对 AI 说：
   ```
   帮我生成演示视频，使用Edge TTS晓晓语音
   ```

3. AI 自动：
   - 读取 PRD 提取功能点
   - 设计场景化脚本（每个场景对应一个画面状态）
   - 按 Edge TTS 生成自然语音并获取时长
   - Playwright 逐帧录制（每个场景按语音时长截图）
   - FFmpeg 合成音画同步视频

### 示例2：仅基于原型

**场景**：只有 HTML 原型，没有 PRD

**操作**：
```
用户：录制这个页面 demo.html，用晓晓的声音
AI：好的，我将探测页面功能，使用Edge TTS生成自然语音...
```

### 示例3：基于文字描述

**场景**：只有文字描述，没有原型

**操作**：
```
用户：生成一个电商下单流程的演示视频，用云希男声
AI：好的，我将基于您的描述创建演示视频...
```

### 示例4：使用自己的声音

**操作**：
```
用户：用我的声音生成这个页面的演示视频
AI：好的，请提供一段您的录音文件（10秒以上），我将使用声音克隆技术...
```

---

## 🔧 故障排除

### 问题1：提示"找不到 FFmpeg"

**解决**：
```bash
winget install --id=Gyan.FFmpeg -e
```

### 问题2：提示"找不到 edge-tts"

**解决**：
```bash
pip install edge-tts
```

### 问题3：视频画面不变（始终显示同一页）

**原因**：页面使用了内部滚动容器（如 `.content-scroll-wrapper`），`window.scrollTo` 无效。

**解决**：
```python
# 使用内部滚动容器替代 window.scrollTo
await page.evaluate('''() => {
    const w = document.querySelector('.content-scroll-wrapper');
    if (w) w.scrollTop = 1000;
}''')
```

### 问题4：音画不同步（语音讲A时画面显示B）

**原因**：场景设计不合理——一段语音包含多个画面的内容。

**解决**：
- 拆分场景，每段语音只描述当前画面
- 先执行页面操作，再开始截图
- 使用 `ffmpeg -shortest` 合并

### 问题5：Edge TTS 报错网络问题

**原因**：Edge TTS 需要联网调用微软服务。

**解决**：
- 检查网络连接
- 回退到 Windows SAPI 作为备用

---

## 📦 资源检测策略

Skill 会自动检测可用资源，按优先级处理：

```
优先级1: PRD + 原型     → 最完整准确
优先级2: 仅原型         → AI探测功能
优先级3: 仅PRD          → 概念演示
优先级4: 文字描述       → 基于描述生成
```

语音引擎选择策略：
```
优先级1: Edge TTS       → 自然神经语音（默认）
优先级2: Fish Audio     → 声音克隆（用户要求时）
优先级3: Windows SAPI   → 备用离线方案
```

---

## 🎯 技术参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 视频分辨率 | 1440x900 | 可自定义 |
| 视频格式 | MP4 (H.264) | 兼容性最佳 |
| 帧率 | 4 FPS | 平衡质量与速度 |
| 语音引擎 | Edge TTS | zh-CN-XiaoxiaoNeural |
| 语速 | -5% | 稍慢，适合解说 |
| 输出位置 | `video_output/` | 项目目录下 |

---

## 📞 需要帮助？

如果安装遇到问题：
1. 检查依赖：`node --version`, `ffmpeg -version`, `pip show edge-tts`
2. 手动安装：参考上文"手动安装"部分
3. 查看示例脚本：项目中的 `generate_demo_video_v11.py`