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(svg_to_pptx): add semantic 'auto' animation mode as default

hugohe3cd129c928d9d
diff --git a/docs/faq.md b/docs/faq.md
index d3ac126e..5eac6b84 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -84,7 +84,7 @@ If your workflow specifically requires Excel-driven data editing, manually creat
## Q: Can I change page transitions and element animations?
-Yes. Page transitions (`fade` 0.4s by default) and per-element entrance animations (`mixed` effect with `after-previous` cascade by default) are both controlled by `svg_to_pptx.py` flags — `-t/--transition` for page-level and `-a/--animation` for element-level. Common one-liners:
+Yes. Page transitions (`fade` 0.4s by default) and per-element entrance animations (`auto` effect with `after-previous` cascade by default — effect mapped from each group's SVG id, with image-like ids cycling a visual pool for variation) are both controlled by `svg_to_pptx.py` flags — `-t/--transition` for page-level and `-a/--animation` for element-level. Common one-liners:
```bash
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index 8dd88a12..d791f471 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -7,7 +7,7 @@ PPT Master 导出的 PPTX 同时支持**页间转场**(page transition)与**
| 层级 | 默认 | 原因 |
|---|---|---|
| 页间转场 | `fade`,0.4 秒 | 适合大多数 deck 的中性基线 |
-| 页内元素动画 | `mixed` 效果 + `after-previous` 触发,0.4 秒时长 + 0.5 秒间隔 | 进入页面后元素自动按顺序级联入场,零交互即可看到完整动画过程,最能体现 deck 的动画能力 |
+| 页内元素动画 | `auto` 效果 + `after-previous` 触发,0.4 秒时长 + 0.5 秒间隔 | 根据每个 group 的 SVG id 映射效果:信息密集元素稳定映射(chart→wipe、card-/step-/pillar-→fly、title/takeaway→fade),图片类 id(`hero` / `figure-` / `image` / `img-` / `kpi`)在更丰富的视觉池(zoom / dissolve / circle / box / diamond / wheel)中循环以产生 deck 内变化,未命中的 id 在 fade/wipe/fly/zoom 间循环。进入页面后元素自动级联入场,零交互即可看到完整动画过程 |
修改设置只需对同一份 `svg_output/`(或 `svg_final/`)重跑 `svg_to_pptx.py`,无需重新跑 LLM。如要彻底关闭页内动画,加 `-a none`。
@@ -79,14 +79,14 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
## 页内元素动画
-默认开启(`mixed` 效果 + `after-previous` 触发)。共有三种 Start 模式,**与 PowerPoint 动画窗格的 Start 下拉菜单一一对应**:
+默认开启(`auto` 效果 + `after-previous` 触发)。共有三种 Start 模式,**与 PowerPoint 动画窗格的 Start 下拉菜单一一对应**:
- **`on-click`**(单击时)—— 进入页面 → 第一次点击显示第一个语义组,后续每次点击按 z-order 显示下一个组。适合现场演讲,演讲者控制节奏。与 `--recorded-narration` 互斥,因为带旁白的视频导出需要无点击播放。
- **`with-previous`**(与上一动画同时)—— 所有组在进入页面时一起入场,并行播放各自的入场动画。`--animation-stagger` 不生效。
- **`after-previous`**(默认,在上一动画之后)—— 第一组进入页面时入场,后续组在前一个结束后接着出现,并按 `--animation-stagger` 增加额外间隔。适合展厅循环、录屏走查,或者只是想看流动效果不想点击。
```bash
-# 默认即开启:mixed 效果 + after-previous 触发,无需任何参数
+# 默认即开启:auto 效果 + after-previous 触发,无需任何参数
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
# 关闭页内动画
@@ -106,16 +106,17 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed \
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger with-previous
```
-22 种单一效果:`appear`、`fade`、`fly`、`cut`、`zoom`、`wipe`、`split`、`blinds`、`checkerboard`、`dissolve`、`random_bars`、`peek`、`wheel`、`box`、`circle`、`diamond`、`plus`、`strips`、`wedge`、`stretch`、`expand`、`swivel`。再加两种自动轮换模式:
+22 种单一效果:`appear`、`fade`、`fly`、`cut`、`zoom`、`wipe`、`split`、`blinds`、`checkerboard`、`dissolve`、`random_bars`、`peek`、`wheel`、`box`、`circle`、`diamond`、`plus`、`strips`、`wedge`、`stretch`、`expand`、`swivel`。再加三种自动模式:
-- `mixed` — 确定性轮换。每页第一个动画组使用 `fade`,后续组在整份 deck 范围内按精选效果池连续轮换。
-- `random` — 在同一效果池中随机抽取。
+- `auto`(默认)—— 按 group 的 SVG id 映射效果。信息密集元素稳定映射:`chart` / `table` / `legend` / `timeline` / `track` → `wipe`;`card-*` / `pillar-*` / `item-*` / `step-*` / `stage-*` / `tier-*` / `principle-*` → `fly`;`title` / `chapter-*` / `section-*` / `cover-*` / `tagline` / `subtitle` → `fade`;`takeaway` / `callout` / `quote` / `source` / `conclusion` / `note` → `fade`。图片类 id `hero` / `figure-*` / `image` / `img-*` / `kpi` 则在更丰富的视觉池(`zoom` / `dissolve` / `circle` / `box` / `diamond` / `wheel`)中循环,使多张图片在 deck 内呈现不同入场。未命中的 id 在 `fade` / `wipe` / `fly` / `zoom` 之间循环。
+- `mixed`(旧逻辑)—— 确定性轮换。每页第一个动画组使用 `fade`,后续组在整份 deck 范围内按 16 效果池(`blinds` / `checkerboard` / `dissolve` / `fly` / `cut` / `random_bars` / `box` / `split` / `strips` / `wedge` / `wheel` / `wipe` / `expand` / `fade` / `swivel` / `zoom`)连续轮换。保留以兼容旧配置。
+- `random` —— 在旧的 16 效果池中随机抽取。
-效果池排除了 `appear`,因为它没有可见动画过程。
+所有轮换池都排除了 `appear`,因为它没有可见动画过程。
参数:
-- `-a/--animation` — 效果名、`mixed`、`random` 或 `none`。默认 `mixed`。
+- `-a/--animation` — 效果名、`auto`、`mixed`、`random` 或 `none`。默认 `auto`。
- `--animation-trigger` — Start 模式(与 PowerPoint 一致):`on-click`、`with-previous`、`after-previous`(默认)。
- `--animation-duration` — 单个元素入场秒数,默认 `0.4`。
- `--animation-stagger` — `after-previous` 模式下两组之间的额外间隔(秒,默认 `0.5`)。其他模式忽略。
@@ -129,7 +130,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger w
每页建议 **3–8 个内容组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度,与是否启用动画无关,都能改善编辑体验。
-**装饰类分组自动跳过。** 顶层中看起来属于页面装饰的组(背景、页头页脚、装饰元素、水印、页码)会被排除在点击序列外,跟随页面立即显示。识别基于 `id`:按 `-` 和 `_` 切分后,若任一 token 命中 `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum`,则视为装饰类。会自动跳过的例子:`<g id="background">`、`<g id="bg-texture">`、`<g id="cover-footer">`、`<g id="p03-header">`、`<g id="bottom-decor">`、`<g id="watermark">`。仍会动画的例子:`<g id="card-1">`、`<g id="cover-title">`、`<g id="step-discover">`。**不要为了规避动画去掉 `<g>` 包裹**——保留分组(PowerPoint 框选需要),只要给个合适的 id 即可。
+**装饰类分组自动跳过。** 顶层中看起来属于页面装饰的组(背景、页头页脚、装饰元素、水印、页码、导航、logo、分隔线)会被排除在点击序列外,跟随页面立即显示。识别基于 `id`:按 `-` 和 `_` 切分后,若任一 token 命中 `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum` / `nav` / `logo` / `rule`,则视为装饰类。会自动跳过的例子:`<g id="background">`、`<g id="bg-texture">`、`<g id="cover-footer">`、`<g id="p03-header">`、`<g id="bottom-decor">`、`<g id="watermark">`、`<g id="nav">`、`<g id="logo-area">`、`<g id="column-rule">`。仍会动画的例子:`<g id="card-1">`、`<g id="cover-title">`、`<g id="step-discover">`、`<g id="timeline-track">`。**不要为了规避动画去掉 `<g>` 包裹**——保留分组(PowerPoint 框选需要),只要给个合适的 id 即可。
**扁平 SVG 的回退逻辑**(顶层没有 `<g>`,只有裸 `<rect>` / `<text>` / `<path>`):
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 97fd44a5..1bad1cce 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -84,7 +84,7 @@ PPT Master 本身免费开源,唯一的成本来自你自己的 AI 模型用
## Q: 页面切换和元素动画可以调吗?
-可以。页间转场(默认 `fade` 0.4s)和页内元素入场动画(默认 `mixed` 效果 + `after-previous` 自动级联)都通过 `svg_to_pptx.py` 的参数控制——`-t/--transition` 控制页级,`-a/--animation` 控制元素级。常用一行命令:
+可以。页间转场(默认 `fade` 0.4s)和页内元素入场动画(默认 `auto` 效果 + `after-previous` 自动级联,根据每个 group 的 SVG id 自动映射效果——图片类 id 在视觉池中循环以产生 deck 内变化)都通过 `svg_to_pptx.py` 的参数控制——`-t/--transition` 控制页级,`-a/--animation` 控制元素级。常用一行命令:
```bash
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 0f66ca9d..87bfcab5 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -457,7 +457,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
**Optional animation flags** (the defaults already enable rich entrance animations — adjust only when the user asks for something different):
- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`.
-- `-a <effect>` — per-element entrance animation. Default `mixed` (auto-vary across the deck). Pass `none` to disable, or pick a specific effect like `fade`. Requires top-level `<g id="...">` groups (already required by Executor).
+- `-a <effect>` — per-element entrance animation. Default `auto` (map effect from group id: chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade; image-like ids `hero` / `figure-` / `image` / `img-` / `kpi` cycle a richer pool — zoom / dissolve / circle / box / diamond / wheel — so multiple images vary across the deck). Pass `none` to disable, a specific effect like `fade`, or `mixed` for the legacy 16-effect cycle. Requires top-level `<g id="...">` groups (already required by Executor).
- `--animation-trigger {on-click,with-previous,after-previous}` — Start mode (matches PowerPoint's animation-pane Start dropdown). Default `after-previous` (click-free cascade; pace via `--animation-stagger`). Use `on-click` for presenter-paced reveals, or `with-previous` for all-at-once.
- `--animation-config <path>` — optional object-level sidecar. Default: `<project_path>/animations.json` when present.
- `--auto-advance <seconds>` — kiosk-style auto-play.
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 56f8285e..936d2c65 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -7,7 +7,7 @@ PPT Master's exported PPTX supports **page transitions** (slide-to-slide) and **
| Layer | Default | Why |
|---|---|---|
| Page transition | `fade`, 0.4s | Calm baseline that suits most decks |
-| Per-element animation | `mixed` effect + `after-previous` trigger, 0.4s duration + 0.5s stagger | Groups cascade in automatically on slide entry — zero interaction, with a measured pace for typical content decks |
+| Per-element animation | `auto` effect + `after-previous` trigger, 0.4s duration + 0.5s stagger | Effects are mapped from group id (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (`hero` / `figure-` / `image` / `img-` / `kpi`) cycle a richer visual pool (zoom / dissolve / circle / box / diamond / wheel) so multiple images vary across the deck; unmatched ids cycle a small fade/wipe/fly/zoom pool. Cascades automatically on slide entry — zero interaction |
To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` (or `svg_final/`) — no need to rerun the LLM. To turn per-element animation off entirely, pass `-a none`.
@@ -79,14 +79,14 @@ Flags:
## Per-Element Animations
-Enabled by default (`mixed` effect + `after-previous` trigger). Three Start modes are available — these mirror PowerPoint's animation-pane "Start" dropdown:
+Enabled by default (`auto` effect + `after-previous` trigger). Three Start modes are available — these mirror PowerPoint's animation-pane "Start" dropdown:
- **`on-click`** — entering a slide → first click reveals the first semantic group; each subsequent click reveals the next group in z-order. Suits live presentations where the speaker paces reveals. Forbidden with `--recorded-narration` because video-ready exports need click-free playback.
- **`with-previous`** — all groups start together on slide entry, playing their entrance animation in parallel. Stagger ignored.
- **`after-previous`** (default) — first group fires on slide entry, subsequent groups cascade after the previous one finishes, with `--animation-stagger` extra spacing. Suits kiosk playback, recorded walkthroughs, or anyone who wants visual flow without clicking.
```bash
-# Default behavior (no flags needed): mixed effect + after-previous cascade
+# Default behavior (no flags needed): auto effect + after-previous cascade
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
# Disable per-element animation entirely
@@ -106,16 +106,17 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed \
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger with-previous
```
-22 single effects: `appear`, `fade`, `fly`, `cut`, `zoom`, `wipe`, `split`, `blinds`, `checkerboard`, `dissolve`, `random_bars`, `peek`, `wheel`, `box`, `circle`, `diamond`, `plus`, `strips`, `wedge`, `stretch`, `expand`, `swivel`. Plus two auto-vary modes:
+22 single effects: `appear`, `fade`, `fly`, `cut`, `zoom`, `wipe`, `split`, `blinds`, `checkerboard`, `dissolve`, `random_bars`, `peek`, `wheel`, `box`, `circle`, `diamond`, `plus`, `strips`, `wedge`, `stretch`, `expand`, `swivel`. Plus three auto-vary modes:
-- `mixed` — deterministic. The first animated group on each slide uses `fade`; later groups cycle through a curated visible-effect pool across the deck.
-- `random` — samples from the same pool.
+- `auto` (default) — map effect from the group's SVG id. Information-dense elements get a single stable effect: `chart` / `table` / `legend` / `timeline` / `track` → `wipe`; `card-*` / `pillar-*` / `item-*` / `step-*` / `stage-*` / `tier-*` / `principle-*` → `fly`; `title` / `chapter-*` / `section-*` / `cover-*` / `tagline` / `subtitle` → `fade`; `takeaway` / `callout` / `quote` / `source` / `conclusion` / `note` → `fade`. Image-like ids `hero` / `figure-*` / `image` / `img-*` / `kpi` instead cycle a richer visual pool (`zoom` / `dissolve` / `circle` / `box` / `diamond` / `wheel`) so multiple images vary across the deck. Unmatched ids cycle through `fade` / `wipe` / `fly` / `zoom`.
+- `mixed` (legacy) — deterministic. The first animated group on each slide uses `fade`; later groups cycle through a 16-effect pool (`blinds` / `checkerboard` / `dissolve` / `fly` / `cut` / `random_bars` / `box` / `split` / `strips` / `wedge` / `wheel` / `wipe` / `expand` / `fade` / `swivel` / `zoom`) across the deck. Kept for backward compatibility.
+- `random` — samples from the legacy 16-effect pool.
-The pool excludes `appear` because it has no visible motion.
+`appear` is excluded from every variation pool because it has no visible motion.
Flags:
-- `-a/--animation` — effect name, `mixed`, `random`, or `none`. Default: `mixed`.
+- `-a/--animation` — effect name, `auto`, `mixed`, `random`, or `none`. Default: `auto`.
- `--animation-trigger` — Start mode (matches PowerPoint): `on-click`, `with-previous`, or `after-previous` (default).
- `--animation-duration` — per-element entrance seconds, default `0.4`.
- `--animation-stagger` — gap between elements in `after-previous` mode (seconds, default `0.5`). Ignored otherwise.
@@ -129,7 +130,7 @@ Per-element animations are anchored on **top-level `<g id="...">` content groups
Aim for **3–8 content groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.
-**Chrome groups skip the cascade automatically.** Top-level groups that look like page chrome (background, header/footer, decorations, watermark, page number) are excluded from the click sequence and appear together with the slide. Detection is done on the `id`: after splitting on `-` and `_`, if any token matches `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum`, the group is treated as chrome. Examples that auto-skip: `<g id="background">`, `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="watermark">`. Examples that still animate: `<g id="card-1">`, `<g id="cover-title">`, `<g id="step-discover">`. Don't strip the `<g>` wrapper to avoid animation — keep it (PowerPoint group-select needs it) and just name it appropriately.
+**Chrome groups skip the cascade automatically.** Top-level groups that look like page chrome (background, header/footer, decorations, watermark, page number, nav, logo, dividing rule) are excluded from the click sequence and appear together with the slide. Detection is done on the `id`: after splitting on `-` and `_`, if any token matches `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum` / `nav` / `logo` / `rule`, the group is treated as chrome. Examples that auto-skip: `<g id="background">`, `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="watermark">`, `<g id="nav">`, `<g id="logo-area">`, `<g id="column-rule">`. Examples that still animate: `<g id="card-1">`, `<g id="cover-title">`, `<g id="step-discover">`, `<g id="timeline-track">`. Don't strip the `<g>` wrapper to avoid animation — keep it (PowerPoint group-select needs it) and just name it appropriately.
**Fallback for flat SVGs** (no top-level `<g>` wrappers, only raw `<rect>` / `<text>` / `<path>` at the root):
@@ -154,7 +155,7 @@ Executors should wrap logical sections in `<g id>` regardless of whether you pla
| Auto-play | `--auto-advance 5` |
| Disable element animation | `-a none` |
| Switch to on-click trigger | `--animation-trigger on-click` |
-| Use a single effect instead of mixed | `--animation fade` |
+| Use a single effect instead of auto | `--animation fade` |
| All groups animate together | `--animation-trigger with-previous` |
| Slower per-element reveal | `--animation-duration 0.5` |
| Wider gap in after-previous | `--animation-stagger 0.7` |
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index c59fee38..7846d7da 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -251,7 +251,7 @@ Wrap logically related elements in top-level `<g id="...">` groups. Produces Pow
**Animation-ready rule**: direct children of `<svg>` should be semantic groups, not raw drawing atoms. Aim for **3–8 top-level content `<g id>` groups per slide** (the 3–8 budget excludes page chrome — see below); each content group becomes one entrance step under the chosen `--animation-trigger` mode (one click in `on-click`, one cascade slot in `after-previous`, parallel in `with-previous`).
-**Chrome groups are excluded automatically.** The exporter treats top-level groups whose id contains chrome tokens as page chrome and skips them in the animation sequence — they appear together with the slide. Tokens (matched against id after splitting on `-` / `_`): `background`, `bg`, `decoration` / `decorations` / `decor`, `header`, `footer`, `chrome`, `watermark`, `pagenumber` / `pagenum` / `page-number`. So `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">` all skip animation while keeping their `<g>` wrapper for editing/grouping. Use these naming conventions for chrome — do **not** strip the `<g>` wrapper.
+**Chrome groups are excluded automatically.** The exporter treats top-level groups whose id contains chrome tokens as page chrome and skips them in the animation sequence — they appear together with the slide. Tokens (matched against id after splitting on `-` / `_`): `background`, `bg`, `decoration` / `decorations` / `decor`, `header`, `footer`, `chrome`, `watermark`, `pagenumber` / `pagenum` / `page-number`, `nav`, `logo`, `rule`. So `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="nav">`, `<g id="logo-area">`, `<g id="column-rule">` all skip animation while keeping their `<g>` wrapper for editing/grouping. Use these naming conventions for chrome — do **not** strip the `<g>` wrapper.
**What to group**:
@@ -312,7 +312,7 @@ python3 scripts/svg_to_pptx.py <project_path>
**Optional animation flags** (only when the user asks):
- `-t <effect>` — page transition (`fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`; default `fade`)
-- `-a <effect>` — per-element entrance animation (`fade` / `mixed` / `random` / one of 22 named effects / `none`; default `mixed`). Anchors on top-level `<g id="...">` groups.
+- `-a <effect>` — per-element entrance animation (`fade` / `auto` / `mixed` / `random` / one of 22 named effects / `none`; default `auto`, maps effect from group id — image-like ids cycle zoom/dissolve/circle/box/diamond/wheel, other matches map to a single effect, unmatched ids cycle fade/wipe/fly/zoom). Anchors on top-level `<g id="...">` groups.
- `--animation-trigger {on-click,with-previous,after-previous}` — Start mode matching PowerPoint's animation-pane Start dropdown. Default `after-previous` (cascade on slide entry; pace via `--animation-stagger <seconds>`); `on-click` advances per click; `with-previous` plays all groups together.
- `--animation-config <path>` — optional object-level animation sidecar. Default: `<project>/animations.json` when present.
- `--auto-advance <seconds>` — kiosk-style auto-play
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index c23c57cd..2c4ea366 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -79,7 +79,8 @@ Behavior:
- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)
- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timings
- Flat SVG roots without top-level groups fall back to at most 8 visible primitives; beyond that, animation is skipped on the slide
-- `mixed` is deterministic: the first animated group on each slide uses `fade`, then later groups cycle through a curated visible-effect pool across the whole deck; `random` samples from that same pool
+- `auto` (default) maps effect from the group's SVG id: information-dense elements get a single stable effect (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (hero/figure-/image/img-/kpi) cycle through a richer visual pool (zoom/dissolve/circle/box/diamond/wheel) so multiple images vary across the deck; unmatched ids cycle through a fade/wipe/fly/zoom fallback pool
+- `mixed` (legacy) is deterministic: the first animated group on each slide uses `fade`, then later groups cycle through a larger 16-effect pool across the whole deck; `random` samples from that same legacy pool
- `--animation-duration` controls per-element entrance length (default `0.4`); `--animation-stagger` adds gap between elements in `after-previous` mode (default `0.5`)
- Optional object-level overrides live in `<project>/animations.json` or a path passed via `--animation-config`; build and validate them with `animation_config.py scaffold|validate`
diff --git a/skills/ppt-master/scripts/pptx_animations.py b/skills/ppt-master/scripts/pptx_animations.py
index 857fa836..e03533ef 100644
--- a/skills/ppt-master/scripts/pptx_animations.py
+++ b/skills/ppt-master/scripts/pptx_animations.py
@@ -20,8 +20,17 @@ Supported entrance animations (per-element):
Animation modes used by the builder:
- single effect name (one of the above) — apply to every element
- - 'mixed' — first element fades, the rest cycle through a curated visible pool
- - 'random' — pick a random effect from the same visible pool per element
+ - 'auto' — pick effect from the group's SVG id. Image-like ids
+ (hero / figure- / image / img- / kpi) cycle through a
+ visual pool (zoom / dissolve / circle / box / diamond /
+ wheel) so multiple images vary across the deck. Other
+ semantic matches map to a single stable effect
+ (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade).
+ Unmatched ids cycle through a small modern pool
+ (fade / wipe / fly / zoom).
+ - 'mixed' — legacy mode: first element fades, the rest cycle through a
+ larger curated visible pool (kept for backward compatibility).
+ - 'random' — pick a random effect from the legacy pool per element
Dependencies: None (pure XML generation)
@@ -162,6 +171,55 @@ _MIXED_POOL = [
'wipe', 'expand', 'fade', 'swivel', 'zoom',
]
+# Small modern pool used by 'auto' mode when the group id matches no semantic
+# pattern. Restricted to four widely supported, restrained effects so the
+# fallback cycle never produces PowerPoint-era visuals.
+_AUTO_POOL = ['fade', 'wipe', 'fly', 'zoom']
+
+# Image-only diversity pool. Image-like groups (`hero`, `figure-`, `image`,
+# `img-`, `kpi`) deliberately cycle through a richer set of visual effects
+# rather than mapping to a single effect: images are visual focal points, so
+# variation is desirable on them even when surrounding information-dense
+# elements (titles, charts, lists) stay reserved. Pool members are chosen for
+# image-friendly motion — no PowerPoint-era patterns (blinds / checkerboard /
+# random_bars / wedge) that would dominate raster content.
+_IMAGE_POOL = ['zoom', 'dissolve', 'circle', 'box', 'diamond', 'wheel']
+_IMAGE_KEYWORDS: tuple[str, ...] = ('hero', 'figure-', 'image', 'img-', 'kpi')
+
+# Ordered (substring, effect) patterns consumed by 'auto' mode for non-image
+# groups. The first matching substring in the lowercased group id wins;
+# ordering matters where substrings could overlap (e.g. 'title' before 'item'
+# prevents 'item-title' from being misread as a list item). All substrings are
+# lowercase. Image-like ids are handled separately via ``_IMAGE_POOL`` because
+# they cycle rather than map to a single effect.
+_SEMANTIC_PATTERNS: list[tuple[tuple[str, ...], str]] = [
+ (('title', 'chapter-', 'section-', 'cover-', 'tagline', 'subtitle'), 'fade'),
+ (('chart', 'table', 'legend', 'timeline', 'track'), 'wipe'),
+ (('card-', 'pillar-', 'item-', 'step-', 'stage-', 'tier-',
+ 'principle-', 'q-', 'schema-'), 'fly'),
+ (('takeaway', 'callout', 'quote', 'source', 'conclusion', 'note',
+ 'try-at-home'), 'fade'),
+]
+
+
+def _semantic_effect(group_id: str | None, idx: int = 0, offset: int = 0) -> str | None:
+ """Return the effect mapped from a group id, or None if no pattern matches.
+
+ Image-like ids cycle through ``_IMAGE_POOL`` using ``idx + offset`` so the
+ same deck shows different effects across multiple images. Other semantic
+ matches return a single stable effect because information-dense elements
+ benefit from consistency, not variation.
+ """
+ if not group_id:
+ return None
+ lower = group_id.lower()
+ if any(k in lower for k in _IMAGE_KEYWORDS):
+ return _IMAGE_POOL[(idx + offset) % len(_IMAGE_POOL)]
+ for substrings, effect in _SEMANTIC_PATTERNS:
+ if any(s in lower for s in substrings):
+ return effect
+ return None
+
def create_timing_xml(
animation: str = 'fade',
@@ -504,17 +562,36 @@ def create_sequence_timing_xml(
</p:timing>'''
-def pick_animation_effect(mode: str, idx: int, offset: int = 0) -> str:
+def pick_animation_effect(
+ mode: str,
+ idx: int,
+ offset: int = 0,
+ group_id: str | None = None,
+) -> str:
"""Resolve a per-element effect name from a mode string.
- A specific animation name returns itself (no variation).
- - 'mixed': first element fixed to 'fade', rest cycle through ``_MIXED_POOL``
- plus ``offset`` (so titles stay calm while content varies across slides).
- - 'random': uniform random choice from ``_MIXED_POOL``.
+ - 'auto': map ``group_id`` to an effect. Image-like ids
+ (hero / figure- / image / img- / kpi) cycle through ``_IMAGE_POOL``
+ (zoom / dissolve / circle / box / diamond / wheel) by ``idx + offset``
+ so multiple images vary across the deck. Other semantic matches in
+ ``_SEMANTIC_PATTERNS`` return a single stable effect (chart→wipe,
+ card-/step-/pillar-→fly, title/takeaway→fade). When the id matches no
+ pattern, cycle through ``_AUTO_POOL`` (fade / wipe / fly / zoom).
+ - 'mixed' (legacy): first element fixed to 'fade', rest cycle through
+ ``_MIXED_POOL`` plus ``offset`` (so titles stay calm while content varies
+ across slides). Kept for backward compatibility with existing CLI flags
+ and animations.json sidecars.
+ - 'random' (legacy): uniform random choice from ``_MIXED_POOL``.
- Unknown mode falls back to 'fade'.
"""
if mode in ANIMATIONS:
return mode
+ if mode == 'auto':
+ semantic = _semantic_effect(group_id, idx, offset)
+ if semantic is not None:
+ return semantic
+ return _AUTO_POOL[(idx + offset) % len(_AUTO_POOL)]
if mode == 'mixed':
if idx == 0:
return 'fade'
diff --git a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py b/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
index 55f8e3b3..1361f70b 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
@@ -126,7 +126,7 @@ def load_animation_config(project_path: Path, config_path: str | None = None) ->
def _valid_animation_effect(effect: str) -> bool:
- return effect == 'none' or effect in ANIMATIONS or effect in ('mixed', 'random')
+ return effect == 'none' or effect in ANIMATIONS or effect in ('auto', 'mixed', 'random')
def _valid_transition_effect(effect: str) -> bool:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
index 8fb5438e..bb69d0f8 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
@@ -41,6 +41,7 @@ _CHROME_ID_TOKENS = frozenset({
'header', 'footer',
'chrome', 'watermark',
'pagenumber', 'pagenum',
+ 'nav', 'logo', 'rule',
})
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
index 7a4c883b..63f31649 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
@@ -210,11 +210,13 @@ def _build_sequence_targets(
for seq_idx, (_has_order, _order, _original_idx, _svg_id, group_cfg) in enumerate(ordered):
shape_id = int(group_cfg['_shape_id'])
raw_effect = group_cfg.get('effect')
- if raw_effect in ('mixed', 'random'):
- effect = pick_animation_effect(str(raw_effect), seq_idx, mixed_animation_offset)
+ if raw_effect in ('auto', 'mixed', 'random'):
+ effect = pick_animation_effect(
+ str(raw_effect), seq_idx, mixed_animation_offset, group_id=_svg_id,
+ )
else:
effect = str(raw_effect or pick_animation_effect(
- animation, seq_idx, mixed_animation_offset,
+ animation, seq_idx, mixed_animation_offset, group_id=_svg_id,
))
item_duration = _to_float(group_cfg.get('duration'), duration)
delay_seconds = _to_float(
@@ -226,6 +228,12 @@ def _build_sequence_targets(
mixed_count = 0
if animation == 'mixed':
mixed_count = sum(1 for _target in seq_targets[1:])
+ elif animation == 'auto':
+ # 'auto' accumulates a cross-slide offset so the image pool and the
+ # unmatched-id fallback rotate as the deck advances. Single-effect
+ # semantic matches (title→fade, chart→wipe etc.) are unaffected
+ # because they ignore the offset.
+ mixed_count = len(seq_targets)
return seq_targets, mixed_count
@@ -515,7 +523,7 @@ def create_pptx_with_native_svg(
slide_animation_stagger,
mixed_animation_offset,
)
- if slide_animation == 'mixed':
+ if slide_animation in ('mixed', 'auto'):
mixed_animation_offset += mixed_count
timing_xml = '\n' + create_sequence_timing_xml(
seq_targets, duration=slide_animation_duration,
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
index c6cce244..32a6bd1d 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -64,7 +64,7 @@ def main() -> None:
animation_choices = (
['none'] + (list(_ANIMATIONS.keys()) if _ANIMATIONS
else ['fade', 'fly', 'zoom', 'appear'])
- + ['mixed', 'random']
+ + ['auto', 'mixed', 'random']
)
parser = argparse.ArgumentParser(
@@ -92,14 +92,17 @@ Transition effects (-t/--transition):
Per-element entrance animation (-a/--animation, native shapes mode):
{', '.join(animation_choices)}
Notes: applied to top-level <g id="..."> SVG groups in z-order. Default is
- "mixed" (auto-vary effects per group). Start mode set by
+ "auto" (map effect from group id: chart→wipe, card-/step-/pillar-→fly,
+ title/takeaway→fade; image-like ids hero/figure-/image/img-/kpi cycle
+ zoom/dissolve/circle/box/diamond/wheel so multiple images vary across
+ the deck; unmatched ids cycle fade/wipe/fly/zoom). Start mode set by
--animation-trigger, matching PowerPoint's Start dropdown:
on-click one presenter click per group
with-previous all groups start together on slide entry
after-previous (default) cascade on slide entry;
gap = --animation-stagger seconds
- mixed uses a curated visible-effect sequence across the deck; random samples
- from the same visible-effect pool. Use "-a none" to disable.
+ mixed (legacy) cycles a larger 16-effect pool by group order;
+ random samples from the same legacy pool. Use "-a none" to disable.
Compatibility mode (enabled by default):
- Automatically generates PNG fallback images, SVG embedded as extension
@@ -188,8 +191,11 @@ Recorded narration:
parser.add_argument('-a', '--animation', type=str, choices=animation_choices,
default=None,
help='Per-element entrance animation (native shapes mode '
- 'only). Pick a single effect, "mixed" (auto-vary per '
- 'element, default), "random", or "none" to disable.')
+ 'only). Pick a single effect, "auto" (default; map '
+ 'effect from group id — image-like ids cycle a richer '
+ 'pool for visual variation, fallback cycles fade/wipe/'
+ 'fly/zoom), "mixed" (legacy 16-effect pool), "random", '
+ 'or "none" to disable.')
parser.add_argument('--animation-duration', type=non_negative_float, default=None,
help='Per-element entrance duration in seconds (default: 0.4)')
parser.add_argument('--animation-trigger', type=str,
@@ -418,7 +424,7 @@ Recorded narration:
animation_effect = (
animation_arg
if animation_arg is not None
- else animation_defaults.get('effect', 'mixed')
+ else animation_defaults.get('effect', 'auto')
)
animation = None if animation_effect == 'none' else animation_effect
animation_duration = (
diff --git a/skills/ppt-master/workflows/customize-animations.md b/skills/ppt-master/workflows/customize-animations.md
index 99eba0b6..b18c8774 100644
--- a/skills/ppt-master/workflows/customize-animations.md
+++ b/skills/ppt-master/workflows/customize-animations.md
@@ -127,8 +127,9 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
| `stretch` | Stretch entrance |
| `expand` | Expand entrance |
| `swivel` | Swivel entrance |
-| `mixed` | Deterministic varied effects across animated groups |
-| `random` | Random effect per animated group |
+| `auto` | Map effect from group id (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (hero/figure-/image/img-/kpi) cycle zoom/dissolve/circle/box/diamond/wheel for visual variation; unmatched ids cycle fade/wipe/fly/zoom |
+| `mixed` | Legacy 16-effect cycle by group order (first group fades, rest cycle the larger pool) |
+| `random` | Random effect per animated group, sampled from the legacy pool |
**Start modes**:
@@ -152,7 +153,7 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
| `animation.duration` | Slide-specific default object entrance duration |
| `animation.stagger` | Slide-specific delay between object entrances |
| `animation.trigger` | Slide-specific start mode |
-| `groups.<id>.effect` | Object-specific entrance effect, `mixed`, `random`, or `none` |
+| `groups.<id>.effect` | Object-specific entrance effect, `auto`, `mixed`, `random`, or `none` |
| `order` | Animation order only; does not change SVG layer order |
| `delay` | Extra seconds before this group starts in `after-previous` mode |
| `duration` | Per-group entrance duration in seconds; vary when semantic weight or pacing calls for it |