AIPPT：PPT 有声课件与视频笔记工作流

把静态 PPT 自动变成带讲解、带配音的"有声课件"，也能反向把视频整理成结构化笔记或 PPT 草稿。整套链路基于 Qwen2.5（讲稿生成）、CosyVoice2（语音合成）、Whisper / FunASR（语音识别）与 Gradio（交互界面），并针对 Intel XPU 做了完整的设备迁移适配。

这个技能解决什么问题

制作者不必逐页手写讲稿，也不必自己录音配音
课程录屏、汇报视频可以反向整理成笔记或课件
同一份业务代码能在 CUDA → XPU → CPU 之间平滑切换，方便端侧部署

何时触发

只要用户的需求落在下面任意一条，就加载本技能：

上传 / 给定 PPTX，想要讲解词、配音、带音频的 PPT 或视频课件
上传 / 给定视频，想要笔记、摘要或 PPT
想把某段音频 / 视频里的人声换成另一个音色
需要在本机或云端把上面这些能力跑起来（环境安装、启动、排障）
在 Intel XPU 或魔搭创空间上部署这套多模态应用时遇到报错

快速开始

第 0 步：先做环境自检（必做）

不要凭猜测判断环境是否就绪，先跑自检脚本，它会一次性报告 Python 版本、推理设备、关键依赖和模型目录状态：

python scripts/check_env.py

如果用户还没装依赖，按 references/runtime.md 里对应平台（XPU 本地 / CUDA / 魔搭创空间）的步骤安装，再回到这里继续。

第 1 步：启动应用

# Intel XPU 本地（推荐，自动建环境 + 装依赖 + 启动）
run_xpu.cmd

# CUDA / 通用环境
run_cuda.cmd

# 或手动
python app.py

启动后 Gradio 监听 0.0.0.0:7860，界面包含两个主标签页：

| 标签页 | 用途 | |--------|------| | PPT-->有声课件(视频) | PPT 配音主链路，内含「示例音频/上传音频」「录制音频」「PPTX 文件」「音频音色替换」「视频音色替换」 | | 视频转笔记(PPT) | 视频 → ASR → 结构化笔记 / PPT |

第 2 步：判断用户要的是哪条链路

输入是 .pptx → 走 工作流 A
输入是视频，要笔记 → 走 工作流 B
输入是音频/视频，要换音色 → 走 工作流 C
要部署、要迁移到 XPU、部署报错 → 走 工作流 D

工作流 A：PPT → 讲解词 → 配音 → 有声课件

界面路径：PPT-->有声课件(视频) → PPTX文件。

上传 PPTX 文件（仅支持 .pptx）
点「生成每张PPT的文字」：
- 逐页提取文本框、表格内容
- 若该页已有备注，直接采用备注作为讲稿；没有备注才调用大模型生成
在「内容预览编辑区」人工校对讲稿（这一步别跳过，讲稿质量决定成品质量）
点「为每张PPT配音」：合成每页语音，并输出
- 带配音的PPT文件
- 带演讲稿的Word文档
需要视频形态时，继续走课件视频导出

讲稿生成使用 prompt.py 中的 PPTMAKER 提示词。它要求模型只输出讲解内容，且只能使用 ，。？！ 四种标点，并按语境插入 CosyVoice2 的情感指令：

<strong>词</strong>：强调某个词
<laughter>词</laughter>：笑着说出某个词
[breath] [laughter] [cough] [sigh] [lipsmack] [mn] 等 15 种非包裹型指令，直接插在对应位置

这 15 种指令是 CosyVoice2 的硬约束。让模型自由发挥会生成无效标签，导致合成报错或读出字面文本。

不想开界面时：用脚本完成前半段

讲稿与备注的读写可以完全脱离 Gradio 用脚本做，适合批处理和自动化：

# 提取每页文字与备注 -> slides.json + slides.md
python scripts/extract_pptx.py input.pptx -o work/

# 把校订好的讲稿写回备注页 -> 带备注的 pptx
python scripts/apply_notes.py input.pptx --notes work/slides.json -o output_带备注.pptx

配音与打包环节依赖模型权重，需要 python app.py 启动的服务或直接调用 app.py 内的 run_tts()。

工作流 B：视频 → 笔记 / PPT

界面路径：视频转笔记(PPT)。

上传视频文件
调用 ASR（Whisper）提取语音并按时间轴分段
按 prompt.py 的 BASE_PROMPT 生成结构化笔记，产出：
- 转换后的笔记内容（Markdown 文本）
- 生成的PPT文件

笔记生成的硬性约定（来自 BASE_PROMPT）：

笔记必须用中文，专有名词 / 技术术语 / 品牌名保留英文
只返回 Markdown 正文，不要包在代码块里
编号标题不要写成有序列表：用 1\. **内容** 或 ## 1. 内容，避免渲染错乱
数学公式保留 LaTeX
可选增强：每个 ## 标题后追加 *Content-[mm:ss] 时间锚点；视觉演示、代码演示处插入 *Screenshot-[mm:ss] 截图占位；结尾追加中文 AI 摘要（AI_SUM）

工作流 C：音色替换

界面路径：PPT-->有声课件(视频) → 音频音色替换 / 视频音色替换。

音频音色替换：给一段音频 + 一段目标音色参考音频，重合成目标音色
视频音色替换：抽取视频音轨 → 变声 → 回写，保持画面不变

底层是 CosyVoice2 的 zero-shot 推理（run_tts()），用「参考音频 + 参考文本」做音色克隆。参考音频建议 5–15 秒、干净无背景音乐，效果最稳。

工作流 D：Intel XPU 迁移与云端部署

本项目在 XPU 上的适配遵循四步：检测 → 迁移 → 同步 → 释放。

device = torch.device(
    "cuda" if torch.cuda.is_available()
    else "xpu" if torch.xpu.is_available()
    else "cpu"
)

model = model.half().to("xpu")

if torch.xpu.is_available():
    torch.xpu.synchronize()
    torch.xpu.empty_cache()

这套模式已在 Qwen2.5、CosyVoice2、Whisper/FunASR 三条链路上验证可用。

部署前先跑：

python scripts/check_env.py            # 设备与依赖自检
python scripts/prepare_modelscope_requirements.py   # 生成云端稳健版 requirements

云端具体安装命令、依赖版本矩阵和报错处理见 references/runtime.md 与 references/troubleshooting.md。

脚本清单

所有脚本均为标准库优先、路径无关，可在任意目录调用。

| 脚本 | 作用 | 用法 | |------|------|------| | scripts/check_env.py | 环境自检：Python 版本、torch/xpu/cuda 可用性、关键依赖、模型目录、外部工具 | python scripts/check_env.py | | scripts/extract_pptx.py | 提取 PPTX 每页文字与备注，输出 JSON + Markdown | python scripts/extract_pptx.py deck.pptx -o work/ | | scripts/apply_notes.py | 把讲稿写回 PPTX 备注页 | python scripts/apply_notes.py deck.pptx --notes work/slides.json -o out.pptx | | scripts/prepare_modelscope_requirements.py | 生成带重试/超时/优先 wheel 的云端 requirements | python scripts/prepare_modelscope_requirements.py | | scripts/publish_skill.py | 打包、发布到魔搭 Skills 中心、同步到本地 skills 目录 | python scripts/publish_skill.py build / publish / sync |

参考文档

按需读取，不要一次性全部加载：

references/runtime.md — 三种运行环境（XPU / CUDA / 魔搭创空间）的安装步骤与依赖版本矩阵
references/pipeline.md — 四条链路的实现细节、模型清单、关键参数与提示词约定
references/troubleshooting.md — 部署与运行报错排查表
references/examples.md — 典型用户请求与期望的执行路径

常见问题速查

| 现象 | 首要怀疑 | 处理 | |------|----------|------| | ModuleNotFoundError: pkg_resources | setuptools 缺失 | 固定 setuptools==69.5.1 + wheel>=0.43.0 | | ReadTimeoutError | 云端网络不稳 | --retries 10 --timeout 180 --prefer-binary，切镜像源 | | 镜像 HTTP 403 | 镜像源限流 | 换阿里源，保留 torch 的 extra-index-url | | PPT 转图片失败 | LibreOffice / poppler 缺失 | 安装 libreoffice 与 poppler-utils | | 配音读出方括号内容 | 讲稿含非法情感指令 | 只允许 prompt.py 中定义的 15 种指令 | | SKILLS_ERROR: No valid skills found | zip 层级错误 | 重打包，保证 zip 根目录直接含 SKILL.md |

详细排查见 references/troubleshooting.md。