pptx2video

将编辑后的 PPTX 转换为视频

这是一个独立的通用型 PowerPoint 转视频软件包。它在运行时不依赖 paper2video、ResearchStudio-Reel 或 ppt-master，完整的 CLI 和渲染器都包含在可安装的 pptx2video Python 软件包中。它不局限于研究论文或先前生成的 video.pptx。可使用任何本地 PPTX 作为视觉素材。为确保旁白内容和标记时间精准，优先使用规范的作者备注。若没有规范的备注，则从形状替代文本中读取相同的区块语法。切勿重复使用已渲染的捆绑包产物。仅当完整的合成标识完全匹配时，才可安全地重复使用未经更改的区块级 TTS 缓存条目。

入口点

将 /pptx2video <input.pptx> 视为对此技能的直接调用。常规渲染均使用已安装的公共 CLI：

pptx2video render <input.pptx> <new-output-directory> --resolution 1080p

添加 --animation-pointer cursor|laser 可跟随原生动画目标；它独立于 Spotlight，默认值为 none。

不要导入或执行 Paper2Video 或 ResearchStudio 的私有脚本。如果 CLI 不可用，请先从公共仓库安装运行时，再继续：

python -m pip install \
  'pptx2video[svg] @ git+https://github.com/ai-nuts/pptx2video.git'
python -m playwright install chromium
pptx2video doctor --svg

编写约定

如需精确控制，请编写一个 Notes 块，其句柄与顶层形状或组匹配：

## [latency-card] latency-card
A new latency card appears. [[Spotlight] It reports lower latency.]

Alt Text 使用相同的单块语法，包括开头的两个 # 字符。] 后的语义文本是可选的，不会被朗读：

## [latency-card] latency-card
A new latency card appears. [[Spotlight] It reports lower latency.]

基线哈希、生成顺序来源信息和语义配置文件都存储在 PPTX 形状的 OOXML 中。] 后可见的语义文本是简洁配置文件。PPTX 生成或协议回写也会持久化详细配置文件。冲突显示会读取这些存储值，并为旧版演示文稿使用确定性回退，因此不会调用 LLM。原生效果、目标、触发器和延迟数据保留在 PowerPoint 的 p:timing 树中，不会出现在 Notes 或 Alt Text 中。较旧的 [handle] 加 Script:、[ID] handle 和冗长的 [Paper2Video] 块仍可读取，并会在下次回写时迁移为此统一格式。请保持 Author Notes 内容简洁。有关隐藏来源信息约定，请参阅 references/editable_pptx.md。

稳定句柄可直接解析目标。默认情况下，成功解析的规范 Notes 块会保留当前相对顺序，作为锚点。只有 Notes 中缺失的旁白目标才会根据当前画布几何位置插入这些锚点之间。--narration-order-policy author-notes 选项保留为显式兼容别名，并生成相同的“锚点加插入项”旁白序列。Animation Pane 顺序独立控制原生动画行顺序和局部效果计时。在渲染后的视频中，每个 Pane 阶段都会放在对应旁白块之前，仅用于输出的预留时段中；下一阶段会等待前一块朗读完毕。唯一的规范脚本标记是 Spotlight；其位置决定 Edge 的单词边界时间或时段。旧版进入效果标记仍可读取以供迁移，但绝不会替代、创建或重新排序原生动画。

每个交付的 PPTX 默认会在每张幻灯片上使用便于人工编辑的编号点击组。将每个非 With Previous 的 Pane 行设为其自身顶层 mainSeq 组的 On Click 领头行。让连续的 With Previous 行跟随该领头行，使它们共用画布徽标。PowerPoint 根据此拓扑生成徽标；徽标不是存储的动画 ID。只有在效果目标、预设、持续时间、延迟、Pane 开始和结束时间、行顺序及同时组都保持不变时，才接受重写。如果无法保留此时间安排，则安全失败。仅当源文件的自动点击组拓扑必须保持不变时，才使用 --click-group-policy preserve。

对于不使用规范 Notes 的 PPT 原生工作流，请使用相同语法在形状的 Alt Text 中添加显式脚本，并使用原生 Animation Pane 设置效果：

## [latency-card] latency-card
A new latency card appears and reports lower latency.

更改效果名称或解决协议冲突前，请参阅 references/animations.md。

权威性与冲突规则

按以下优先顺序处理：

1. 为此次渲染显式选择的用户 script.json 负责旁白。
2. 规范的 Author Notes 负责顺序。对于旁白，将 Notes 和 Alt Text 与形状 OOXML 中存储的最后一次由系统同步的脚本哈希进行比较。只有一个表面发生变化时，以该表面为准；如果两者都发生了不同变化，则以 Notes 为准，并由权威报告记录冲突。
3. 如果 Notes 不存在，或 Alt Text 中的旁白内容与存储的基线相比单独发生变化，则由规范的 Alt Text 块提供旁白。 仅包含普通旧版协议前 Alt Text 的新动画目标，会将该文本用作初始脚本一次，并规范化为统一块语法。
4. 旁白顺序默认按 geometry 增量插入。每个成功解析的规范 Notes 块都是锚点，并保持相对 Notes 顺序。只有 Notes 中不存在的带旁白目标才会围绕这些锚点插入。至少 35％ 的垂直重叠会形成水平带，按从上到下的顺序读取。每个带内，至少 50％ 的水平重叠会形成垂直泳道，按从左到右的顺序读取，并且每条泳道都要从上到下读完后再转到右侧。移动已有锚定形状不会改变已确立的旁白顺序；需要更改该顺序时，请移动其 Notes 块。没有几何信息的静默目标会以确定性顺序排在末尾。为保持兼容性，仍提供显式的 author-notes 策略，并采用相同的 Notes 锚点加几何插入顺序。如果新插入的带旁白块没有可用的顶层几何信息，两种策略都会安全失败。 解析 Notes、Alt Text、显式的 script.json 或请求重新生成的已更改元素后，在执行 TTS 或创建输出包之前，计算两个确定性的入场顺序：纯粹按整张幻灯片的水平带／泳道几何排序，以及按原生动画窗格顺序排序。对每种顺序中的每个符合条件的元素重新编号；不得将 Notes 锚点旁白顺序当作几何顺序呈现。只有当相对顺序颠倒涉及新插入的、Notes 中缺失的带旁白入场目标时，才存在冲突。此候选项筛选不会按几何信息重新排列已确立的 Notes 锚点。忽略静默装饰、仅强调的目标以及同时播放的组。生成 animation_order_authority.json，其中仅包含存在此类冲突的幻灯片，并提供精确的窗格行移动指引。无冲突的幻灯片保持静默，无需作出决定。
5. 动画窗格是普通原生动画类型、行顺序、On Click、With Previous、After Previous、持续时间和延迟的唯一依据。视频调度器会保留这些局部关系，同时在动画窗格阶段之间添加旁白释放门控。脚本只能通过 Spotlight 补充原生效果。
6. 形状 OOXML 会在脚本哈希旁存储 orderSource 和规范的 orderIndex。无冲突的渲染会为已确立的 Notes 锚点写入 author_notes，为新插入的块写入 geometry，然后为有效顺序重新写入连续索引。确认选择动画窗格顺序后，会为该冲突幻灯片的有效入场顺序写入 animation_pane。
7. PowerPoint 画布负责所有可见像素和几何信息。

全部 22 种已注册的原生入场预设都有明确的 MP4 处理策略。复杂预设采用命名明确的确定性近似方式，绝不会默默变成淡入。未知的入场预设组合，以及不属于受支持的入场／强调约定范围的原生动画类别，都会明确报错。 当 Notes 和 Alt Text 发生不同更改时，以 Notes 为准，并刷新交付的 PPTX Alt Text。当旧版脚本入口标记与原生行冲突时，以原生行 为准，并在冲突报告中记录被忽略的标记。没有原生行时，忽略旧版入口标记，而不是 凭空创建动画。如果某个形状已被删除，请移除其过时的 Notes 块， 并将其记录在 removed_stale_notes 中；切勿按位置或 剩余的 Animation Pane 行重新绑定。句柄存在歧义时，仍应安全失败。

一键渲染

安装公开运行时，并在渲染前验证 core 和 SVG 依赖：

python -m pip install \
  'pptx2video[svg] @ git+https://github.com/ai-nuts/pptx2video.git'
python -m playwright install chromium
pptx2video doctor --svg

然后调用本地 CLI：

pptx2video render \
  path/to/edited.pptx \
  path/to/new_video_bundle \
  --resolution 1080p

--narration-order-policy geometry 是默认的增量策略。它 保留当前规范的 Notes 块顺序，仅使用几何信息为 Notes 中缺失的旁白目标排序。 --narration-order-policy author-notes 仍可作为显式的兼容性选项。

默认的 --click-group-policy normalize 会处理每张幻灯片，而不只是 第一张。它会为每个顺序阶段生成一个编号徽标，同时将 With Previous 行保留在同一编号组中。preserve 是 显式的退出选项。

默认的 --animation-order-policy auto 仅在 stdin 是 TTY 时启用交互模式。它只会提示存在冲突的幻灯片，按幻灯片索引升序排列， 并在显示下一个冲突幻灯片之前等待当前决策。例如，先解决幻灯片 2， 再显示幻灯片 4。在非交互模式或 API 调用中，检测到冲突时会写入报告，并在创建输出 目录之前以代码 3 退出。 当 Codex 或其他技能在对话中展示该报告时，一次只显示一张冲突幻灯片，并等待用户选择后再显示下一张。使用报告中的确定性文本或 ASCII 画布，绘制每个元素的 OOXML 边界框，而不只是其中心点；并显示三个垂直堆叠的视图，在考虑等宽字体字符单元格比例后，尽量贴近 PPTX 画布的实际宽高比。根据检测到的终端宽度调整所有尺寸，不要裁切画布。三个视图中使用完全相同的轮廓。在 Geometry Order 中，框内只放几何顺序编号；在 Animation Pane Order 中，同一个框内只放 Pane 顺序编号；在 Element Identity Map 中，只放稳定身份字母，例如 A、B 或 C。不要使用 G1/P2 这类组合标签。身份字母按稳定的 shape_id 自然排序生成，与两个顺序序列无关，因此不代表顺序。每个画布都要有自己的键到语义的图例，标题必须严格为 LEGEND。在 Geometry Order 旁，将每个几何顺序编号映射到对应元素的语义描述。在 Animation Pane Order 旁，将每个 Pane 顺序编号映射到对应元素的语义描述。在 Element Identity Map 旁，将每个身份字母映射到对应元素的语义描述，以便用户能表达任意偏好，例如 C -> A -> D -> B。在宽终端上，将每个图例放在对应画布右侧。在较窄的终端上，将图例紧接着放在对应画布下方，再展示下一个视图。三个图例使用相同的选定配置：默认使用 concise，或通过 --semantic-profile detailed 使用已存储的 detailed 配置。在宽度小于 26 列时，省略边界框图，但保留三个带标签的文本视图，每个视图都包含自己的数字顺序编号或身份字母语义映射。单行元素必须保持明显的宽而薄。冲突展示时，不要使用 LLM 推断任一顺序、身份映射、布局或语义文本，也不要一次列出所有冲突幻灯片。Pane 选择仅适用于选定的冲突幻灯片；它会按 Pane 顺序串行化该幻灯片符合条件的旁白进入动画块，并同步交付的 Notes 和 OOXML 来源信息。其他冲突幻灯片保留各自的决定，无冲突幻灯片则保留 Notes 锚点加插入几何图形的来源信息。如果用户在任何幻灯片上选择 reading-order，请停止并展示报告中的确切 Pane 移动指导；不要悄悄渲染时间安排与交付的 PPTX 不同的视频。

使用确定性的 identity_order.v1 解析用户选择的身份顺序。对于 Identity Map 为 A 到 G 的冲突页面，CABGDEF 表示的顺序严格为 C -> A -> B -> G -> D -> E -> F。输入不区分大小写，并规范为大写。必须是当前页面所显示身份的完整排列；缺失、重复、未知、空白或无效标签均应拒绝。只要每个标签都是单个字母，就允许使用紧凑且无分隔符的输入。如果页面延伸到 Z 之后、包含 AA，则必须使用 A,B,...,AA 这类分隔符。在 TTY 中，直接接受当前显示页面的顺序。对于 API 或非 TTY 用法，单张冲突页面使用 --animation-order-sequence CABGDEF，或对每张冲突页面重复使用 --animation-order-sequence SLIDE=ORDER。如果序列与当前 Pane 完全一致，则将其记录为明确的 Pane 确认并渲染。如果不同，则将其 Identity 和 shape-ID 顺序写入决定报告，并停止以修订源 PPTX 的 Pane。绝不渲染与交付的 PPTX 不一致的顺序。

阅读 references/cli.md 了解安装和任意路径用法。仅当用户编辑的外部脚本应覆盖 PPTX 旁白时，才添加 --script-json path/to/edited-script.json。此命令必须：

1. 存在权威备注时，规范化统一的替代文本块。
2. 为新的动画目标生成句柄和统一的替代文本块。
3. 如果源文件只有替代文本或原生行，则回填规范备注。
4. 按用户脚本、备注、替代文本的优先顺序提取旁白，并独立于脚本权威性应用选定的旁白顺序策略。
5. 检测到变更并写回协议后，在每张幻灯片上规范化编号的点击组。确认渲染器的 Pane 时钟未发生变化，并写入 assets/meta/reports/click_group_normalization.json。
6. 为每个旁白块生成 Edge TTS 和词语时间；仅复用完全匹配的缓存。组装输出时，在每个旁白块前插入对应的 Animation Pane 阶段作为静音，将每个 Edge 词语边界按相同量平移，然后将各块拼接成幻灯片音频。为仅含原生内容的静音幻灯片生成确定性的静音音频。在元数据中保留每个逻辑分区 ID，同时通过 manifest.json 解析其可移植的物理 MP3 文件。
7. 构建按旁白序列化的时间安排：旁白对应的进入动画必须在第一个口播词开始前完成，后续 Pane 阶段只能在前一个旁白块结束后开始。保留原生同时播放组。
8. 将每条字幕提示与其实际的第一个和最后一个 Edge TTS 词语边界对齐。最终渲染中绝不使用比例计时。
9. 渲染 PPTX 像素、动画、音频、聚光效果和底部字幕带。帧源、注意力叠加层、ffmpeg、性能和调试详情请参阅 references/render_video.md。
10. 写入 timeline.json、字幕对齐证据、映射报告和严格 QA 证据。

最终渲染时不要传入 --prebuilt-audio-dir。不要传入 --no-qa。

持久化的 TTS 缓存按块进行内容寻址。其失效键是规范 JSON 标识的 SHA-256，该标识包含规范化旁白的 SHA-256、语音、速率、音调、提供方、提供方版本和缓存架构版本。计时感知型渲染只有在音频、元数据和词语边界证据的哈希及缓存键全部匹配时才接受缓存命中。因此，编辑一个块只会重新生成该块；更改任何合成设置或提供方版本都会使所有受影响的键失效。动画预录和尾部填充在缓存物化后进行，绝不会污染纯净的缓存条目。

对于感知变更的重新渲染，普通用户可选择保留现有旁白，或仅重新生成变更元素。选择后者需要之前的 PPTX 基线和 OpenAI API 密钥：

pptx2video render edited.pptx new-bundle \
  --baseline-pptx previous-video.pptx \
  --narration-mode regenerate

重新生成的脚本会写回交付的 PPTX 中的作者备注和统一替代文本块。script.json 是高级覆盖选项，并非常规编辑界面。

普通动画 PPTX

如果演示文稿尚无规范备注和替代文本，请使用现有旁白脚本引导生成一份副本，然后编辑该副本：

pptx2video bootstrap path/to/animated-source.pptx \
  --script-json path/to/script.json \
  --output path/to/editable-video.pptx \
  --report path/to/bootstrap-report.json

完成门槛

必须提供以下交付物：

new_video_bundle/
  video.mp4
  video_no_subtitles.mp4
  video.pptx
  manifest.json
  assets/audio/
  assets/captions/
  assets/meta/timeline.json
  assets/meta/reports/author_notes_authority.json
  assets/meta/reports/animation_order_authority.json
  assets/meta/reports/click_group_normalization.json
  assets/meta/reports/subtitle_timing_alignment.json
  assets/meta/reports/video_qa_report.json

确认字幕计时报告中的 status: word_aligned，然后确认 video_qa_report.json 中的 passed: true、error: 0 和 warning: 0。严格渲染器以 0 退出前，不要声称已完成。

macOS 本地使用

请参阅 references/macos.md。安装相同的 Python 包，安装 Playwright Chromium，使用 pptx2video doctor --svg 验证原生依赖和 SVG 依赖，然后从 Terminal 或外部启动器调用独立 CLI。