pptx-to-video

通过 Codex Skill 编排资料搜索、视频脚本、逐镜配音和视觉检查，再由 Python、Kokoro-82M 与 Remotion 确定性生成 MP4 和 SRT。

新视频默认直接使用 html-video-spec-v1，不经过 PPT；同时保留 PPTX 转视频兼容路径。

工作流程

资料搜索 → 内容类型路由 → 逐镜叙事板 → 动画库评估 → Video Spec → 首镜样片确认 → 逐镜 TTS
→ Scene IR → 浏览器与视觉检查 → Remotion → MP4 + SRT

• Codex Skill 负责搜索、脚本设计、分镜规划、视觉判断和失败修复。
• 项目运行时负责配音、时间轴编译、确定性检查、字幕和视频渲染。
• 多模态模型不是生成视频的必需条件，仅用于自动审核 contact sheet；没有多模态能力时可人工检查。

安装

需要 Node.js 20+。安装器会按 pyenv → uv → conda → venv 选择并优先复用可用的隔离环境；需要新建环境时默认使用 Python 3.11，TTS 默认使用 Kokoro-82M。初始化时通过锁文件一次性安装 Remotion、GSAP、Motion、Anime.js、D3、Three.js/R3F、PixiJS、Lottie、Rough.js 和 Matter.js，生产阶段不再临时安装动画库。

安装分发包

codex_skill_dir="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$codex_skill_dir"
unzip pptx-to-video.skill.zip -d "$codex_skill_dir"
cd "$codex_skill_dir/pptx-to-video"
bash scripts/setup.sh

也可以克隆仓库后在仓库根目录直接执行：

bash scripts/setup.sh

常用安装选项：

# 仅检查平台、加速设备和环境管理器，不安装
bash scripts/setup.sh --check --skip-tts

# 不安装 TTS，仅使用已有音频或执行画面渲染
bash scripts/setup.sh --skip-tts

# 安装 TTS，但暂不下载默认模型
bash scripts/setup.sh --skip-model

# 显式选择环境管理器
bash scripts/setup.sh --manager uv

安装器自动检测 NVIDIA CUDA、Apple MPS 或 CPU，并安装对应 PyTorch 依赖。Kokoro 不需要 LLVM 22；若在 Intel macOS 上自行安装 qwen-tts，仍需要先执行：

sudo port install llvm-22

安装完成后，实际 Python 路径记录在 .skill-python，默认模型路径记录在 .skill-model。

搜索工具

搜索能力不内置在分发包中，需要在 Codex 环境中单独配置。推荐顺序：

1. open-websearch：优先用于实时搜索、公开页面抓取和资料来源核验。
2. SearXNG：适合自托管、隐私敏感环境，或作为 open-websearch 的备用搜索源。

建议将“搜索”和“资料聚合”交给不同子 Agent，最终脚本保留权威来源 URL。搜索不可用时也能手工提供资料或直接编写 Video Spec。

通过 Codex Skill 使用

将需求直接交给安装了本 Skill 的 Codex，例如：

使用 $pptx-to-video，搜索可靠资料并生成《什么是 TCP 滑动窗口》的视频，
1920×1080，60 秒。先给我确认首镜风格，再配音和批量渲染。

Codex 会执行 Skill 中定义的阶段流程，并在 Skill 目录内调用项目命令。

生成首镜前，Codex 会先将主题路由为热点事件、原理科普、数据比较或操作安全，再加载对应的叙事与验收约束。动画库服务于语义目标，不追求覆盖数量；新闻突出角色、证据和边界，硬核科普突出实体、状态变化和因果链。TTS 保持自然语速，逐镜尾部只留 0.2–0.6 秒，长镜头每 3.5 秒内必须出现一次有信息增量的视觉节拍。

画面文字默认遵循 Video Spec 的 language。中文视频的标题、动作、结论和说明优先使用中文，只保留协议缩写、API、命令、配置值、指标与产品名等必要技术名称。

直接使用 CLI

已有 html-video-spec-v1 文件时，可以脱离 Codex 的创作编排，直接执行运行时：

runtime_python="$(cat .skill-python)"

# 生成首镜风格样片
"$runtime_python" make_video.py video-spec.json --stage styleframe

# 使用默认 Kokoro-82M / zf_xiaoyi 逐镜配音并冻结时长
"$runtime_python" make_video.py video-spec.json --stage voice

# 编译 Scene IR 和字幕
"$runtime_python" make_video.py video-spec.json --stage compile

# 检查首镜，再检查全片
"$runtime_python" make_video.py video-spec.json --stage check --scene-id 01-intro
"$runtime_python" make_video.py video-spec.json --stage check

# 渲染 MP4
"$runtime_python" make_video.py video-spec.json --stage render --output out/video.mp4

覆盖 TTS 设备或模型路径：

KOKORO_TTS_DEVICE=cpu "$runtime_python" make_video.py video-spec.json --stage voice
"$runtime_python" make_video.py video-spec.json --stage voice --model-path /path/to/model

KOKORO_TTS_DEVICE 支持 auto、cuda、mps、cpu，默认值为 auto。默认输出为 24kHz 双声道 WAV。

PPTX 兼容模式

"$runtime_python" make_video.py input.pptx --output out/presentation.mp4

PPTX 路径适合基础页面还原，不扩展 D3、Three.js、Canvas 等高级动画。新视频建议使用 Video Spec。

输出与检查

• out/*.mp4：最终视频。
• out/*.srt：逐镜时间轴字幕。
• out/*.styleframe.png：首镜风格样片。
• checks/<spec>/contact-sheet.png：全片视觉联系表。
• checks/<spec>/report.json：浏览器与确定性检查结果。

out/、audio/、checks/、本地虚拟环境和模型路径均被 Git 忽略。

构建分发包

python3 scripts/package_skill.py

输出文件为 dist/pptx-to-video.skill.zip，包含 Skill 元数据、Python 运行时、Remotion 工程、依赖清单和安装脚本，不包含音频、视频、模型或本机环境。