ppt-video

name	ppt-video
description	PPT 视频录制子技能。把幻灯片录成视频：Playwright截图、TTS配音(Edge TTS / CosyVoice)、FFmpeg合成、ASS字幕。 支持远程 GPU 加速：CosyVoice 3.0 在 SSH 服务器（4090）上运行，零样本声音克隆。 当用户说"录成视频"、"加配音"、"加字幕"、"截图每一页"、"音画不同步"、"TTS不同步"、 "字幕有背景条"、"FFmpeg命令"、"视频太短"、"导出mp4"时触发。 触发词: 视频, 录制, 录成视频, 配音, TTS, 字幕, 截图, 音画不同步, 不同步, FFmpeg, mp4, screenshot, capture, dubbing, subtitle, video, render.

ppt-video — 视频录制

Audio-First pipeline：TTS 音频驱动视频时长。永远不要用固定每页时长生成视频。

---

决策树

用户需求
  ├─ 只截图       → scripts/capture.py
  ├─ 只配音       → scripts/tts.py --engine edge|cosyvoice
  ├─ 声音克隆     → scripts/tts.py --engine cosyvoice --ref-audio xxx.wav
  ├─ 一键出视频    → scripts/render.py（Audio-First 完整流程）
  ├─ 了解技术细节  → video.md
  └─ 修字幕样式    → video.md § ASS 字幕参数速查

---

Audio-First 流程（核心，内联）

实测教训：固定 4s/页 × 9 页 = 28s 视频，但 TTS 音频 61.7s。音画严重不同步。 正确做法：音频时长驱动每页停留时间。

Step 1: TTS 配音 → Edge TTS (本地/快速) 或 CosyVoice (远程GPU/高质量) → .mp3/.wav
         ffprobe 读每段实际时长
Step 2: 每页停留 = 音频时长 + 1s 缓冲，计算 xfade offset
Step 3: Playwright 截图 → 1920×1080 PNG
Step 4: 生成 ASS 字幕 → 时间轴基于音频 offset（非固定间隔）
Step 5: FFmpeg xfade + ass 字幕烧录 → video_only.mp4
Step 6: FFmpeg 合并音频 + 视频 → final.mp4

方式	视频时长	音频时长	结果
固定 4s/页	28s	61.7s	❌ 严重不同步
Audio-First	62.7s	61.7s	✅ 同步

---

脚本速查

capture.py — Playwright 截图

python3 scripts/capture.py --url http://localhost:8080/slides.html --output-dir ./frames
# 输出: frames/slide_00.png, slide_01.png, ... (1920×1080)
# 自动隐藏 .record-panel

tts.py — TTS 批量配音（Edge TTS / CosyVoice）

# JSON 内联
python3 scripts/tts.py --voice zh-CN-YunxiNeural --texts '["旁白1", "旁白2"]' --output-dir ./voiceover

# 从文件读取
python3 scripts/tts.py --texts @narrations.json --output-dir ./voiceover

# 输出: voiceover/slide_00.mp3, slide_01.mp3, ..., full_audio.mp3

CosyVoice 模式（远程 GPU，高质量）

# CosyVoice 3.0 — 远程 RTX 4090，高质量中文 TTS
python3 scripts/tts.py --engine cosyvoice --texts '["旁白1", "旁白2"]' --output-dir ./voiceover

# 零样本声音克隆 — 提供参考音频即可复制声音
python3 scripts/tts.py --engine cosyvoice --ref-audio /path/to/ref.wav \
  --ref-text "参考音频的文本" --texts '["要合成的文本"]' --output-dir ./voiceover

# 指定 SSH 主机（默认 4090）
python3 scripts/tts.py --engine cosyvoice --host 4090 --texts @narrations.json --output-dir ./voiceover

TTS 引擎	质量	速度	需要 GPU	声音克隆	适用场景
Edge TTS	★★★	极快	否	否	快速预览、无 GPU
CosyVoice 3.0	★★★★★	RTF 0.7	RTX 4090	✅ 零样本	最终输出、高质量配音

CosyVoice 依赖：SSH 可达的 GPU 服务器（配置见 ~/.ssh/config Host 4090）， 服务器上已装好 /opt/cosyvoice venv + 模型。 无 GPU 时自动降级为 Edge TTS。

注意：Edge TTS 输出用 --write-media（不是 -w），-w 在某些版本不生效。

render.py — Audio-First 一键出视频

python3 scripts/render.py --dir ./my-presentation
# 输入: frames/ + voiceover/
# 输出: subtitle_synced.ass + presentation_synced.mp4 + final.mp4

# 自定义参数
python3 scripts/render.py --dir ./my-ppt --fade 0.8 --buffer 1.2

---

依赖安装

pip install playwright edge-tts    # Edge TTS (本地)
# CosyVoice: 需要 SSH 可达的 GPU 服务器，详见 video.md § CosyVoice
python -m playwright install chromium
brew install ffmpeg    # macOS

---

ASS 字幕参数速查（内联）

Style: Sub,PingFang SC,26,&H00FFFFFF,&H000000FF,&H80000000,&H00000000,-1,0,0,0,100,100,0,0,1,3,1,2,120,120,90,1

参数	值	含义
BorderStyle	1	描边（不要用 3 = 背景框）
Outline	3	描边粗细 px
Shadow	1	微阴影
Alignment	2	底部居中
MarginV	90	距底部 90px（避开进度条）
BackColour	&H00000000	完全透明背景
PrimaryColour	&H00FFFFFF	白色文字

常见错误：BorderStyle=3 产生背景色块。用户说"字幕为啥要带背景条" → 必须用 BorderStyle=1。

---

文档索引

文件	内容
video.md	完整参考：浏览器 TTS, Edge TTS, CosyVoice 3.0, ASS 字幕, Audio-First 完整脚本, 浏览器兼容性
scripts/capture.py	Playwright 截图（argparse, 1920×1080, 自动隐藏 record-panel）
scripts/tts.py	Edge TTS / CosyVoice 批量生成 + 拼接音频（argparse, --engine edge
scripts/render.py	Audio-First 核心：音频驱动时长 + ASS 字幕 + xfade + 合并（argparse）