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(animations): define the effect-aware video adaptation contract
hugohe3b6627a295019
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex 3d53820e..bf25aaa2 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -132,9 +132,9 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed \python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --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 three auto-vary modes:+29 single effects: `appear`, `fade`, `fly`, `fly_left`, `fly_right`, `fly_top`, `cut`, `zoom`, `wipe`, `wipe_left`, `wipe_right`, `wipe_up`, `wipe_down`, `split`, `blinds`, `checkerboard`, `dissolve`, `random_bars`, `peek`, `wheel`, `box`, `circle`, `diamond`, `plus`, `strips`, `wedge`, `stretch`, `expand`, `swivel`. Plus three auto-vary modes:-These names preserve the established filter / `presetID` / `presetSubtype` tuples documented in [`pptx-animations.md`](../scripts/docs/pptx-animations.md#3-compatibility-contract). `cut` is a legacy public key; compatibility promises its existing tuple, not a semantic interpretation inferred from an external preset-id table.+These names preserve the established filter / `presetID` / `presetSubtype` tuples documented in [`pptx-animations.md`](../scripts/docs/pptx-animations.md#3-compatibility-contract). `fly` remains the bottom-up variant. `wipe` preserves its historical tuple; use `wipe_left`, `wipe_right`, `wipe_up`, or `wipe_down` when motion should follow the layout explicitly. `cut` is a legacy public key; compatibility promises its existing tuple, not a semantic interpretation inferred from an external preset-id table.- `auto` (recommended when enabling) — 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.@@ -182,7 +182,23 @@ Narration injection merges audio timing into an existing direct `p:sld/p:timing`----## 7. Limitations+## 7. Video Adaptation Contract++Custom animation remains the semantic source for video motion. A downstream+video renderer must consume a resolved conversion trace through+`video_motion_plan.py`, not infer motion from delay values or read an unresolved+sidecar directly.++The plan locks object identity, object order, source effect, semantic direction,+and timing anchors. Video-only adaptation may refine easing, travel distance,+opacity, scale, mask feather, blur, motion blur, and overshoot. Unsupported+effect families must fail visibly rather than silently becoming generic fades.+See [`video-motion-plan.md`](../scripts/docs/video-motion-plan.md) for the schema+and renderer contract.++---++## 8. Limitations- **Native DrawingML output only.** Page transitions and per-element animations are authored on the PPTX produced by the project converter from `svg_output/`. `svg_final/` remains a static SVG visual preview, not an animated or alternate PPTX route.- **PowerPoint OOXML scope.** Effects preserve their established filter / `presetID` / `presetSubtype` tuples and are validated against the serialized PowerPoint package. Rendering in Keynote, LibreOffice, WPS, or other applications is outside the unconditional compatibility guarantee.@@ -191,7 +207,7 @@ Narration injection merges audio timing into an existing direct `p:sld/p:timing`----## 8. Quick Reference+## 9. Quick Reference| Goal | Command ||---|---|@@ -208,9 +224,11 @@ Narration injection merges audio timing into an existing direct `p:sld/p:timing`| All groups animate together | `-a auto --animation-trigger with-previous` || Slower per-element reveal | `-a auto --animation-duration 0.5` || Wider gap in after-previous | `-a auto --animation-stagger 0.7` |+| Derive effect-aware video motion | `video_motion_plan.py <output>.pptx.trace.json --force` |See also:- [`scripts/docs/svg-pipeline.md`](../scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference.- [`pptx-transitions.md`](../scripts/docs/pptx-transitions.md) for the shared OOXML writer, MCE preservation, and read-back contract.- [`pptx-animations.md`](../scripts/docs/pptx-animations.md) for the exact effect tuples, timing-tree rules, and animation package validator.+- [`video-motion-plan.md`](../scripts/docs/video-motion-plan.md) for the resolved animation-to-video enhancement contract.diff --git a/skills/ppt-master/scripts/docs/pptx-animations.md b/skills/ppt-master/scripts/docs/pptx-animations.mdindex 23d96a64..2565c650 100644--- a/skills/ppt-master/scripts/docs/pptx-animations.md+++ b/skills/ppt-master/scripts/docs/pptx-animations.md@@ -83,6 +83,25 @@ The registry preserves these established 22 tuples exactly:`cut` is a legacy public key. Compatibility promises the tuple above; it doesnot infer a different semantic name from external preset-id tables.+Seven directional variants extend the registry without changing any established+tuple:++| Key | `p:animEffect@filter` | `presetID` | `presetSubtype` |+|---|---|---:|---:|+| `fly_left` | `slide(fromLeft)` | 2 | 8 |+| `fly_right` | `slide(fromRight)` | 2 | 2 |+| `fly_top` | `slide(fromTop)` | 2 | 1 |+| `wipe_left` | `wipe(left)` | 22 | 8 |+| `wipe_right` | `wipe(right)` | 22 | 2 |+| `wipe_up` | `wipe(up)` | 22 | 1 |+| `wipe_down` | `wipe(down)` | 22 | 4 |++The existing `fly` key remains fly-in from bottom. The existing `wipe` key+keeps its historical `wipe(left)` / subtype `1` tuple; use `wipe_left` for+PowerPoint's native left-direction subtype `8`. Directional keys are explicit+effect names rather than a new configuration field, so version-1 sidecars and+the read-back model remain unchanged.+**Hard rule — no downgrade**:- Keep the 22 established tuples byte-for-byte equivalent in meaning.@@ -175,6 +194,13 @@ targets. Template fill and native enhancement fingerprint the sourceobject-animation tree before and after their allowed edits; any semantic changefails. These routes have no object-animation write ownership.+The conversion trace is also the authoritative input for downstream video+motion. `video_motion_plan.py` preserves the resolved effect tuple, direction,+row order, duration, absolute offset, object bounds, and narration-derived slide+advance while adding only renderer-specific enhancement parameters. Video+renderers must not bypass this read-back result and infer motion from sidecar+delay values alone.+---## 7. Compatibility Scope@@ -192,3 +218,5 @@ Official references:See [`pptx-transitions.md`](./pptx-transitions.md) for the symmetric page-motioncore, MCE handling, and slide-advance contract.+See [`video-motion-plan.md`](./video-motion-plan.md) for the downstream+animation-to-video contract.diff --git a/skills/ppt-master/scripts/docs/video-motion-plan.md b/skills/ppt-master/scripts/docs/video-motion-plan.mdnew file mode 100644index 00000000..d573538e--- /dev/null+++ b/skills/ppt-master/scripts/docs/video-motion-plan.md@@ -0,0 +1,116 @@+# Video Motion Plan++`video_motion_plan.py` converts a resolved SVG-to-PPTX conversion trace into a+renderer-neutral motion plan. It is the handoff between PPT Master's canonical+custom animation and any SVG-native or post-production video renderer.++The planner exists to prevent a video path from reducing animation to delay+values. The conversion trace is authoritative because it already contains the+resolved object target, effect, direction tuple, order, duration, offset, slide+advance, and native object bounds after sidecar inheritance and narration+synchronization.++---++## 1. Generate a Resolved Source Trace++For a narrated deck, generate the trace from the narrated export so its offsets+and slide advances include the final audio timing:++```bash+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \+ --recorded-narration audio \+ --conversion-trace \+ -o <project_path>/validation/video_motion_source.pptx+```++Then build the motion plan:++```bash+python3 skills/ppt-master/scripts/video_motion_plan.py \+ <project_path>/validation/video_motion_source.pptx.trace.json \+ -o <project_path>/validation/video_motion_plan.json \+ --style adaptive \+ --force+```++`restrained` and `dynamic` are explicit intensity alternatives. `adaptive` is+the default and adjusts enhancement strength from page role, animated-object+count, and object area.++---++## 2. Authority and Locks++The downstream renderer must preserve:++- object identity and SVG group id;+- object order;+- source effect;+- semantic direction;+- resolved start time and slide timing anchor.++The video layer may optimize only the declared `optimizer_scope` parameters:+easing, travel distance, opacity, scale, mask feather, blur, motion blur, and+overshoot. These additions can make motion feel more cinematic without+rewriting the presentation's choreography.++Do not derive a video plan directly from raw `animations.json` or+`narration_animations.json`. Raw sidecars may still contain inheritance,+`auto`, timing modes, or narration-relative values. Always use the resolved+conversion trace.++---++## 3. Effect Mapping++Each object keeps `source_effect` and receives a compatible video family:++| Source effect | Video family |+|---|---|+| `appear` | `hard_reveal` |+| `fade` | `soft_fade` |+| `dissolve` | `grain_dissolve` |+| `fly*`, `cut` | `directional_slide` |+| `wipe*`, `peek` | `soft_mask_reveal` |+| `zoom`, `expand`, `stretch` | `focus_scale` |+| `split` | `split_mask` |+| `box`, `circle`, `diamond`, `plus` | `shape_mask` |+| `blinds`, `checkerboard`, `random_bars`, `strips`, `wedge`, `wheel` | `pattern_reveal` |+| `swivel` | `soft_swivel` |++This mapping is an enhancement contract, not permission to substitute an+unrelated effect. A directional slide remains directional; a wipe remains a+mask reveal.++---++## 4. Output Contract++The output schema is `ppt-master.video-motion-plan.v1`. Each slide records:++- SVG source and canvas size;+- page role;+- slide duration and its source;+- resolved transition;+- ordered animated objects.++Each object records:++- `group_id`, native `shape_id`, and order;+- source effect and trigger;+- absolute `start_ms` and `duration_ms`;+- native `bounds_emu` and normalized area;+- renderer parameters under `video`.++The planner rejects click-triggered animation because a rendered video has no+interactive click event. Re-export with click-free `after-previous` or+`with-previous` timing first.++---++## 5. Current Boundary++This script owns the semantic handoff and deterministic enhancement policy. It+does not encode video by itself. A renderer that consumes the plan must report+unsupported families instead of silently falling back to delay-only fades.diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex ed4d3ac9..f27c4f44 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -106,6 +106,24 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>**Duration guidance**: use shorter timing for repeated scan content, longer timing for conceptual pivots, section transitions, hero diagrams, and final takeaways.+**Choreography guidance**: prefer a restrained modern palette (`fade`,+`dissolve`, `zoom`, directional `fly_*`, directional `wipe_*`, and occasional+`expand`) over merely maximizing effect variety. Motion should explain the+layout:++| Page structure | Recommended choreography |+|---|---|+| Left/right comparison | Pair `fly_left` with `fly_right`; reveal the shared conclusion afterward |+| Vertical sequence or timeline | Reveal the track with `wipe_down`, then cascade items with `fly_left` or `fade` |+| Hero image plus takeaway | Bring the visual in with `dissolve` or `zoom`, then use a slower `fade` for the message |+| Dense repeated cards | Use one consistent directional effect with short stagger; do not assign a different novelty effect to every card |+| Quote or reflective breathing page | Prefer one long `fade`/`zoom` followed by a quiet note; avoid patterned effects |++Use direction only when it agrees with the object's position or reading flow.+Do not use `mixed`, `random`, blinds, checkerboard, random bars, wheel, wedge,+or swivel merely to make a deck feel “more animated”; reserve them for an+explicit visual concept or user request.+### 3.1 Supported Page Transitions| Effect | Behavior |@@ -135,9 +153,16 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>| `appear` | Visibility flip without motion || `fade` | Neutral entrance || `fly` | Fly in from bottom |+| `fly_left` | Fly in from left |+| `fly_right` | Fly in from right |+| `fly_top` | Fly in from top || `cut` | Legacy compatibility key; preserve its registered tuple exactly || `zoom` | Scale/zoom entrance |-| `wipe` | Wipe entrance |+| `wipe` | Legacy wipe tuple; keep for compatibility |+| `wipe_left` | Left wipe entrance |+| `wipe_right` | Right wipe entrance |+| `wipe_up` | Upward wipe entrance |+| `wipe_down` | Downward wipe entrance || `split` | Split/barn entrance || `blinds` | Horizontal blinds || `checkerboard` | Checkerboard reveal |@@ -282,6 +307,27 @@ Generated export performs semantic read-back per slide, comparing row order, triDirect-PPTX routes are preserve-only for object animation: they compare the source object-animation fingerprint before and after allowed edits, run structural package validation, and do not write, normalize, or claim ownership of effects. See [`pptx-animations.md`](../../scripts/docs/pptx-animations.md) for the exact compatibility and OOXML contract.+### 5.1 Optional Video Motion Handoff++When a downstream video renderer will enhance the deck, export with+`--conversion-trace` and derive its motion plan from that resolved trace:++```bash+python3 skills/ppt-master/scripts/video_motion_plan.py \+ <output>.pptx.trace.json \+ -o <project_path>/validation/video_motion_plan.json \+ --style adaptive \+ --force+```++For narrated output, the source trace must come from the final+`--recorded-narration` export. The video plan inherits object identity, source+effect, semantic direction, order, duration, native bounds, and final timing+anchors. Video-only optimization may refine easing, travel distance, opacity,+scale, mask feather, blur, motion blur, and overshoot; it must not replace the+source effect or reduce the choreography to delay values. See+[`video-motion-plan.md`](../../scripts/docs/video-motion-plan.md).+---## ✅ Customize Animations Complete@@ -295,3 +341,4 @@ Direct-PPTX routes are preserve-only for object animation: they compare the sour- [x] `animation_config.py validate` passed- [x] PPTX re-export completed with custom animation overrides- [x] Generated animation semantic read-back and package validation passed+- [x] If video enhancement was requested, its motion plan was derived from the final resolved conversion trace