pptx2video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convert an edited PPTX to video

将编辑后的PPTX转换为视频

This is a standalone, general-purpose PowerPoint-to-video package. It has no runtime dependency on

paper2video

, ResearchStudio-Reel, or

ppt-master

, and the complete CLI and renderer live in the installable

pptx2video

Python package. It is not limited to research papers or to a previously delivered

video.pptx

. Use any local PPTX as the visual source. Prefer canonical Author Notes for precise narration and marker timing. When canonical Notes are absent, read the same block grammar from Shape Alt Text. Never reuse rendered bundle artifacts. Reusing a pristine block-level TTS cache entry is safe only when its complete synthesis identity matches.

这是一个独立的通用PowerPoint转视频工具包，运行时不依赖

paper2video

、ResearchStudio-Reel或

ppt-master

，完整的CLI和渲染器都包含在可安装的

pptx2video

Python包中。它不仅限于研究论文或已交付的

video.pptx

，可使用任意本地PPTX作为视觉源。优先使用标准作者备注来实现精准旁白和标记时序。当标准备注缺失时，从形状替代文本中读取相同的块语法。切勿重复使用已渲染的包产物，只有当完整合成标识匹配时，复用纯净的块级TTS缓存条目才是安全的。

Entry point

入口点

Treat

/pptx2video <input.pptx>

as a direct invocation of this skill. Use the installed public CLI for all ordinary rendering:

bash

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

Add

--animation-pointer cursor|laser

to follow native animation targets; it is independent of Spotlight and defaults to

none

Do not import or execute private Paper2Video or ResearchStudio scripts. If the CLI is unavailable, install the runtime from the public repository before continuing:

bash

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

将

/pptx2video <input.pptx>

视为对该功能的直接调用。所有常规渲染均使用已安装的公开CLI：

bash

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

添加

--animation-pointer cursor|laser

参数可跟随原生动画目标；该参数独立于聚光灯功能，默认值为

none

。

请勿导入或执行私有Paper2Video或ResearchStudio脚本。若CLI不可用，请先从公开仓库安装运行环境，再继续操作：

bash

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

Authoring contract

创作约定

For precise control, write a Notes block whose handle matches a top-level shape or group:

text

undefined

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

text

undefined

[latency-card] latency-card

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


Alt Text uses the same single-block grammar, including both leading `#`
characters. The semantic text after `]` is optional and is not spoken:

```text

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


替代文本使用相同的单块语法，包括开头的两个`#`字符。`]`后的语义文本为可选内容，不会被朗读：

```text

[latency-card] latency-card

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


The baseline hash, generated ordering provenance, and semantic profiles live
inside the PPTX shape OOXML. The visible semantic after `]` is the concise
profile. PPTX generation or protocol writeback also persists a detailed
profile. Conflict display reads those stored values and uses deterministic
fallbacks for legacy decks, so it does not call an LLM. Native effect, target,
trigger, and delay data stay in PowerPoint's `p:timing` tree. They do not appear
in Notes or Alt Text. Older `[handle]` plus `Script:`, `[ID] handle`, and verbose
`[Paper2Video]` blocks remain readable and migrate to this unified form on the
next writeback. Keep Author Notes clean. Read
[references/editable_pptx.md](references/editable_pptx.md) for the
hidden provenance contract.

The stable handle resolves the target directly. By default, successfully
resolved canonical Notes blocks keep their current relative order as anchors.
Only narrated targets missing from Notes are inserted around those anchors by
current canvas geometry. The `--narration-order-policy author-notes` option is
retained as an explicit compatibility alias and produces the same
anchor-plus-insertion narration sequence. Animation Pane order independently
controls native animation row order and local effect timing. In the rendered
video, each Pane
phase is placed in output-only pre-roll immediately before its narrated block,
and the next phase waits for the preceding block to finish speaking. The only
canonical script marker is `Spotlight`; its
position determines an Edge word-boundary time or span. Legacy entrance markers
remain readable for migration, but they never replace, create, or reorder a
native animation.

Every delivered PPTX defaults to human-editable numbered click groups on every
slide. Make each non-`With Previous` Pane row the `On Click` leader of its own
top-level `mainSeq` group. Keep contiguous `With Previous` rows with that
leader so they share its canvas badge. PowerPoint derives the badge from this
topology; it is not a stored animation ID. Accept the rewrite only when effect
targets, presets, durations, delays, Pane start/end times, row order, and
simultaneous groups remain identical. Fail closed when the schedule cannot be
preserved. Use `--click-group-policy preserve` only when the source's automatic
click-group topology must remain unchanged.

For a PPT-native workflow without canonical Notes, put an explicit script in
the shape's Alt Text using the same grammar, and use the native Animation Pane
for effects:

```text

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


基线哈希、生成的顺序来源以及语义配置文件存储在PPTX形状的OOXML中。`]`后的可见语义为简洁配置文件。PPTX生成或协议回写也会保留详细配置文件。冲突显示会读取这些存储值，并为旧版演示文稿使用确定性回退，因此无需调用LLM。原生效果、目标、触发器和延迟数据保留在PowerPoint的`p:timing`树中，不会出现在备注或替代文本中。旧版的`[handle]`加`Script:`、`[ID] handle`以及冗长的`[Paper2Video]`块仍可被读取，并在下次回写时迁移为这种统一格式。请保持作者备注简洁，阅读[references/editable_pptx.md](references/editable_pptx.md)了解隐藏的来源约定。

稳定句柄可直接解析目标。默认情况下，成功解析的标准备注块会保留其当前相对顺序作为锚点。仅当备注中缺少旁白目标时，才会根据当前画布几何结构将其插入到这些锚点周围。`--narration-order-policy author-notes`选项作为显式兼容别名保留，会生成相同的锚点加插入旁白序列。动画窗格顺序独立控制原生动画行顺序和局部效果时序。在渲染后的视频中，每个窗格阶段会被放置在仅输出的预滚动部分，紧邻其旁白块之前，下一个阶段需等待前一个块的旁白结束。唯一的标准脚本标记是`Spotlight`；其位置决定Edge词边界时间或跨度。旧版入口标记仍可被读取以用于迁移，但绝不会替换、创建或重新排序原生动画。

每个交付的PPTX默认在每张幻灯片上启用可人工编辑的编号点击组。将每个非`With Previous`的窗格行设为其自身顶层`mainSeq`组的`On Click`主导行。将连续的`With Previous`行与该主导行放在一起，使其共享画布标记。PowerPoint从这种拓扑结构生成标记，而非存储的动画ID。仅当效果目标、预设、时长、延迟、窗格开始/结束时间、行顺序和同步组保持不变时，才接受重写。当无法保留调度时，终止操作。仅当源文件的自动点击组拓扑必须保持不变时，才使用`--click-group-policy preserve`。

对于没有标准备注的PPT原生工作流，请使用相同语法在形状的替代文本中放入显式脚本，并使用原生动画窗格设置效果：

```text

[latency-card] latency-card

A new latency card appears and reports lower latency.


Read [references/animations.md](references/animations.md) before changing
effect names or resolving a protocol conflict.

A new latency card appears and reports lower latency.


在更改效果名称或解决协议冲突前，请阅读[references/animations.md](references/animations.md)。

Authority and conflict rules

权限与冲突规则

Apply this precedence:

An explicitly selected user
```
script.json
```
owns narration for that render.
Canonical Author Notes own handles. For narration, compare Notes and Alt Text with the last system-synchronized script hash stored in shape OOXML. A change on only one surface wins; if both changed differently, Notes wins and the authority report records the conflict.
A canonical Alt Text block provides narration when Notes are absent or when its narration alone differs from the stored baseline. A new animated target with only plain pre-protocol Alt Text uses that text once as its initial script and is normalized to the unified block grammar.
Narration order defaults to incremental
```
geometry
```
insertion. Every successfully resolved canonical Notes block is an anchor and keeps its relative Notes order. Only narrated targets absent from Notes are inserted around those anchors. At least 35 percent vertical overlap forms horizontal bands read top-to-bottom. Within each band, at least 50 percent horizontal overlap forms vertical lanes read left-to-right, and every lane is completed top-to-bottom before advancing right. Moving an existing anchored shape does not reorder established narration; move its Notes block when that order must change. Silent targets without geometry remain deterministic at the end. The explicit
```
author-notes
```
policy remains available for compatibility and uses the same Notes-anchor plus geometry-insertion sequence. Both policies fail closed when a newly inserted narrated block has no usable top-level geometry. After resolving Notes, Alt Text, an explicit
```
script.json
```
, or requested changed-element regeneration, but before TTS or output-bundle creation, compute two deterministic entrance sequences: a pure full-slide band/lane geometry order and native Animation Pane order. Number every eligible element again in each sequence; do not present the Notes-anchor narration sequence as geometry order. A conflict exists only when a relative inversion involves a newly inserted, Notes-missing narrated entrance target. This candidate filter does not geometrically reorder established Notes anchors. Ignore silent decoration, emphasis-only targets, and simultaneous groups. Emit
```
animation_order_authority.json
```
containing only slides with such conflicts, including exact Pane-row move guidance. Slides without conflicts remain silent and require no decision.
Animation Pane is the sole authority for ordinary native animation type, row order,
```
On Click
```
,
```
With Previous
```
,
```
After Previous
```
, duration, and delay. The video scheduler preserves those local relationships while adding narration release gates between Pane phases. A script can supplement the native effects only with
```
Spotlight
```
.
Shape OOXML stores
```
orderSource
```
and canonical
```
orderIndex
```
beside the script hash. A no-conflict render writes
```
author_notes
```
for established Notes anchors and
```
geometry
```
for newly inserted blocks, then rewrites contiguous indices for the effective sequence. A confirmed Pane choice writes
```
animation_pane
```
for that selected conflict slide's effective entrance sequence.
The PowerPoint canvas owns all visible pixels and geometry.

All 22 registered native entrance presets have explicit MP4 strategies. Complex presets use named deterministic approximations and never silently become Fade. Unknown entrance preset tuples and native animation classes outside the supported entrance/emphasis contract fail explicitly.

When Notes and Alt Text both changed differently, Notes wins and the delivered PPTX Alt Text is refreshed. When a legacy script entrance marker conflicts with a native row, the native row wins and the conflict report records the ignored marker. Without a native row, a legacy entrance marker is ignored rather than inventing an animation. If a shape was deleted, remove its stale Notes block and record it in

removed_stale_notes

; never rebind it by position or by a remaining Animation Pane row. Ambiguous live handles still fail closed.

遵循以下优先级：

显式选择的用户
```
script.json
```
拥有该渲染的旁白权限。
标准作者备注拥有句柄权限。对于旁白，将备注和替代文本与形状OOXML中存储的最后一个系统同步脚本哈希进行比较。仅其中一方有变更时，变更方获胜；若双方变更不同，备注获胜，并在权限报告中记录冲突。
当备注缺失或仅其旁白与存储的基线不同时，标准替代文本块提供旁白。带有纯协议前替代文本的新动画目标会将该文本作为初始脚本使用一次，并被标准化为统一块语法。
旁白顺序默认为增量
```
geometry
```
插入。每个成功解析的标准备注块都是一个锚点，并保留其相对备注顺序。仅备注中缺少的旁白目标会被插入到这些锚点周围。至少35%的垂直重叠形成水平区域，按从上到下的顺序读取。在每个区域内，至少50%的水平重叠形成垂直列，按从左到右的顺序读取，且每列在向右推进前需完成从上到下的读取。移动现有锚点形状不会改变已确立的旁白顺序；若必须更改顺序，请移动其备注块。无几何结构的静默目标始终在末尾保持确定性。显式的
```
author-notes
```
策略仍可用于兼容，使用相同的备注锚点加几何插入序列。当新插入的旁白块没有可用的顶层几何结构时，两种策略都会终止操作。在解析备注、替代文本、显式
```
script.json
```
或请求的变更元素再生后，在创建TTS或输出包之前，计算两个确定性入口序列：纯全幻灯片区域/列几何顺序和原生动画窗格顺序。在每个序列中重新为所有符合条件的元素编号；请勿将备注锚点旁白序列显示为几何顺序。仅当相对反转涉及新插入的、缺少备注的旁白入口目标时，才存在冲突。此候选过滤器不会对已确立的备注锚点进行几何重排序。忽略静默装饰、仅强调目标和同步组。生成仅包含此类冲突幻灯片的
```
animation_order_authority.json
```
，包括精确的窗格行移动指导。无冲突的幻灯片无需处理，也无需决策。
动画窗格是普通原生动画类型、行顺序、
```
On Click
```
、
```
With Previous
```
、
```
After Previous
```
、时长和延迟的唯一权威。视频调度器在保留这些局部关系的同时，在窗格阶段之间添加旁白释放门。脚本仅可通过
```
Spotlight
```
补充原生效果。
形状OOXML在脚本哈希旁存储
```
orderSource
```
和标准
```
orderIndex
```
。无冲突渲染会为已确立的备注锚点写入
```
author_notes
```
，为新插入的块写入
```
geometry
```
，然后重写有效序列的连续索引。确认的窗格选择会为该选定冲突幻灯片的有效入口序列写入
```
animation_pane
```
。
PowerPoint画布拥有所有可见像素和几何结构。

所有22个已注册的原生入口预设都有明确的MP4策略。复杂预设使用命名的确定性近似值，绝不会自动变为淡入效果。未知的入口预设元组和超出支持的入口/强调约定的原生动画类会显式终止操作。

当备注和替代文本都发生不同变更时，备注获胜，交付的PPTX替代文本会被刷新。当旧版脚本入口标记与原生行冲突时，原生行获胜，并在冲突报告中记录被忽略的标记。若无原生行，旧版入口标记会被忽略，而非创建动画。若形状已被删除，请移除其过时的备注块并记录在

removed_stale_notes

中；切勿通过位置或剩余的动画窗格行重新绑定。模糊的活动句柄仍会终止操作。

One-command render

一键渲染

Install the public runtime and verify both core and SVG dependencies before rendering:

bash

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

Then invoke the local CLI:

bash

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

--narration-order-policy geometry

is the default incremental policy. It preserves the current canonical Notes block sequence and uses geometry only to place narrated targets missing from Notes.

--narration-order-policy author-notes

remains an explicit compatibility selection.

The default

--click-group-policy normalize

processes every slide, not only the first slide. It produces one numbered badge per sequential phase while keeping

With Previous

rows in the same numbered group.

preserve

is the explicit opt-out.

The default

--animation-order-policy auto

is interactive only when stdin is a TTY. It prompts only for conflict slides, in ascending slide index, and waits for each decision before showing the next conflict slide. For example, resolve slide 2 before displaying slide 4. In non-interactive or API use, a detected conflict writes the report and exits with code 3 before creating the output directory.

When Codex or another skill presents that report in conversation, show exactly one conflict slide at a time and wait for the user's choice before showing the next. Use the report's deterministic text or ASCII canvas, draw each element's OOXML bounding box rather than only its center, and show three vertically stacked views that approximate the PPTX canvas's actual aspect ratio after accounting for monospace character-cell proportions. Fit all dimensions to the detected terminal width rather than clipping a canvas. Use identical outlines in all three views. Put only the geometry rank number inside each box in

Geometry Order

, only the Pane rank number inside the same box in

Animation Pane Order

, and only its stable identity letter such as

, or

Element Identity Map

. Do not use combined labels such as

G1/P2

. Identity letters follow natural sort of stable

shape_id

, independently of both order sequences, so they carry no ordering meaning. Give every canvas its own key-to-semantic legend titled exactly

LEGEND

. Beside

Geometry Order

, map each geometry rank number to that element's semantic description. Beside

Animation Pane Order

, map each Pane rank number to that element's semantic description. Beside

Element Identity Map

, map each identity letter to that element's semantic description, so a user can state an arbitrary preference such as

C -> A -> D -> B

. On a wide terminal, place each legend to the right of its corresponding canvas. On a narrower terminal, place it immediately below that canvas before presenting the next view. The same selected profile applies to all three legends: default to

concise

, or use the stored

detailed

profile through

--semantic-profile detailed

. Below 26 columns, omit the bbox plots but retain three labeled textual views, each with its own numeric-rank or identity-letter semantic mapping. Thin one-line elements must remain visibly wide and thin. Do not use an LLM to infer either sequence, the identity map, the layout, or the semantic text at conflict-display time, and do not list all conflict slides at once. A Pane choice applies only to the selected conflict slide; it serializes that slide's eligible narrated entrance blocks in Pane order and synchronizes delivered Notes and OOXML provenance. Other conflict slides keep their own decisions, and no-conflict slides retain Notes-anchor plus inserted-geometry provenance. If the user chooses

reading-order

on any slide, stop and present the exact Pane move guidance from the report; do not silently render a video whose schedule differs from the delivered PPTX.

Parse a user-selected Identity order with deterministic

identity_order.v1

. For a conflict page whose Identity Map is

through

CABGDEF

means exactly

C -> A -> B -> G -> D -> E -> F

. Treat input case-insensitively and canonicalize it to uppercase. Require a complete permutation of the current page's displayed identities, rejecting missing, duplicate, unknown, empty, or invalid labels. Compact undelimited input is valid while every label is one letter. If a page extends past

AA

, require separators such as

A,B,...,AA

. In a TTY, accept the order directly for the displayed page. For API or non-TTY use, accept

--animation-order-sequence CABGDEF

for one conflict page, or repeat

--animation-order-sequence SLIDE=ORDER

for every conflict page. If the sequence exactly matches the current Pane, record it as explicit Pane confirmation and render. If it differs, persist its Identity and shape-ID orders in the decision report and stop for a source-PPTX Pane revision. Never render an order that disagrees with the delivered PPTX.

Read references/cli.md for installation and arbitrary-path usage. Add

--script-json path/to/edited-script.json

only when a user-edited external script should override PPTX narration. This command must:

Normalize unified Alt Text blocks from authoritative Notes when present.
Generate handles and unified Alt Text blocks for new animation targets.
Backfill canonical Notes when the source has only Alt Text or native rows.
Extract narration using user script, Notes, then Alt Text precedence, and apply the selected narration-order policy independently of script authority.
Normalize numbered click groups across every slide after change detection and protocol writeback. Verify that the renderer's Pane clock is unchanged and write
```
assets/meta/reports/click_group_normalization.json
```
.
Materialize Edge TTS and word timings per narration block, reusing only exact cache hits. During output assembly, prepend the corresponding Animation Pane phase as silence before each narrated block, shift every Edge word boundary by the same amount, then concatenate the blocks into slide audio. Generate deterministic silent audio for a native-only silent slide. Preserve each logical section ID in metadata while resolving its portable physical MP3 through
```
manifest.json
```
.
Build the narration-serialized schedule: a narrated entrance completes before its first spoken word, and the following Pane phase starts only after the preceding narrated block ends. Preserve native simultaneous groups.
Align every subtitle cue to its actual first and last Edge TTS word boundaries. Never use proportional timing in a final render.
Render PPTX pixels, animations, audio, spotlight, and bottom-band subtitles. Read references/render_video.md for frame-source, attention-overlay, ffmpeg, performance, and debugging details.
Write
```
timeline.json
```
, subtitle-alignment evidence, mapping reports, and strict QA evidence.

Do not pass

--prebuilt-audio-dir

for a final render. Do not pass

--no-qa

The persistent TTS cache is content addressed per block. Its invalidation key is the SHA-256 of a canonical JSON identity containing normalized narration SHA-256, voice, rate, pitch, provider, provider version, and cache schema version. A timing-aware render accepts a hit only when audio, metadata, and word-boundary evidence all match their hashes and cache key. Editing one block therefore regenerates that block only; changing any synthesis setting or provider version invalidates every affected key. Animation pre-roll and tail padding happen after cache materialization and never contaminate the pristine cache entry.

For a change-aware rerender, ordinary users choose whether to keep existing narration or regenerate only changed elements. The latter requires a previous PPTX baseline and an OpenAI API key:

bash

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

Regenerated scripts are written back into both Author Notes and unified Alt Text blocks in the delivered PPTX.

script.json

remains an Advanced override, not the normal editing surface.

在渲染前安装公开运行环境并验证核心和SVG依赖：

bash

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

然后调用本地CLI：

bash

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

--narration-order-policy geometry

是默认的增量策略，它保留当前标准备注块序列，仅使用几何结构放置备注中缺少的旁白目标。

--narration-order-policy author-notes

仍为显式兼容选项。

默认的

--click-group-policy normalize

会处理每张幻灯片，而非仅第一张。它为每个连续阶段生成一个编号标记，同时将

With Previous

行保留在同一编号组中。

preserve

是显式的退出选项。

默认的

--animation-order-policy auto

仅在标准输入为TTY时才会交互。它仅针对冲突幻灯片按幻灯片索引升序提示，并在显示下一个冲突幻灯片前等待每个决策。例如，先解决幻灯片2的冲突，再显示幻灯片4。在非交互式或API使用中，检测到冲突时会写入报告并以代码3退出，不会创建输出目录。

当Codex或其他功能在对话中呈现该报告时，一次仅显示一张冲突幻灯片，等待用户选择后再显示下一张。使用报告的确定性文本或ASCII画布，绘制每个元素的OOXML边界框而非仅中心，并显示三个垂直堆叠的视图，近似PPTX画布在考虑等宽字符单元格比例后的实际宽高比。将所有尺寸适配检测到的终端宽度，而非裁剪画布。在所有三个视图中使用相同的轮廓。在

Geometry Order

的每个框内仅放置几何排名编号，在

Animation Pane Order

的同一框内仅放置窗格排名编号，在

Element Identity Map

的同一框内仅放置其稳定标识字母（如

、

或

）。请勿使用

G1/P2

这类组合标签。标识字母遵循稳定

shape_id

的自然排序，独立于两个顺序序列，因此不带有排序含义。为每个画布提供一个标题为

LEGEND

的键到语义图例。在

Geometry Order

旁，将每个几何排名编号映射到该元素的语义描述。在

Animation Pane Order

旁，将每个窗格排名编号映射到该元素的语义描述。在

Element Identity Map

旁，将每个标识字母映射到该元素的语义描述，以便用户可以表达任意偏好，如

C -> A -> D -> B

。在宽终端上，将每个图例放在对应画布的右侧。在较窄终端上，在呈现下一个视图前，将图例立即放在对应画布下方。相同的选定配置文件适用于所有三个图例：默认使用

concise

，或通过

--semantic-profile detailed

使用存储的

detailed

配置文件。在26列以下，省略边界框图，但保留三个带标签的文本视图，每个视图都有自己的数字排名或标识字母语义映射。细单行元素必须保持可见的宽而薄的状态。在冲突显示时，请勿使用LLM推断序列、标识映射、布局或语义文本，也请勿一次性列出所有冲突幻灯片。窗格选择仅适用于选定的冲突幻灯片；它会按窗格顺序序列化该幻灯片的所有符合条件的旁白入口块，并同步交付的备注和OOXML来源。其他冲突幻灯片保留各自的决策，无冲突幻灯片保留备注锚点加插入几何结构的来源。若用户在任何幻灯片上选择

reading-order

，请停止并呈现报告中精确的窗格移动指导；切勿静默渲染调度与交付的PPTX不同的视频。

使用确定性的

identity_order.v1

解析用户选择的标识顺序。对于标识映射为

到

的冲突页面，

CABGDEF

表示确切的

C -> A -> B -> G -> D -> E -> F

。不区分输入大小写，并将其规范化为大写。要求对当前页面显示的标识进行完整排列，拒绝缺失、重复、未知、空或无效的标签。无分隔符的输入有效，前提是每个标签为单个字母。若页面扩展到

之后至

AA

，则需要分隔符，如

A,B,...,AA

。在TTY中，直接接受显示页面的顺序。对于API或非TTY使用，为一个冲突页面接受

--animation-order-sequence CABGDEF

，或为每个冲突页面重复

--animation-order-sequence SLIDE=ORDER

。若序列与当前窗格完全匹配，则记录为显式窗格确认并渲染。若不同，则在决策报告中保留其标识和形状ID顺序，并停止以进行源PPTX窗格修订。切勿渲染与交付的PPTX不一致的顺序。

阅读references/cli.md了解安装和任意路径使用方法。仅当用户编辑的外部脚本应覆盖PPTX旁白时，才添加

--script-json path/to/edited-script.json

。此命令必须：

当存在权威备注时，将统一替代文本块标准化为权威备注。
为新动画目标生成句柄和统一替代文本块。
当源文件仅包含替代文本或原生行时，回填标准备注。
按照用户脚本、备注、替代文本的优先级提取旁白，并独立于脚本权限应用选定的旁白顺序策略。
在变更检测和协议回写后，标准化每张幻灯片的编号点击组。验证渲染器的窗格时钟未更改，并写入
```
assets/meta/reports/click_group_normalization.json
```
。
为每个旁白块生成Edge TTS和词时序，仅复用精确的缓存命中项。在输出组装期间，在每个旁白块前添加对应的动画窗格阶段作为静默部分，将每个Edge词边界移动相同的量，然后将块连接成幻灯片音频。为仅含原生动画的静默幻灯片生成确定性静音音频。在元数据中保留每个逻辑部分ID，同时通过
```
manifest.json
```
解析其可移植的物理MP3。
构建旁白序列化调度：旁白入口在第一个单词说出前完成，下一个窗格阶段仅在前一个旁白块结束后开始。保留原生同步组。
将每个字幕提示与实际的Edge TTS首尾词边界对齐。在最终渲染中切勿使用比例时序。
渲染PPTX像素、动画、音频、聚光灯和底部字幕。阅读references/render_video.md了解帧源、注意力覆盖、ffmpeg、性能和调试细节。
写入
```
timeline.json
```
、字幕对齐证据、映射报告和严格的QA证据。

最终渲染请勿传递

--prebuilt-audio-dir

参数。请勿传递

--no-qa

参数。

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

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

bash

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

重新生成的脚本会回写到交付的PPTX的作者备注和统一替代文本块中。

script.json

仍是高级覆盖选项，而非常规编辑界面。

Ordinary animated PPTX

普通动画PPTX

If the deck does not yet contain canonical Notes and Alt Text, bootstrap a copy from an existing narration script, then edit that copy:

bash

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

若演示文稿尚未包含标准备注和替代文本，可从现有旁白脚本引导生成副本，然后编辑该副本：

bash

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

Completion gate

完成校验

Require these deliverables:

text

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

Confirm the subtitle timing report has

status: word_aligned

, then confirm

video_qa_report.json

has

passed: true

error: 0

, and

warning: 0

. Do not claim completion until the strict renderer exits 0.

需要交付以下内容：

text

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

为

、

warning

为

。在严格渲染器以0退出前，请勿声称完成。

macOS local use

macOS本地使用

Read references/macos.md. Install the same Python package, install Playwright Chromium, verify native and SVG dependencies with

pptx2video doctor --svg

, and invoke the standalone CLI from Terminal or an external launcher.

阅读references/macos.md。安装相同的Python包，安装Playwright Chromium，使用

pptx2video doctor --svg

验证原生和SVG依赖，然后从终端或外部启动器调用独立CLI。