| 1 | # Page Transitions & Element Animations |
| 2 | |
| 3 | [English](./animations.md) | [Chinese](./zh/animations.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | PPT Master writes **page transitions** and optional **element object |
| 8 | animations** as real PowerPoint OOXML, not embedded video. Object animation |
| 9 | includes entrance, emphasis, motion-path, and exit effects. This guide covers |
| 10 | the choices and commands users need; exact effect mappings, the complete |
| 11 | sidecar schema, anchor rules, and package validation live in the |
| 12 | [animation execution reference](../skills/ppt-master/references/animations.md). |
| 13 | |
| 14 | ## Default Behavior |
| 15 | |
| 16 | | Layer | Default | What it means | |
| 17 | |---|---|---| |
| 18 | | Page transition | `fade`, 0.4 seconds | Slides change with a restrained visual transition | |
| 19 | | Element object animation | **`none` (off)** | Each slide appears as a complete page; opt in only when motion helps the presentation | |
| 20 | |
| 21 | Changing animation settings does not require regenerating the slides. Reuse the |
| 22 | same `svg_output/`; default release export still requires its current passing |
| 23 | final SVG quality report. When no current matching passing final report exists, |
| 24 | run the final checker and resolve its blockers before rerunning `svg_to_pptx.py`. |
| 25 | |
| 26 | ## Common Recipes |
| 27 | |
| 28 | | Goal | Command | |
| 29 | |---|---| |
| 30 | | Keep the defaults | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project>` | |
| 31 | | Change the page transition | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push` | |
| 32 | | Remove the visual transition | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none` | |
| 33 | | Auto-advance every 5 seconds | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5` | |
| 34 | | Enable automatic element reveals | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto` | |
| 35 | | Use one entrance effect throughout | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade` | |
| 36 | | Reveal elements on click | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click` | |
| 37 | | Animate all elements together | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous` | |
| 38 | | Slow the reveal sequence | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8` | |
| 39 | |
| 40 | ## Choose a Page Transition |
| 41 | |
| 42 | | Relationship between adjacent slides | Start with | |
| 43 | |---|---| |
| 44 | | Ordinary continuation within one section | `fade` | |
| 45 | | Immediate change with no continuity to preserve | `none` or `cut` | |
| 46 | | Directional steps, timeline, or visible layer progression | `push`, `wipe`, `cover`, or `uncover` with a meaningful direction | |
| 47 | | The same object or scene changes position, size, crop, or appearance | `morph` | |
| 48 | | Section opening, key reveal, or marked state boundary | A selective `split`, `reveal`, `shape`, `flash`, or `random_bars` | |
| 49 | | A repeated collection advances through one spatial frame | `pan`, `conveyor`, or `ferris_wheel`; use Morph when individual objects must retain identity | |
| 50 | | The viewpoint travels around or through a continuous space | `rotate`, `window`, `orbit`, or `fly_through` | |
| 51 | | The theme supports a stage, paper, or physical-page metaphor | A selective `fall_over`, `drape`, `curtains`, `wind`, `prestige`, `peel_off`, `page_curl`, `airplane`, `origami`, or `doors` | |
| 52 | | A disruptive beat represents breakage, collapse, or dispersal | A selective `fracture`, `crush`, `dissolve`, `vortex`, or `shred` | |
| 53 | | A marked reveal benefits from a geometric, timed, or textured pattern | A selective `checkerboard`, `blinds`, `clock`, `ripple`, `honeycomb`, `glitter`, or `comb` | |
| 54 | | A card, panel, gallery, or viewpoint visibly turns or changes face | A selective `switch`, `flip`, `gallery`, `cube`, `box`, or `zoom` | |
| 55 | |
| 56 | Keep `fade` or `none` when no other transition adds meaning. Do not change |
| 57 | effects merely to create variety; `random` is appropriate only when |
| 58 | unpredictability is itself intentional. |
| 59 | |
| 60 | The 48 canonical transition keys cover all three sections in the current |
| 61 | PowerPoint gallery: |
| 62 | |
| 63 | - Subtle: `morph`, `fade`, `push`, `wipe`, `split`, `reveal`, `cut`, |
| 64 | `random_bars`, `shape`, `uncover`, `cover`, `flash`. |
| 65 | - Exciting: `fall_over`, `drape`, `curtains`, `wind`, `prestige`, `fracture`, |
| 66 | `crush`, `peel_off`, `page_curl`, `airplane`, `origami`, `dissolve`, |
| 67 | `checkerboard`, `blinds`, `clock`, `ripple`, `honeycomb`, `glitter`, |
| 68 | `vortex`, `shred`, `switch`, `flip`, `gallery`, `cube`, `doors`, `box`, |
| 69 | `comb`, `zoom`, `random`. |
| 70 | - Dynamic Content: `pan`, `ferris_wheel`, `conveyor`, `rotate`, `window`, |
| 71 | `orbit`, `fly_through`. |
| 72 | |
| 73 | The old names `strips`, `circle`, `diamond`, `newsflash`, `plus`, `pull`, |
| 74 | `wedge`, and `wheel` remain accepted only as compatibility inputs. New |
| 75 | sidecars, plans, traces, and output use canonical keys. Compatibility inputs |
| 76 | desugar into a native effect plus its Effect Options—for example, `diamond` |
| 77 | becomes `shape` with `shape: diamond`, and `wedge` becomes `clock` with |
| 78 | `style: wedge`. |
| 79 | |
| 80 | Set effect-specific PowerPoint options in |
| 81 | `transition.effect_options`. Direction, shape, pattern, Morph scope, black |
| 82 | screen, page count, and bounce are validated against the selected effect. |
| 83 | Run |
| 84 | `python3 skills/ppt-master/scripts/pptx_animations.py --describe-transition <effect>` |
| 85 | for the exact values. `-t none` removes the visual effect but does not remove |
| 86 | an explicitly configured auto-advance timer. |
| 87 | |
| 88 | ## Choose a Start Mode |
| 89 | |
| 90 | | Start mode | Behavior | Best fit | |
| 91 | |---|---|---| |
| 92 | | `on-click` | One content group appears per click | Live presentations where the speaker controls pacing | |
| 93 | | `with-previous` | All content groups animate together when the slide appears | A single coordinated entrance | |
| 94 | | `after-previous` (default) | Groups appear sequentially without clicks | Kiosk playback, walkthroughs, and narrated decks | |
| 95 | |
| 96 | `--recorded-narration` does not support `on-click`; use `after-previous` or `with-previous` for narrated or video-ready output. |
| 97 | |
| 98 | ## Choose an Object Animation |
| 99 | |
| 100 | Start with `none`. When object motion has a communication job, choose its |
| 101 | lifecycle before its visual effect: |
| 102 | |
| 103 | | Communication job | Choice | Boundary | |
| 104 | |---|---|---| |
| 105 | | Reveal information in reading or narration order | `auto` or a native `entrance_*` key | This is the usual object-animation case | |
| 106 | | Redirect attention to an already visible object | An explicit `emphasis_*` key | Do not use it as the object's first reveal | |
| 107 | | Show meaningful spatial or causal movement | An explicit `path_*` key, or Morph across adjacent slides | The path itself should carry meaning; deliberate background ambience is an advanced exception | |
| 108 | | Remove, replace, or make room for content on the same slide | An explicit `exit_*` key | A normal slide change already removes the old page | |
| 109 | | Add deterministic or seeded variation to generic entrances | `mixed` or `random` | These modes still select entrance effects only | |
| 110 | | No clear motion task | `none` | Keep the slide static | |
| 111 | |
| 112 | The canonical registry contains 203 PowerPoint-native keys: 53 entrance, 33 |
| 113 | emphasis, 64 motion path, and 53 exit presets. New selections, sidecars, |
| 114 | automatic choices, traces, and examples use these category-qualified keys. |
| 115 | `auto`, `mixed`, and `random` select entrances only. Use an explicit canonical |
| 116 | key for emphasis, motion-path, or exit behavior. |
| 117 | The 29 established short names remain accepted only as compatibility inputs; |
| 118 | they normalize before writing and do not retain a second behavior engine. |
| 119 | Old Fly direction names all normalize to `entrance_fly`, and old Wipe |
| 120 | direction names all normalize to `entrance_wipe`; their direction is preserved |
| 121 | as an option rather than another canonical preset. Legacy `wheel` keeps four |
| 122 | spokes. Run |
| 123 | `python3 skills/ppt-master/scripts/pptx_animations.py --list` for the complete |
| 124 | categorized list. The four media playback commands are handled by the |
| 125 | audio/video workflows because they require media or bookmark targets. |
| 126 | |
| 127 | ## Add Sound After Choosing Motion |
| 128 | |
| 129 | Sound effects are off by default. PPT Master includes a global CC0 sound |
| 130 | library, but it is not copied during strategy or ordinary project setup. First |
| 131 | finish the SVG pages and choose the visual transition/object motion. Only when |
| 132 | one of those resolved beats has a specific auditory job should you read the |
| 133 | complete objective [sound vocabulary](../skills/ppt-master/templates/sounds/sound-vocabulary.md), |
| 134 | select one exact id, and sync the cue: |
| 135 | |
| 136 | ```bash |
| 137 | python3 skills/ppt-master/scripts/sound_sync.py \ |
| 138 | <project> bigsoundbank/1797 kenney-interface/click_001 |
| 139 | ``` |
| 140 | |
| 141 | The command copies only the selected files into |
| 142 | `<project>/sounds/<namespace>/`. With no selected cue, PPT Master creates no |
| 143 | project sound directory and copies nothing. After reviewing the vocabulary, |
| 144 | the CLI may narrow an already-considered label, tag, or context without deciding |
| 145 | fit: |
| 146 | |
| 147 | ```bash |
| 148 | python3 skills/ppt-master/scripts/sound_sync.py list --query whoosh |
| 149 | ``` |
| 150 | |
| 151 | Configuration always references the copied project-local path, never the |
| 152 | global `templates/sounds/` path or a library id: |
| 153 | |
| 154 | ```json |
| 155 | { |
| 156 | "version": 1, |
| 157 | "slides": { |
| 158 | "02_process": { |
| 159 | "transition": { |
| 160 | "effect": "push", |
| 161 | "sound": "sounds/bigsoundbank/1797.wav" |
| 162 | }, |
| 163 | "groups": { |
| 164 | "next-step": { |
| 165 | "effect": "entrance_fade", |
| 166 | "sound": "sounds/kenney-interface/click_001.wav" |
| 167 | } |
| 168 | } |
| 169 | } |
| 170 | } |
| 171 | } |
| 172 | ``` |
| 173 | |
| 174 | `transition.sound` uses WAV. Object-animation `sound` also accepts an existing |
| 175 | project-relative or absolute `.m4a`, `.mp3`, or `.wav` input; bundled choices |
| 176 | are WAV and should use the copied project-relative path. A transition-only cue |
| 177 | may use a sparse `animations.json`; a slide-level `transition.sound: null` |
| 178 | clears an inherited default sound. Validate before export. Do not add sound |
| 179 | merely to demonstrate that the feature exists. |
| 180 | |
| 181 | This validation proves the editable PPTX contains the native cue; it does not |
| 182 | prove PowerPoint's MP4 audio track contains it. For direct narrated video with |
| 183 | resolved cues, follow [Audio Narration & Video Export](./audio-narration.md) |
| 184 | and choose either the verified native-export sound mix or an explicit |
| 185 | PowerPoint slideshow capture with system audio. Do not combine the two paths. |
| 186 | |
| 187 | ## Customize Specific Objects |
| 188 | |
| 189 | Use `animations.json` only when deck-wide settings are not enough—for example, |
| 190 | one object entering, moving, drawing attention, and then leaving. List the real |
| 191 | groups, write sparse overrides for only the affected slides and objects, |
| 192 | validate, and export. `scaffold` is an optional neutral editing starter: it |
| 193 | sets the default object effect to `none`, and untouched `{}` group entries do |
| 194 | not enable animation. |
| 195 | |
| 196 | ```bash |
| 197 | python3 skills/ppt-master/scripts/animation_config.py list-groups <project> |
| 198 | python3 skills/ppt-master/scripts/animation_config.py validate <project> |
| 199 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> |
| 200 | ``` |
| 201 | |
| 202 | The sidecar targets stable top-level `<g id="...">` content groups. A group ID |
| 203 | is a PowerPoint shape-target anchor, not an Animation Pane row. The compatible |
| 204 | single-effect object still creates one row; an `effects[]` array can create |
| 205 | several ordered rows that all target the same shape: |
| 206 | |
| 207 | ```json |
| 208 | { |
| 209 | "version": 1, |
| 210 | "slides": { |
| 211 | "03_threshold": { |
| 212 | "animation": { "trigger": "after-previous" }, |
| 213 | "groups": { |
| 214 | "risk-marker": { |
| 215 | "effects": [ |
| 216 | { "effect": "entrance_fade", "order": 1, "duration": 0.25 }, |
| 217 | { "effect": "path_right", "order": 2, "delay": 0.1, "duration": 0.7 }, |
| 218 | { "effect": "emphasis_teeter", "order": 3, "trigger": "with-previous", "duration": 0.45 }, |
| 219 | { "effect": "exit_fade", "order": 4, "trigger_shape": "details-button", "duration": 0.3 } |
| 220 | ] |
| 221 | } |
| 222 | } |
| 223 | } |
| 224 | } |
| 225 | } |
| 226 | ``` |
| 227 | |
| 228 | A populated group uses either the legacy single-effect fields or the |
| 229 | `{ "effects": [...] }` form, never both. `effects` must be non-empty, and every |
| 230 | row names an explicit `effect`. Existing single-effect sidecars remain fully |
| 231 | compatible. |
| 232 | |
| 233 | Common row fields are: |
| 234 | |
| 235 | | Field | Purpose | |
| 236 | |---|---| |
| 237 | | `effect` | Select one explicit effect; the legacy form may use `none` to keep that object static | |
| 238 | | `trigger` | Override this row's Start mode; otherwise inherit the slide animation trigger | |
| 239 | | `order` | Order ordinary rows across the slide without changing slide layers; trigger-shape rows remain in separate interactive sequences | |
| 240 | | `delay` | Add a pause to this row's resolved Start behavior | |
| 241 | | `duration` | Override this row's scheduled animation duration | |
| 242 | | `effect_options` | Set effect-specific `direction`, `amount`, `color`, `font_name`, `relative`, or `size` | |
| 243 | | `trigger_shape` | Trigger this row when another top-level group is clicked (PowerPoint **On Click of**) | |
| 244 | | Timing modifiers | `repeat_count`/`repeat_duration`, `auto_reverse`, `rewind`, `accelerate`, `decelerate`, `bounce_end`, and `restart` | |
| 245 | | Completion | `after_effect` (`none`, dim, hide, or hide on next click) | |
| 246 | | Sound cue | Optional project-local `sound` path; bundled choices follow the on-demand sync above | |
| 247 | |
| 248 | `order`, `delay`, `duration`, `trigger`, and `trigger_shape` are resolved per |
| 249 | row. The slide-level animation trigger is inheritance only. `trigger_shape` |
| 250 | implies `on-click`; if the row also declares `trigger`, it must be |
| 251 | `on-click`. |
| 252 | |
| 253 | Use `python3 skills/ppt-master/scripts/pptx_animations.py --describe |
| 254 | <canonical_effect>` to see exactly which options that effect accepts. Speed is |
| 255 | controlled by `duration`; smooth start/end are controlled by |
| 256 | `accelerate`/`decelerate`. Change Font's `font_name` is one concrete |
| 257 | target-installed PowerPoint face, never a CSS font stack. |
| 258 | |
| 259 | `trigger_shape` points to a different group id on the same slide and affects |
| 260 | only its row. Recorded narration rejects any row that resolves to `on-click`, |
| 261 | including trigger-shape rows. |
| 262 | |
| 263 | When a user asks the AI to tune individual objects, use the [`customize-animations`](../skills/ppt-master/workflows/stages/customize-animations.md) stage. The full sidecar schema and target-validation rules remain in the [animation execution reference](../skills/ppt-master/references/animations.md). |
| 264 | |
| 265 | ## Validation & Compatibility |
| 266 | |
| 267 | PPT Master validates animation settings strictly: unknown effects or Start modes, invalid timing values, missing slide/group references, and attempts to animate structural objects fail instead of silently changing behavior. Export also reads the candidate PPTX back before replacing an existing output. |
| 268 | |
| 269 | | Boundary | User-facing consequence | |
| 270 | |---|---| |
| 271 | | Animation target | Element animation operates on logical top-level content-group anchors; one anchor may own several Animation Pane rows | |
| 272 | | Static structure | Backgrounds, Master/Layout content, placeholders, and page chrome remain static | |
| 273 | | 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 | |
| 274 | | Output route | Animation exists in the native PPTX generated from `svg_output/`; `svg_final/` is a static preview | |
| 275 | | Existing PPTX routes | Template Fill and Native Enhance preserve source object animation rather than translating it into this generated-deck model | |
| 276 | | 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 | |
| 277 | | Playback compatibility | Microsoft PowerPoint desktop is the primary validation target; Keynote, WPS, LibreOffice, and older Office versions may remap or omit individual effects | |
| 278 | |
| 279 | 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). |
| 280 |