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(ppt): clarify semantic custom animation planning
hugohe38dc12e5e6ffc
diff --git a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py b/skills/ppt-master/scripts/svg_to_pptx/animation_config.pyindex 0a9adda3..55f8e3b3 100644--- a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py+++ b/skills/ppt-master/scripts/svg_to_pptx/animation_config.py@@ -107,8 +107,11 @@ def default_config_path(project_path: Path) -> Path:def load_animation_config(project_path: Path, config_path: str | None = None) -> dict[str, Any] | None:"""Load optional animation config; return ``None`` when absent."""- path = Path(config_path) if config_path else default_config_path(project_path)- if not path.is_absolute():+ if config_path:+ path = Path(config_path)+ else:+ path = default_config_path(project_path)+ if config_path and not path.is_absolute():path = project_path / pathif not path.exists():return None@@ -220,8 +223,11 @@ def write_scaffold(force: bool = False,) -> Path:"""Write ``animations.json`` scaffold and return its path."""- path = Path(output_path) if output_path else default_config_path(project_path)- if not path.is_absolute():+ if output_path:+ path = Path(output_path)+ else:+ path = default_config_path(project_path)+ if output_path and not path.is_absolute():path = project_path / pathif path.exists() and not force:raise FileExistsError(f'Animation config already exists: {path}')diff --git a/skills/ppt-master/workflows/customize-animations.md b/skills/ppt-master/workflows/customize-animations.mdindex 835bcab9..99eba0b6 100644--- a/skills/ppt-master/workflows/customize-animations.md+++ b/skills/ppt-master/workflows/customize-animations.md@@ -35,24 +35,140 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>----## 2. Edit `animations.json`+## 2. Read Semantic Context++**Mandatory**: before editing `animations.json`, read the deck's semantic planning files.++| File | Use |+|---|---|+| `<project_path>/design_spec.md` | Understand each slide's content intent, narrative role, and visual emphasis |+| `<project_path>/spec_lock.md` | Confirm page rhythm, layout role, chart/template constraints, and execution contract |+| `<project_path>/notes/total.md` or `<project_path>/notes/*.md` | Use speaker flow to tune reveal order, delays, and emphasis |++**Hard rule**: semantic files determine animation intent; `svg_output/*.svg` determines valid animation targets. Never reference a slide or group id that is absent from the scaffold / SVG scan.++**Missing context**: if one semantic file is absent, state what is missing and proceed with the remaining files plus real SVG group ids. If both `design_spec.md` and `spec_lock.md` are absent, do not infer detailed object choreography; use only conservative defaults and explicit user instructions.++---++## 3. Plan Slide and Object Motion++**Mandatory**: plan both page-level transitions and in-slide object entrances before editing `animations.json`.++| Layer | Config path | Use |+|---|---|---|+| Page transition | `defaults.transition` or `slides.<slide>.transition` | Control how one slide enters from the previous slide |+| Page animation defaults | `defaults.animation` or `slides.<slide>.animation` | Control the default entrance behavior for animated groups on a slide |+| Object overrides | `slides.<slide>.groups.<group_id>` | Control order, effect, delay, or duration for a real SVG group |++**Per-page motion brief**: for each slide, decide transition effect, transition duration, object reveal sequence, object effects, and timing. Use `design_spec.md` for slide role, `spec_lock.md` for rhythm, speaker notes for narration order, and SVG group ids for target validity.++**Hard rule**: a custom animation pass must not only edit group effects. It must also decide whether each slide should inherit the default transition or need a slide-specific `transition` override.++**Timing guidance**: prefer content-aware durations when the deck has varied slide rhythm or object importance. Uniform timing is acceptable when it matches the user's requested style or the deck's pacing.++**Duration planning**:++| Context | Transition duration | Object duration | Delay / stagger |+|---|---:|---:|---:|+| `anchor` slide / section opener / closing synthesis | 0.35-0.60s | 0.45-0.75s | 0.20-0.40s |+| `breathing` concept slide / hero diagram | 0.25-0.45s | 0.40-0.65s | 0.16-0.30s |+| `dense` technical slide / repeated pattern page | 0.18-0.35s | 0.25-0.45s | 0.10-0.24s |+| Minor supporting object | inherit or 0.20-0.35s | 0.20-0.35s | 0.08-0.18s |+| Key insight / final takeaway | 0.30-0.50s | 0.50-0.80s | 0.25-0.45s |++**Duration guidance**: use shorter timing for repeated scan content, longer timing for conceptual pivots, section transitions, hero diagrams, and final takeaways.++### 3.1 Supported Page Transitions++| Effect | Behavior |+|---|---|+| `none` | Disable page transition |+| `fade` | Neutral default for technical decks |+| `push` | Directional slide entry |+| `wipe` | Directional reveal |+| `split` | Split-open transition |+| `strips` | Diagonal strips transition |+| `cover` | Cover from the side |+| `random` | PowerPoint random transition |++**Transition fields**:++| Field | Behavior |+|---|---|+| `effect` | One supported page transition effect |+| `duration` | Transition duration in seconds |+| `auto_advance` | Optional seconds before automatic slide advance |++### 3.2 Supported In-Slide Animations++| Effect | Behavior |+|---|---|+| `none` | Exclude the object or slide from in-slide animation |+| `appear` | Visibility flip without motion |+| `fade` | Neutral entrance |+| `fly` | Fly in from bottom |+| `cut` | Cut in from left |+| `zoom` | Scale/zoom entrance |+| `wipe` | Wipe entrance |+| `split` | Split/barn entrance |+| `blinds` | Horizontal blinds |+| `checkerboard` | Checkerboard reveal |+| `dissolve` | Dissolve reveal |+| `random_bars` | Random bars reveal |+| `peek` | Peek/wipe down |+| `wheel` | Wheel entrance |+| `box` | Box-in reveal |+| `circle` | Circle-in reveal |+| `diamond` | Diamond-in reveal |+| `plus` | Plus-shaped reveal |+| `strips` | Diagonal strips reveal |+| `wedge` | Wedge reveal |+| `stretch` | Stretch entrance |+| `expand` | Expand entrance |+| `swivel` | Swivel entrance |+| `mixed` | Deterministic varied effects across animated groups |+| `random` | Random effect per animated group |++**Start modes**:++| Trigger | Behavior |+|---|---|+| `after-previous` | Cascade automatically on slide entry |+| `with-previous` | Start together on slide entry |+| `on-click` | One presenter click per animated group |++---++## 4. Edit `animations.json`**Hard rule**: write only overrides that differ from the default global animation. Unmentioned groups keep the normal export behavior.| Field | Behavior ||---|---|-| `effect` | Any supported entrance effect, `mixed`, `random`, or `none` |+| `transition.effect` | Slide-specific page transition effect |+| `transition.duration` | Slide-specific page transition duration |+| `animation.effect` | Slide-specific default object entrance effect |+| `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` || `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 |+| `duration` | Per-group entrance duration in seconds; vary when semantic weight or pacing calls for it |Example:```json{"version": 1,+ "defaults": {+ "transition": { "effect": "fade", "duration": 0.25 },+ "animation": { "effect": "fade", "duration": 0.4, "stagger": 0.2, "trigger": "after-previous" }+ },"slides": {"03_market": {+ "transition": { "effect": "wipe", "duration": 0.35 },"groups": {"title": { "effect": "fade", "order": 1 },"chart": { "effect": "wipe", "order": 2, "duration": 0.6 },@@ -68,7 +184,7 @@ Example:----## 3. Validate and Export+## 5. Validate and ExportRun sequentially:@@ -87,5 +203,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>## ✅ Customize Animations Complete- [x] `animations.json` exists only because object-level customization was requested+- [x] `design_spec.md`, `spec_lock.md`, and available speaker notes were checked before editing animation overrides+- [x] Page transitions and in-slide object animations were planned together+- [x] Transition and object durations were chosen intentionally for the deck's pacing- [x] `animation_config.py validate` passed- [x] PPTX re-export completed with custom animation overrides