Release standalone PPT template workflow 0.5.0

2026-10-10 21:02:47 +08:00
commit 4e3271ff62
303 changed files with 190946 additions and 0 deletions
@@ -0,0 +1,117 @@
+# 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.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 |
+|---|---|
+| `entrance_appear` | `hard_reveal` |
+| `entrance_fade` | `soft_fade` |
+| `entrance_dissolve` | `grain_dissolve` |
+| `entrance_fly`, `entrance_ascend` | `directional_slide` |
+| `entrance_wipe`, `entrance_peek` | `soft_mask_reveal` |
+| `entrance_zoom`, `entrance_expand`, `entrance_stretch` | `focus_scale` |
+| `entrance_split` | `split_mask` |
+| `entrance_box`, `entrance_circle`, `entrance_diamond`, `entrance_plus` | `shape_mask` |
+| `entrance_blinds`, `entrance_checkerboard`, `entrance_random_bars`, `entrance_strips`, `entrance_wedge`, `entrance_wheel` | `pattern_reveal` |
+| `entrance_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. The retired short effect names remain readable in older
+conversion traces, but new traces record canonical PowerPoint keys.
+
+---
+
+## 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.