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
docs: surface page transitions and per-element animations
hugohe3ae380b97eb4f
diff --git a/README.md b/README.mdindex f0379be7..90863c36 100644--- a/README.md+++ b/README.md@@ -38,6 +38,8 @@ English | [中文](./README_CN.md)Drop in a PDF, DOCX, URL, or Markdown — get back a **natively editable PowerPoint** with real shapes, real text boxes, and real charts. Not images. Click anything and edit it.+> **Animations** — exported decks support **page transitions** and **per-element entrance animations** as real OOXML, not embedded video. Click-by-click cascade in PowerPoint and Keynote, no extra tooling. See [Animations & Transitions →](./docs/animations.md).+> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.>> **What you'll do**: install Python, install an AI IDE, drop in your material.@@ -236,6 +238,7 @@ Multiple backends are supported across Core / Extended / Experimental tiers. Run| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules || 🎨 | [Create a Custom Template](./skills/ppt-master/workflows/create-template.md) | Standalone workflow for building your own brand or industry template || 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |+| 🎬 | [Animations & Transitions](./docs/animations.md) | Page transitions and per-element entrance animations || 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands || 💼 | [Examples](./examples/README.md) | 22 projects, 309 pages || 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |diff --git a/README_CN.md b/README_CN.mdindex 91ecad9c..9d348da0 100644--- a/README_CN.md+++ b/README_CN.md@@ -38,6 +38,8 @@丢进一份 PDF、DOCX、网址或 Markdown,拿回一份**原生可编辑的 PowerPoint**——真正的形状、真正的文本框、真正的图表,不是图片。点击任何元素即可编辑。+> **动画** —— 导出的 deck 支持**页间转场**和**页内元素入场动画**,输出为真正的 OOXML 动画(不是嵌入视频),在 PowerPoint 和 Keynote 中按点击逐次播放,无需额外工具。详见 [转场与动画使用指南 →](./docs/zh/animations.md)。+> **运作方式** —— PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill")。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成一个真正可编辑的 `.pptx`。你不写任何代码——IDE 只是你和 AI 对话的地方。>> **你要做的**:装 Python、装一个 AI IDE、把资料放进来。@@ -240,6 +242,7 @@ OPENAI_MODEL=gpt-image-2| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 || 🎨 | [创建自定义模板](./skills/ppt-master/workflows/create-template.md) | 独立工作流,构建你自己的品牌或行业模板 || 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |+| 🎬 | [转场与动画](./docs/zh/animations.md) | 页间转场和页内元素入场动画 || 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 || 💼 | [示例](./examples/README.md) | 22 个项目,309 页 || 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |diff --git a/docs/animations.md b/docs/animations.mdnew file mode 100644index 00000000..4f66ff7b--- /dev/null+++ b/docs/animations.md@@ -0,0 +1,94 @@+# Page Transitions & Per-Element Animations++PPT Master's exported PPTX supports **page transitions** (slide-to-slide) and **per-element entrance animations** (within a slide). Both are controlled by `svg_to_pptx.py` CLI flags and ship as real OOXML — they animate inside PowerPoint and Keynote, no embedded video.++## Defaults++| Layer | Default | Why |+|---|---|---|+| Page transition | `fade`, 0.4s | Calm baseline that suits most decks |+| Per-element animation | off | Existing users see no behavior change |++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.++## Page Transitions++```bash+# Pick a different effect+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6++# Disable+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none++# Auto-advance every 5 seconds (kiosk-style playback)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5+```++Available effects: `fade`, `push`, `wipe`, `split`, `strips`, `cover`, `random`.++Flags:++- `-t/--transition` — effect name, or `none` to disable. Default: `fade`.+- `--transition-duration` — seconds, default `0.4`.+- `--auto-advance` — seconds; omit for presenter-controlled advance.++## Per-Element Animations++Off by default. When enabled, entering a slide → first click reveals the first semantic group; each subsequent click reveals the next group in z-order.++```bash+# Cascade every group with fade (recommended starting point)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade++# Auto-vary effects within a slide (title fades; later groups cycle a curated pool)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed++# Slow each reveal down to 0.5s+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --animation-duration 0.5+```++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:++- `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.++The pool excludes `appear` because it has no visible motion.++Flags:++- `-a/--animation` — effect name, `mixed`, `random`, or `none`. Default: `none`.+- `--animation-duration` — per-element seconds, default `0.3`.+- `--animation-stagger` — kept for backward compatibility; ignored by click-by-click timing.++## Anchor Logic — Top-Level `<g id="...">`++Per-element animations are anchored on **top-level `<g id="...">` groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). One group = one click reveal.++Aim for **3–8 semantic groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.++**Fallback for flat SVGs** (no top-level `<g>` wrappers, only raw `<rect>` / `<text>` / `<path>` at the root):++- ≤ 8 visible top-level primitives → each becomes one anchor (capped to avoid 70+ atom cascades on dense pages).+- > 8 → animation is skipped on that slide. The slide still renders, just without entrance animation.++Executors should wrap logical sections in `<g id>` regardless of whether you plan to animate. The Executor reference (`skills/ppt-master/references/shared-standards.md`) requires it.++## Limitations++- **Native shapes mode only.** Per-element animation needs editable shape anchors. `--only legacy` produces one image per slide and has no element granularity to animate; that mode is unaffected by `-a/--animation` and only honors `-t/--transition`.+- **Office version drift on element animations.** Effects use the `<p:animEffect filter=...>` path (vs. `presetID` lookup tables) to stay stable across Office versions. Most filters render identically in PowerPoint 2016+; older Office may downgrade some filters to plain Appear.+- **PNG fallback (compat mode) is for visual rendering only.** Transitions and animations live in the slide XML, not in the PNG, so disabling compat mode does not affect either layer.++## Quick Reference++| Goal | Command |+|---|---|+| Disable transitions | `-t none` |+| Change transition effect | `-t push` (or any from the list above) |+| Slower transition | `--transition-duration 0.8` |+| Auto-play | `--auto-advance 5` |+| Enable element animation | `--animation fade` |+| Auto-vary element animation | `--animation mixed` |+| Slower per-element reveal | `--animation-duration 0.5` |++See also: [`scripts/docs/svg-pipeline.md`](../skills/ppt-master/scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference.diff --git a/docs/faq.md b/docs/faq.mdindex c09349d1..f680cc50 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -56,46 +56,16 @@ If your workflow specifically requires Excel-driven data editing, manually creat## Q: Can I change page transitions and element animations?-Yes. The exported PPTX supports both **page transitions** and **per-element entrance animations**, controlled via `svg_to_pptx.py` CLI flags.--**Page transitions** (on by default, 0.4s `fade`)--```bash-# Pick a different effect: fade / push / wipe / split / strips / cover / random-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6--# Disable transitions-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none--# Auto-advance every 5 seconds-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5-```--**Per-element animations** (off by default — existing users see no behavior change)--Enter a slide → click once → semantic groups cascade in by z-order. To enable:+Yes. Page transitions (`fade` 0.4s by default) and per-element entrance animations (off 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:```bash-# Cascade every element with fade (recommended starting point)-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade--# Auto-vary visible effects within a slide (title fades; content cycles through a curated pool)-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed--# Slower pace: 0.5s per click-revealed element-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade \- --animation-duration 0.5 --animation-stagger 0.2+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # enable per-element+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed # auto-vary effects```-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 `mixed` and `random` auto-vary modes.--`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 the same visible-effect pool. The pool excludes `appear` because it is too subtle for presenter-controlled reveals.--`--animation-stagger` is kept for backward compatibility but is ignored by click-by-click timing. Use `--animation-duration` to control how obvious each reveal feels.--**Anchor logic**: animations are anchored on top-level SVG `<g id="...">` groups (e.g. `<g id="cover-title">`, `<g id="card-1">`) — this is the cleanest cascade granularity. Aim for 3–8 semantic groups per slide. Slides whose root is flat `<rect>` / `<text>` / `<path>` (no top-level `<g>` wrappers) **fall back automatically**: if there are ≤8 top-level visible elements, each becomes one animation anchor; beyond 8, animation is skipped on that slide. So Executors should wrap logical sections in `<g id>` regardless of animation, since it also improves PowerPoint's group-select / group-move ergonomics.--**Note**: per-element animations only apply in native shapes mode (the default); `--only legacy` produces one image per slide and has no element anchors to animate.+Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](./animations.md).## Q: Which AI model works best?diff --git a/docs/zh/animations.md b/docs/zh/animations.mdnew file mode 100644index 00000000..a75866b9--- /dev/null+++ b/docs/zh/animations.md@@ -0,0 +1,94 @@+# 页间转场与页内元素动画++PPT Master 导出的 PPTX 同时支持**页间转场**(page transition)与**页内元素入场动画**(per-element entrance animation)。两者都通过 `svg_to_pptx.py` 的 CLI 参数控制,输出为真正的 OOXML 动画——在 PowerPoint 和 Keynote 中原生播放,不是嵌入视频。++## 默认行为++| 层级 | 默认 | 原因 |+|---|---|---|+| 页间转场 | `fade`,0.4 秒 | 适合大多数 deck 的中性基线 |+| 页内元素动画 | 关闭 | 老用户更新后行为不变 |++修改设置只需对同一份 `svg_output/`(或 `svg_final/`)重跑 `svg_to_pptx.py`,无需重新跑 LLM。++## 页间转场++```bash+# 换效果+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6++# 关闭转场+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none++# 每 5 秒自动翻页(展厅 / 自动循环)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5+```++可选效果:`fade`、`push`、`wipe`、`split`、`strips`、`cover`、`random`。++参数:++- `-t/--transition` — 效果名,或 `none` 禁用。默认 `fade`。+- `--transition-duration` — 秒数,默认 `0.4`。+- `--auto-advance` — 秒数;不写则由演示者手动翻页。++## 页内元素动画++默认关闭。开启后:进入页面 → 第一次点击显示第一个语义组,后续每次点击按 z-order 显示下一个组。++```bash+# 全部用 fade 入场(推荐起点)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade++# 同页自动轮换效果(首组 fade,后续组在精选效果池中轮换)+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed++# 让每次入场放慢到 0.5 秒+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --animation-duration 0.5+```++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` — 在同一效果池中随机抽取。++效果池排除了 `appear`,因为它没有可见动画过程。++参数:++- `-a/--animation` — 效果名、`mixed`、`random` 或 `none`。默认 `none`。+- `--animation-duration` — 单个元素入场秒数,默认 `0.3`。+- `--animation-stagger` — 仅保留兼容旧命令;当前逐次点击入场逻辑会忽略它。++## 锚点机制 — 顶层 `<g id="...">`++页内动画锚定在 SVG 的**顶层 `<g id="...">` 组**上(如 `<g id="cover-title">`、`<g id="card-1">`),一个组对应一次点击入场。++每页建议 **3–8 个语义组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度,与是否启用动画无关,都能改善编辑体验。++**扁平 SVG 的回退逻辑**(顶层没有 `<g>`,只有裸 `<rect>` / `<text>` / `<path>`):++- 顶层可见图元 ≤ 8 → 每个图元作为一个锚点(设上限以避免密集页面出现 70+ 次点击)。+- 顶层可见图元 > 8 → 该页跳过页内动画。页面照常显示,只是不带入场。++无论是否打算开启动画,Executor 都应该把逻辑分块包进 `<g id>`。`skills/ppt-master/references/shared-standards.md` 已将这一点列为强制要求。++## 限制++- **仅原生形状模式生效。** 页内动画需要可编辑形状作为锚点。`--only legacy` 模式每页一张大图,没有元素粒度,因此不响应 `-a/--animation`,只受 `-t/--transition` 影响。+- **不同 Office 版本对元素动画存在轻微差异。** 实现走 `<p:animEffect filter=...>` 路径(而非 `presetID` 查找表),在 PowerPoint 2016+ 上表现一致;更老的 Office 可能把部分效果降级为 Appear。+- **兼容模式的 PNG fallback 只用于显示。** 转场与动画都在 slide XML 里,不在 PNG 中;关掉兼容模式不影响两个动画层。++## 常用速查++| 目标 | 命令 |+|---|---|+| 关闭转场 | `-t none` |+| 切换转场效果 | `-t push`(或上文列表中任一) |+| 转场放慢 | `--transition-duration 0.8` |+| 自动播放 | `--auto-advance 5` |+| 启用元素动画 | `--animation fade` |+| 元素动画自动轮换 | `--animation mixed` |+| 元素入场放慢 | `--animation-duration 0.5` |++完整 `svg_to_pptx.py` 参考:[`scripts/docs/svg-pipeline.md`](../../skills/ppt-master/scripts/docs/svg-pipeline.md)。diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 20809fbd..2d393f1f 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -56,46 +56,16 @@ PPT Master 本身免费开源,唯一的成本来自你自己的 AI 模型用## Q: 页面切换和元素动画可以调吗?-可以。导出的 PPTX 同时支持**页间转场**和**页内元素入场动画**,都通过 `svg_to_pptx.py` 的 CLI 参数控制。--**页间转场**(默认开启 0.4s `fade`)--```bash-# 换效果:fade / push / wipe / split / strips / cover / random-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6--# 关闭转场-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none--# 自动定时翻页(每 5 秒)-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5-```--**页内动画**(默认关闭 —— 老用户更新后行为不变)--进入新页 → 单击一次 → 各语义组按 z-order 依次入场。开启方式:+可以。页间转场(默认 `fade` 0.4s)和页内元素入场动画(默认关闭)都通过 `svg_to_pptx.py` 的参数控制——`-t/--transition` 控制页级,`-a/--animation` 控制元素级。常用一行命令:```bash-# 全部元素淡入级联(推荐起步)-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade--# 同页内自动混搭明显可见的效果(标题 fade,内容按精选池轮换)-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed--# 调慢节奏:每次点击出现的元素入场 0.5s-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade \- --animation-duration 0.5 --animation-stagger 0.2+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # 关闭转场+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # 开启页内动画+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed # 自动混搭效果```-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`、`random` 两种自动混搭模式。--`mixed` 是确定性轮换:每页第一个动画组使用 `fade`,后续组按精选的明显效果池在整份 deck 内连续轮换。`random` 从同一个明显效果池中随机抽取。效果池会排除 `appear`,因为它对演示点击入场来说太不明显。--`--animation-stagger` 仅保留作兼容旧命令,当前逐次点击入场逻辑会忽略它。需要让动画更明显时,使用 `--animation-duration` 调整每个入场效果的持续时间。--**锚点逻辑**:动画以 SVG 顶层 `<g id="语义名">` 分组为单位(如 `<g id="cover-title">`、`<g id="card-1">`),这是最干净的级联粒度。建议每页控制在 3–8 个语义组。如果某页根节点是平铺的 `<rect>`/`<text>`/`<path>`(没有顶层 `<g>` 包裹),导出器会**自动降级**:当顶层可见元素 ≤8 个时,每个元素作为一个动画锚点;超过 8 个则跳过该页动画。所以 Executor 输出应该把逻辑组都用 `<g id>` 包起来,既利于动画,也利于 PowerPoint 里成组选择/移动。--**注意**:页内动画只在 native shapes 模式(默认)生效,`--only legacy` 整页一张图无可锚定元素。+完整效果列表、`<g id="...">` 锚点机制、降级行为、限制:见 [转场与动画](./animations.md)。## Q: 推荐用什么 AI 模型?diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex d5e07b82..c2a5d4b1 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -305,9 +305,16 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final# backup/<timestamp>/svg_output/ ← Executor SVG source backup```+**Optional animation flags** (add to the command above when the user asks for them; otherwise omit):+- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`.+- `-a <effect>` — per-element entrance animation. Default off. Common picks: `fade` (every group fades in by click), `mixed` (auto-vary across the deck). Requires top-level `<g id="...">` groups (already required by Executor).+- `--auto-advance <seconds>` — kiosk-style auto-play.++Full effect list, anchor logic, and limits: [`docs/animations.md`](../../docs/animations.md).+> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps> ❌ **NEVER** export from `svg_output/` — MUST use `-s final` (exports from `svg_final/`)-> ❌ **NEVER** add extra flags like `--only`+> ❌ **NEVER** use `--only` (it suppresses one of the two output files)---diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex e1d6d4a2..f013c3dd 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -306,10 +306,17 @@ python3 scripts/svg_to_pptx.py <project_path> -s final# backup/<timestamp>/svg_output/ ← Executor SVG source backup```+**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; default off). Anchors on top-level `<g id="...">` groups.+- `--auto-advance <seconds>` — kiosk-style auto-play++Full reference: [`docs/animations.md`](../../../docs/animations.md).+**Prohibited**:- NEVER use `cp` as a substitute for `finalize_svg.py`- NEVER export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)-- NEVER add extra flags like `--only`+- NEVER use `--only` (it suppresses one of the two output files)**Re-run rule**: Any change to `svg_output/` after post-processing requires re-running Steps 2-3. Step 1 only re-runs if `notes/total.md` changed.