Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(pptx-to-svg): reconstruct finite object animations

hugohe3f904aae183de
diff --git a/docs/animations.md b/docs/animations.md
index a31873f2..0cae81f2 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -272,6 +272,7 @@ PPT Master validates animation settings strictly: unknown effects or Start modes
| Unsupported object builds | No paragraph/text-range builds, custom freeform motion-path authoring, native Chart/SmartArt build sequencing, or media playback commands are inferred from grouped SVG content |
| Output route | Animation exists in the native PPTX generated from `svg_output/`; `svg_final/` is a static preview |
| Existing PPTX routes | Template Fill and Native Enhance preserve source object animation rather than translating it into this generated-deck model |
+| PPTX-to-SVG import | Reconstructs only current-registry rows with exact native duration and unique top-level group targets; advanced/build/media timing remains diagnosed |
| Playback compatibility | Microsoft PowerPoint desktop is the primary validation target; Keynote, WPS, LibreOffice, and older Office versions may remap or omit individual effects |
For the full CLI reference, see [`svg-pipeline.md`](../skills/ppt-master/scripts/docs/svg-pipeline.md). For exact effect definitions, sidecar requirements, anchor fallback logic, and OOXML read-back rules, see the [animation execution reference](../skills/ppt-master/references/animations.md).
diff --git a/docs/faq.md b/docs/faq.md
index 4bff06a5..fe24de2d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -197,8 +197,9 @@ animation is **off by default**—a page appears as a whole instead of having
elements auto-cascade in one by one. Both are controlled by `svg_to_pptx.py`
flags: `-t/--transition` for page-level and `-a/--animation` for element-level.
The object registry includes entrance, emphasis, motion-path, and exit effects.
-`pptx_to_svg.py` also reconstructs exact current-registry page transitions into
-`animations.json`; unsupported source carriers remain explicit diagnostics.
+`pptx_to_svg.py` also reconstructs exact current-registry page transitions and
+finite exact-duration object-animation rows into `animations.json`;
+unsupported source timing remains an explicit diagnostic.
```bash
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index 2a3adea7..f06771ba 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -241,7 +241,7 @@ owner.
|---|---|---|---|---|
| Speaker notes | `notes/<slide>.md` sidecar | Notes Slide part and relationship | `Sidecar/package` | Notes are not SVG text and do not affect page geometry |
| Slide transition | CLI options or `animations.json` | `p:transition` | `Sidecar/package`; PPTX import reconstructs exact current-registry transitions into `animations.json` | Unknown effects or inexact carriers fail or remain diagnosed; no silent `fade` fallback |
-| Object animation (entrance / emphasis / motion path / exit) | `animations.json` targeting stable top-level SVG group IDs; `effects[]` may assign several rows to one anchor | Root `p:timing` animation tree | `Sidecar/package`; the group ID is only the shape-target anchor | Static structural layers and placeholders cannot be animated |
+| Object animation (entrance / emphasis / motion path / exit) | `animations.json` targeting stable top-level SVG group IDs; `effects[]` may assign several rows to one anchor | Root `p:timing` animation tree | `Sidecar/package`; PPTX import reconstructs exact-duration current-registry rows into the sidecar | Target and optional trigger shape must map uniquely; advanced/build/media timing remains diagnosed/direct-preserve |
| Narration audio | `audio/` asset plus recorded-narration export option | Media relationship, audio carrier, and timing | `Sidecar/package` | Asset, slide association, and timing must validate |
| Automatic slide advance | Explicit transition timing or narration-derived duration | `advTm`/advance behavior | `Sidecar/package` | Click-driven animation is incompatible with recorded narration |
| Whole-object hyperlink | Standard SVG `<a href="...">` around one visual element or group | `p:cNvPr/a:hlinkClick` on each clickable leaf plus one shared relationship | `Native-stable` for supported external and same-deck targets; PPTX import reconstructs the anchor | Add an explicit background shape when gaps inside a multi-object card/button must be clickable |
@@ -293,6 +293,7 @@ The importer reconstructs supported PowerPoint semantics into the same project v
| Group | `<g>` |
| Supported native table/chart | Visible fallback plus native-object metadata |
| Supported current-registry page transition | Canonical `animations.json` row with effective options, exact duration, optional auto-advance, and supported WAV sound |
+| Supported exact-duration object-animation sequence | Canonical `animations.json` group rows with effect/options, order, trigger, duration, relative delay, and optional `trigger_shape` |
| Unsupported graphic frame or SmartArt | Explicit preview, placeholder, or unsupported status |
This is semantic projection, not a syntax round trip. Preserving validated source-package Master/Layout facts is confined to Create Template mirror and always produces a new workspace; an ordinary visual import does not infer reusable topology from slide appearance.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index b0a4e60c..87f2c2bc 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -71,7 +71,7 @@ A presentation is four layers: what is on the slide, how it is arranged, how it
| Concern | Status | Notes |
|---|---|---|
| Page transitions | Systematized | Includes on-demand transition sounds from a bundled CC0 catalog; PPTX import reconstructs exact current-registry transitions into the canonical sidecar |
-| Object animation | Systematized | Off by default and opt-in; per-object configuration is explicit |
+| Object animation | Systematized | Off by default and opt-in; per-object configuration is explicit, and PPTX import reconstructs the finite exact-duration current-registry subset into the canonical sidecar |
| Auto-advance | Covered | Derived from narration lead-in, audio duration, and page-tail padding |
| Media playback | Covered | Narration audio and animation sounds play natively; media already present in a source deck keeps its playback settings |
| Hyperlinks | Systematized | Whole-object and inline-text links author through standard SVG `<a href>`, export as native external or same-deck click relationships, and reconstruct on supported PPTX import |
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index 4f24ac22..e2a1c4d4 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -248,6 +248,7 @@ PPT Master 会严格校验动画设置:未知效果或 Start 模式、非法
| 不支持的对象 build | 不会从分组 SVG 推导段落/文字范围 build、自定义自由动作路径、原生 Chart/SmartArt 分步 build 或媒体播放命令 |
| 输出路线 | 动画存在于从 `svg_output/` 生成的原生 PPTX;`svg_final/` 只是静态预览 |
| 现有 PPTX 路线 | Template Fill 与 Native Enhance 保留源对象动画,不把它翻译成生成路线的动画模型 |
+| PPTX-to-SVG 回导 | 只重建当前注册表内具有精确原生时长且可唯一映射到顶层 group 的记录;高级/build/media timing 保留诊断 |
| 播放兼容性 | Microsoft PowerPoint 桌面版是主要验证目标;Keynote、WPS、LibreOffice 与较旧 Office 可能重新映射或忽略个别效果 |
完整 CLI 说明见 [`svg-pipeline.md`](../../skills/ppt-master/scripts/docs/svg-pipeline.md)。精确效果定义、sidecar 要求、锚点回退逻辑与 OOXML 回读规则见[动画执行规范](../../skills/ppt-master/references/animations.md)。
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 85d21245..eca7415e 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -189,8 +189,8 @@ carrier 与保留边界见 [PowerPoint ↔ SVG 映射指南](./powerpoint-svg-ma
一页时整页一次性呈现,不会自动逐个级联。两者都通过 `svg_to_pptx.py` 的
参数控制:`-t/--transition` 控制页级,`-a/--animation` 控制元素级。对象
注册表已经包含进入、强调、动作路径和退出效果。
-`pptx_to_svg.py` 也会把当前注册表内可精确读回的页面切换重建到
-`animations.json`;不支持的来源 carrier 会保留明确诊断。
+`pptx_to_svg.py` 也会把当前注册表内可精确读回的页面切换和具有精确时长的
+有限对象动画记录重建到 `animations.json`;不支持的来源 timing 会保留明确诊断。
```bash
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index 81dadbda..8c1c72f5 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -231,7 +231,7 @@ SVG 预览内容只负责让导出前的作者页面保持可见。
|---|---|---|---|---|
| 演讲者备注 | `notes/<slide>.md` sidecar | Notes Slide part 与 relationship | `Sidecar/package` | 备注不是 SVG 文本,不影响页面几何 |
| 幻灯片切换 | CLI 选项或 `animations.json` | `p:transition` | `Sidecar/package`;PPTX 回导把当前注册表内的精确切换重建到 `animations.json` | 未知效果或不精确 carrier 会失败或保留诊断;不默默 fallback 到 `fade` |
-| 对象动画(进入 / 强调 / 动作路径 / 退出) | `animations.json`,目标为稳定的顶层 SVG group ID;`effects[]` 可让一个锚点拥有多条记录 | 根 `p:timing` 动画树 | `Sidecar/package`;group ID 仅为 shape target 锚点 | 静态结构层与占位符不可动画 |
+| 对象动画(进入 / 强调 / 动作路径 / 退出) | `animations.json`,目标为稳定的顶层 SVG group ID;`effects[]` 可让一个锚点拥有多条记录 | 根 `p:timing` 动画树 | `Sidecar/package`;PPTX 回导把当前注册表内具有精确时长的记录重建到 sidecar | target 与可选 trigger shape 必须唯一映射;高级/build/media timing 保留诊断或直接保留 |
| 旁白音频 | `audio/` 资产加 recorded-narration 导出选项 | media relationship、audio carrier 与 timing | `Sidecar/package` | 必须校验资产、Slide 关联与时序 |
| 幻灯片自动换页 | 显式 transition timing 或旁白派生时长 | `advTm`/换页行为 | `Sidecar/package` | 单击驱动动画与录制旁白不兼容 |
| 整体对象超链接 | 标准 SVG `<a href="...">` 包裹一个可见元素或组 | 每个可点击叶子上的 `p:cNvPr/a:hlinkClick`,共用一个 relationship | 受支持外链与 deck 内目标为 `Native-stable`;PPTX 回导重建 anchor | 多对象卡片 / 按钮的间隙也要可点时,需显式加入背景形状 |
@@ -280,6 +280,7 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re
| 组 | `<g>` |
| 受支持原生表格/图表 | 可见 fallback 加原生对象 metadata |
| 当前注册表内受支持的页面切换 | 规范 `animations.json` 记录,包含有效选项、精确时长、可选自动换页与受支持 WAV 声音 |
+| 受支持的精确时长对象动画序列 | 规范 `animations.json` group 记录,包含效果/选项、顺序、触发、时长、相对延迟与可选 `trigger_shape` |
| 不支持的 graphic frame 或 SmartArt | 显式 preview、placeholder 或 unsupported 状态 |
这是语义投影,不是语法往返。只有 Create Template mirror 可把来源包中已验证的 Master/Layout 事实保留到新工作区;普通视觉导入不会从 Slide 外观推断可复用拓扑。
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 3010fab9..3df06c14 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -71,7 +71,7 @@
| 关注点 | 状态 | 说明 |
|---|---|---|
| 页面转场 | 系统化 | 含来自内置 CC0 音效库的按需转场音;PPTX 回导会把当前注册表内的精确转场重建到规范 sidecar |
-| 对象动画 | 系统化 | 默认关闭、opt-in;逐对象配置为显式声明 |
+| 对象动画 | 系统化 | 默认关闭、opt-in;逐对象配置为显式声明,PPTX 回导会把当前注册表内具有精确时长的有限子集重建到规范 sidecar |
| 自动翻页 | 已覆盖 | 由旁白起始留白、音频时长与页尾补白推导 |
| 音视频播放 | 已覆盖 | 旁白音频与动画音效原生播放;来源 deck 中已有的媒体保留其播放设置 |
| 超链接 | 系统化 | 整体对象与行内文字通过标准 SVG `<a href>` 创作,导出为原生外链或 deck 内跳转关系,并在受支持的 PPTX 回导中重建 |
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index cb09c0c4..18f62831 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -603,6 +603,14 @@ source transitions remain absent on re-export. Unknown or inexact native
carriers stay diagnosed/direct-preserve. This is a closed PPT Master-owned
contract, not an arbitrary OOXML transition normalizer.
+For source `p:timing`, the importer accepts only current generated behavior
+trees whose registry effect/options, pane order, Start trigger, exact duration,
+relative delay, and target/optional trigger shape map to unique top-level slide
+SVG groups. It emits one group row or `effects[]` in the same sidecar. Rows
+without a native duration, advanced timing modifiers, sounds, builds/media
+commands, unknown behavior trees, and unmapped targets remain diagnosed/direct-
+preserve; no timing value is inferred.
+
**Validation boundary**: these checks prove PPTX timing, relationships, and
embedded sound parts. They are not final-video audio acceptance. The
native-export branch requires a triggered `video_sound_mix.py` receipt; the
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index d9d4d7c8..54b81ba9 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -296,6 +296,11 @@ transition registry are read back with their effective options, exact duration,
automatic advance, and optional embedded WAV sound. Source transition XML
outside that closed writer/read-back contract remains diagnosed rather than
being normalized by guesswork.
+Finite object-animation rows from the current writer are also projected when
+their registry effect, effective options, pane order, trigger, exact duration,
+relative delay, and top-level SVG group target all read back exactly. Advanced
+timing, build/media trees, duration-less native rows, and unmapped targets stay
+diagnosed/direct-preserve.
`pptx_to_svg.py` annotates verified text-grid tables and conservative chart data with `data-pptx-replace-with` beside the visible SVG fallback and places the payload in `<metadata type="application/json">`; the parent claim selects the chart or table schema. Imported table/chart groups under this contract carry `data-pptx-import-source="pptx"`, whether active or fallback-only. Table import covers exact physical row/grid topology, canonical rectangular merges, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph schema. Each rich run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. A merge must use the exact `rowSpan` / `gridSpan` / `hMerge` / `vMerge` physical topology with empty merge slaves. Presentation-only source run XML without a non-empty `effectLst` / `effectDag` normalizes; a table-cell run effect disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, broken text topology, unsafe border XML, non-solid fills, and other merge encodings remain fallback-only. For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, the normalized SVG fallback resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct cell/run overrides; other built-in/custom style families are not implied.
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index ad6e90b7..ad910931 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -295,12 +295,12 @@ retains the usable fallback/object and records the degradation; it does not
discard unrelated shapes, pages, or the entire deck.
Source `p:transition` and `p:timing` nodes are never silently implied by the
-static SVG view. Supported page transitions are reconstructed in
-`animations.json`; source object timing still emits
+static SVG view. Supported page transitions and finite object-animation
+sequences are reconstructed in `animations.json`; source timing outside either
+closed contract emits `transition-not-reconstructed` or
`animation-not-reconstructed` with the exact source slide. Direct PPTX
-Fill/Enhance workflows remain the source-preserving route for timing outside
-the closed read-back contracts; `--strict` stops on the first unreconstructed
-node.
+Fill/Enhance workflows remain the source-preserving route for all other timing;
+`--strict` stops on the first unreconstructed node.
### Page-transition reverse import
@@ -317,6 +317,26 @@ Unknown effects, legacy `p:transition@spd`, visual effects without exact
relationships produce `transition-not-reconstructed` in tolerant mode;
`--strict` stops. The converter never substitutes `fade` for those cases.
+### Finite object-animation reverse import
+
+The importer accepts only rows that pass the current generated-animation
+behavior-tree validator and map both their target and optional click trigger to
+one unique top-level slide SVG group. It reconstructs the canonical registry
+effect, non-default effective options, Animation Pane order, Start trigger,
+exact native duration, and relative delay. Repeated targets use `effects[]`;
+shape-triggered rows restore `trigger_shape`.
+
+This exact-duration subset covers 199 of the 203 registered effects. The four
+native rows without a readable behavior duration—`emphasis_change_font`,
+`emphasis_change_font_style`, `emphasis_transparency`, and
+`emphasis_bold_reveal`—remain diagnosed because their authored scheduling span
+cannot be separated honestly from the following delay. Repeat/reverse/rewind,
+acceleration/bounce/restart, after-effects, animation sounds, paragraph or
+Chart/SmartArt builds, media commands, unknown behavior trees, and targets that
+do not map to a top-level SVG group likewise produce
+`animation-not-reconstructed`; `--strict` stops. The importer never invents a
+replacement timing tree.
+
### Native formula reverse import
The importer reconstructs formulas only from the closed OMML vocabulary owned
diff --git a/skills/ppt-master/scripts/docs/pptx-animations.md b/skills/ppt-master/scripts/docs/pptx-animations.md
index 82e33ad1..d6fa0822 100644
--- a/skills/ppt-master/scripts/docs/pptx-animations.md
+++ b/skills/ppt-master/scripts/docs/pptx-animations.md
@@ -236,6 +236,15 @@ duplicate or malformed `p:cTn` ids, missing `p:spTgt` shapes, invalid build
targets, and unsupported generated effect tuples. A mismatch fails export
before the requested output file replaces an existing deck.
+`pptx_to_svg.py` reuses that semantic reader and behavior-tree validator for a
+finite reverse projection. A row enters `animations.json` only when its current
+registry effect/options, pane order, Start trigger, exact behavior duration,
+relative delay, and target/optional trigger shape can be represented by unique
+top-level slide SVG groups. Repeated targets become `effects[]`. Duration-less
+native rows, advanced timing modifiers, sounds, build/media commands, unknown
+trees, and unmapped targets remain explicit import diagnostics. This is not a
+general PowerPoint timing-tree normalizer.
+
Narration injection parses and merges the slide DOM. It adds audio timing under
the existing `tmRoot`, allocates fresh ids, and preserves object animation.
For bounce timing it updates both p14 Choice and Fallback; unsupported nested
diff --git a/skills/ppt-master/scripts/pptx_animations.py b/skills/ppt-master/scripts/pptx_animations.py
index fae4d227..10589b6a 100644
--- a/skills/ppt-master/scripts/pptx_animations.py
+++ b/skills/ppt-master/scripts/pptx_animations.py
@@ -3857,6 +3857,39 @@ def describe_animation_effect(effect: object) -> dict[str, Any]:
}
+def effective_animation_effect_options(
+ effect: object,
+ effect_options: Mapping[str, object] | None = None,
+) -> dict[str, object]:
+ """Return the effective option values encoded by one registry request."""
+ canonical, normalized_options = normalize_animation_effect_request(
+ effect,
+ effect_options,
+ allow_none=False,
+ allow_modes=False,
+ )
+ assert canonical is not None
+ row = _animation_row_for_options(canonical, normalized_options)
+ errors: list[str] = []
+ filter_name = _row_filter(
+ row,
+ str(NATIVE_ANIMATIONS[canonical]['presetClass']),
+ errors,
+ )
+ effective = _read_effect_options(
+ row,
+ canonical,
+ filter_name,
+ errors,
+ )
+ if errors:
+ raise RuntimeError(
+ f'animation effect {canonical!r} option model failed: '
+ + '; '.join(errors)
+ )
+ return effective
+
+
def main() -> None:
"""Run the CLI entry point."""
parser = argparse.ArgumentParser(
diff --git a/skills/ppt-master/scripts/pptx_to_svg.py b/skills/ppt-master/scripts/pptx_to_svg.py
index d0d1e404..8668854f 100644
--- a/skills/ppt-master/scripts/pptx_to_svg.py
+++ b/skills/ppt-master/scripts/pptx_to_svg.py
@@ -42,6 +42,14 @@ from pptx_to_svg.converter import ConvertOptions
configure_utf8_stdio()
+def _diagnostic_preview(message: str, limit: int = 240) -> str:
+ """Return one compact CLI preview while the report retains full detail."""
+ compact = " ".join(message.split())
+ if len(compact) <= limit:
+ return compact
+ return compact[: limit - 3].rstrip() + "..."
+
+
def _reconstruction_only_graphics(result: object) -> list[tuple[int, str]]:
"""Return slide/object labels for generated placeholders."""
artifacts = getattr(result, "flat_slides", None) or getattr(result, "slides", [])
@@ -165,7 +173,8 @@ def main() -> int:
if shape:
location = f"{location}, {shape}" if location else shape
print(
- f" {location or 'package'}: {item.code}: {item.message}",
+ f" {location or 'package'}: {item.code}: "
+ f"{_diagnostic_preview(item.message)}",
file=sys.stderr,
)
if len(result.diagnostics) > 20:
diff --git a/skills/ppt-master/scripts/pptx_to_svg/animation_import.py b/skills/ppt-master/scripts/pptx_to_svg/animation_import.py
new file mode 100644
index 00000000..31bc43de
--- /dev/null
+++ b/skills/ppt-master/scripts/pptx_to_svg/animation_import.py
@@ -0,0 +1,287 @@
+"""Import the finite PPT Master-owned object-animation contract.
+
+The importer deliberately projects only canonical effect identity, pane order,
+Start trigger, duration, relative delay, and one top-level SVG group target.
+Everything else remains an explicit source-preservation boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from xml.etree import ElementTree as ET
+
+from pptx_animations import (
+ AnimationRowSummary,
+ effective_animation_effect_options,
+ read_slide_animation_sequence,
+ validate_generated_animation_xml,
+)
+
+from .ooxml_loader import OoxmlPackage, SlideRef
+
+
+_SVG_NS = "http://www.w3.org/2000/svg"
+_UNSUPPORTED_TIMING_TAGS = frozenset(
+ {
+ "audio",
+ "bldDgm",
+ "bldGraphic",
+ "bldLst",
+ "bldOleChart",
+ "bldP",
+ "cmd",
+ "video",
+ }
+)
+
+
+class AnimationImportError(ValueError):
+ """Raised when source timing exceeds the finite reversible contract."""
+
+
+@dataclass(frozen=True)
+class AnimationImport:
+ """Canonical per-group animation rows for one slide."""
+
+ groups: dict[str, dict[str, object]]
+
+
+def import_slide_animation(
+ pkg: OoxmlPackage,
+ slide: SlideRef,
+ *,
+ slide_svg: str,
+) -> AnimationImport | None:
+ """Read one exact generated object-animation sequence into sidecar rows."""
+ slide_xml = pkg.read_part_bytes(slide.part.path)
+ if slide_xml is None:
+ raise AnimationImportError(
+ f"source slide part is missing: {slide.part.path}"
+ )
+ return read_animation_config(slide_xml, slide_svg)
+
+
+def read_animation_config(
+ slide_xml: str | bytes,
+ slide_svg: str,
+) -> AnimationImport | None:
+ """Read one exact generated object-animation sequence from XML and SVG."""
+ data = slide_xml.encode("utf-8") if isinstance(slide_xml, str) else slide_xml
+ if not _contains_timing(data):
+ return None
+
+ try:
+ summary = read_slide_animation_sequence(
+ data,
+ require_supported_effects=True,
+ )
+ except ValueError as exc:
+ raise AnimationImportError(str(exc)) from exc
+ if summary.timing_count != 1:
+ raise AnimationImportError(
+ "object animation requires exactly one effective root p:timing"
+ )
+ if not summary.rows:
+ raise AnimationImportError(
+ "p:timing contains no supported object-animation rows"
+ )
+ if summary.audio_target_ids:
+ raise AnimationImportError(
+ "media playback and animation sounds are outside the finite "
+ "object-animation read-back contract"
+ )
+ unsupported_tags = _unsupported_timing_tags(data)
+ if unsupported_tags:
+ raise AnimationImportError(
+ "unsupported timing feature(s): " + ", ".join(unsupported_tags)
+ )
+
+ group_id_by_shape_id = _top_level_shape_group_index(slide_svg)
+ delays = _relative_delays(summary.rows)
+ expected_targets: list[dict[str, object]] = []
+ rows_by_group: dict[str, list[dict[str, object]]] = {}
+
+ for order, (row, delay_ms) in enumerate(
+ zip(summary.rows, delays),
+ 1,
+ ):
+ if row.effect is None or row.duration_ms is None:
+ raise AnimationImportError(
+ f"animation row {order} has no exact registry effect or duration"
+ )
+ group_id = _resolve_group_id(
+ group_id_by_shape_id,
+ row.shape_id,
+ label=f"animation row {order} target",
+ )
+ trigger_group_id = None
+ if row.trigger_shape_id is not None:
+ trigger_group_id = _resolve_group_id(
+ group_id_by_shape_id,
+ row.trigger_shape_id,
+ label=f"animation row {order} trigger",
+ )
+
+ sidecar_row: dict[str, object] = {
+ "effect": row.effect,
+ "duration": row.duration_ms / 1000.0,
+ "delay": delay_ms / 1000.0,
+ "order": order,
+ "trigger": row.trigger,
+ }
+ expected_target: dict[str, object] = {
+ "shape_id": row.shape_id,
+ "delay_ms": delay_ms,
+ "effect": row.effect,
+ "duration": row.duration_ms / 1000.0,
+ "trigger": row.trigger,
+ }
+ effect_options = dict(row.effect_options)
+ try:
+ default_options = effective_animation_effect_options(row.effect)
+ except ValueError:
+ default_options = None
+ if effect_options != default_options:
+ sidecar_row["effect_options"] = effect_options
+ expected_target["effect_options"] = effect_options
+ if row.trigger_shape_id is not None:
+ expected_target["trigger_shape_id"] = row.trigger_shape_id
+ sidecar_row["trigger_shape"] = trigger_group_id
+ expected_targets.append(expected_target)
+ rows_by_group.setdefault(group_id, []).append(sidecar_row)
+
+ try:
+ validate_generated_animation_xml(data, expected_targets)
+ except ValueError as exc:
+ raise AnimationImportError(str(exc)) from exc
+
+ groups: dict[str, dict[str, object]] = {}
+ for group_id, rows in rows_by_group.items():
+ groups[group_id] = (
+ rows[0]
+ if len(rows) == 1
+ else {"effects": rows}
+ )
+ return AnimationImport(groups=groups)
+
+
+def _contains_timing(slide_xml: bytes) -> bool:
+ """Return whether any selected or fallback branch contains p:timing."""
+ try:
+ root = ET.fromstring(slide_xml)
+ except ET.ParseError as exc:
+ raise AnimationImportError(f"invalid slide XML: {exc}") from exc
+ return any(_local_name(node.tag) == "timing" for node in root.iter())
+
+
+def _unsupported_timing_tags(slide_xml: bytes) -> tuple[str, ...]:
+ """Return timing features that the finite sidecar projection cannot own."""
+ root = ET.fromstring(slide_xml)
+ found = {
+ _local_name(node.tag)
+ for node in root.iter()
+ if _local_name(node.tag) in _UNSUPPORTED_TIMING_TAGS
+ }
+ return tuple(sorted(found))
+
+
+def _top_level_shape_group_index(slide_svg: str) -> dict[int, tuple[str, ...]]:
+ """Index direct slide-local SVG group anchors by source shape id."""
+ try:
+ root = ET.fromstring(slide_svg)
+ except ET.ParseError as exc:
+ raise AnimationImportError(f"invalid reconstructed slide SVG: {exc}") from exc
+
+ groups: dict[int, list[str]] = {}
+ group_id_counts: dict[str, int] = {}
+ for child in list(root):
+ if child.tag != f"{{{_SVG_NS}}}g":
+ continue
+ if child.get("data-pptx-shape-scope") != "slide":
+ continue
+ raw_shape_id = child.get("data-pptx-shape-id") or ""
+ if not raw_shape_id.isdigit() or int(raw_shape_id) <= 0:
+ continue
+ group_id = child.get("id") or ""
+ if not group_id.strip():
+ continue
+ shape_id = int(raw_shape_id)
+ groups.setdefault(shape_id, []).append(group_id)
+ group_id_counts[group_id] = group_id_counts.get(group_id, 0) + 1
+
+ return {
+ shape_id: (
+ tuple(group_ids)
+ if (
+ len(group_ids) == 1
+ and group_id_counts.get(group_ids[0]) == 1
+ )
+ else ()
+ )
+ for shape_id, group_ids in groups.items()
+ }
+
+
+def _resolve_group_id(
+ group_id_by_shape_id: dict[int, tuple[str, ...]],
+ shape_id: int,
+ *,
+ label: str,
+) -> str:
+ group_ids = group_id_by_shape_id.get(shape_id, ())
+ if len(group_ids) != 1:
+ raise AnimationImportError(
+ f"{label} shape {shape_id} must map to exactly one unique "
+ f"top-level slide SVG group; found {group_ids or 'none'}"
+ )
+ return group_ids[0]
+
+
+def _relative_delays(rows: tuple[AnimationRowSummary, ...]) -> tuple[int, ...]:
+ """Invert the native writer's absolute main-sequence offsets."""
+ delays: list[int] = []
+ previous_start_ms = 0
+ previous_duration_ms = 0
+ has_previous = False
+ for index, row in enumerate(rows, 1):
+ if row.playback_duration_ms is None:
+ raise AnimationImportError(
+ f"animation row {index} has no exact playback duration"
+ )
+ if row.trigger_shape_id is not None or row.trigger == "on-click":
+ base_ms = 0
+ elif row.trigger == "with-previous":
+ base_ms = previous_start_ms if has_previous else 0
+ elif row.trigger == "after-previous":
+ base_ms = (
+ previous_start_ms + previous_duration_ms
+ if has_previous
+ else 0
+ )
+ else:
+ raise AnimationImportError(
+ f"animation row {index} has unsupported trigger {row.trigger!r}"
+ )
+ delay_ms = row.offset_ms - base_ms
+ if delay_ms < 0:
+ raise AnimationImportError(
+ f"animation row {index} has a negative reconstructed delay"
+ )
+ delays.append(delay_ms)
+ if row.trigger_shape_id is None:
+ previous_start_ms = row.offset_ms
+ previous_duration_ms = row.playback_duration_ms
+ has_previous = True
+ return tuple(delays)
+
+
+def _local_name(tag: str) -> str:
+ return tag.rsplit("}", 1)[-1]
+
+
+__all__ = [
+ "AnimationImport",
+ "AnimationImportError",
+ "import_slide_animation",
+ "read_animation_config",
+]
diff --git a/skills/ppt-master/scripts/pptx_to_svg/converter.py b/skills/ppt-master/scripts/pptx_to_svg/converter.py
index 697f8ff3..71a7314d 100644
--- a/skills/ppt-master/scripts/pptx_to_svg/converter.py
+++ b/skills/ppt-master/scripts/pptx_to_svg/converter.py
@@ -29,6 +29,10 @@ from svg_to_pptx.animation_config import (
validate_transition_config,
)
+from .animation_import import (
+ AnimationImportError,
+ import_slide_animation,
+)
from .color_resolver import ColorPalette
from .emu_units import NS
from .import_diagnostics import ImportDiagnostic, append_diagnostic
@@ -350,7 +354,7 @@ def convert_pptx_to_svg(
# rendered alongside when needed.
primary_mode = "layered" if emit_layered else "flat"
for slide in pkg.iter_slides():
- _read_back_slide_motion(
+ _read_back_slide_transition(
pkg,
slide,
result,
@@ -376,6 +380,13 @@ def convert_pptx_to_svg(
inheritance_mode=primary_mode,
)
result.slides.append(artifact)
+ _read_back_slide_animation(
+ pkg,
+ slide,
+ artifact,
+ result,
+ options,
+ )
if emit_layered and emit_flat:
for slide in pkg.iter_slides():
slide_theme = pkg.resolve_theme(slide.master) or default_theme
@@ -409,13 +420,13 @@ def convert_pptx_to_svg(
return result
-def _read_back_slide_motion(
+def _read_back_slide_transition(
pkg: OoxmlPackage,
slide: SlideRef,
result: ConvertResult,
options: ConvertOptions,
) -> None:
- """Recover supported transitions and diagnose remaining motion."""
+ """Recover one supported slide transition into the sidecar."""
try:
transition = import_slide_transition(
pkg,
@@ -456,27 +467,50 @@ def _read_back_slide_motion(
)
result.animation_media_files[filename] = payload
- if slide.part.xml.find("p:timing", NS) is None:
- return
- message = (
- "Source slide contains object animation timing that was not "
- "reconstructed in the SVG workspace"
- )
- if options.strict:
- raise ValueError(message)
- append_diagnostic(
- result.diagnostics,
- ImportDiagnostic(
- code="animation-not-reconstructed",
- message=message,
- fallback=(
- "keep the source PPTX for direct native preservation or "
- "author the corresponding animations.json sidecar"
+
+
+def _read_back_slide_animation(
+ pkg: OoxmlPackage,
+ slide: SlideRef,
+ artifact: SlideArtifact,
+ result: ConvertResult,
+ options: ConvertOptions,
+) -> None:
+ """Recover one finite object-animation sequence into the sidecar."""
+ try:
+ animation = import_slide_animation(
+ pkg,
+ slide,
+ slide_svg=artifact.svg,
+ )
+ except AnimationImportError as exc:
+ message = f"Object animation timing was not reconstructed: {exc}"
+ if options.strict:
+ raise ValueError(message) from exc
+ append_diagnostic(
+ result.diagnostics,
+ ImportDiagnostic(
+ code="animation-not-reconstructed",
+ message=message,
+ fallback=(
+ "keep this timing in the source PPTX through direct "
+ "native preservation"
+ ),
+ part_path=slide.part.path,
+ slide_index=slide.index,
),
- part_path=slide.part.path,
- slide_index=slide.index,
- ),
- )
+ )
+ return
+ if animation is None:
+ return
+
+ slides = result.animation_config["slides"]
+ if not isinstance(slides, dict):
+ raise RuntimeError("internal animations.json slides must be an object")
+ slide_config = slides.setdefault(f"slide_{slide.index:02d}", {})
+ if not isinstance(slide_config, dict):
+ raise RuntimeError("internal animations.json slide row must be an object")
+ slide_config["groups"] = animation.groups
def _convert_slide(