| 1 | # Video Motion Plan |
| 2 | |
| 3 | `video_motion_plan.py` converts a resolved SVG-to-PPTX conversion trace into a |
| 4 | renderer-neutral motion plan. It is the handoff between PPT Master's canonical |
| 5 | custom animation and any SVG-native or post-production video renderer. |
| 6 | |
| 7 | The planner exists to prevent a video path from reducing animation to delay |
| 8 | values. The conversion trace is authoritative because it already contains the |
| 9 | resolved object target, effect, direction tuple, order, duration, offset, slide |
| 10 | advance, and native object bounds after sidecar inheritance and narration |
| 11 | synchronization. |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## 1. Generate a Resolved Source Trace |
| 16 | |
| 17 | For a narrated deck, generate the trace from the narrated export so its offsets |
| 18 | and slide advances include the final audio timing: |
| 19 | |
| 20 | ```bash |
| 21 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \ |
| 22 | --recorded-narration audio \ |
| 23 | --conversion-trace \ |
| 24 | -o <project_path>/validation/video_motion_source.pptx |
| 25 | ``` |
| 26 | |
| 27 | Then build the motion plan: |
| 28 | |
| 29 | ```bash |
| 30 | python3 skills/ppt-master/scripts/video_motion_plan.py \ |
| 31 | <project_path>/validation/video_motion_source.trace.json \ |
| 32 | -o <project_path>/validation/video_motion_plan.json \ |
| 33 | --style adaptive \ |
| 34 | --force |
| 35 | ``` |
| 36 | |
| 37 | `restrained` and `dynamic` are explicit intensity alternatives. `adaptive` is |
| 38 | the default and adjusts enhancement strength from page role, animated-object |
| 39 | count, and object area. |
| 40 | |
| 41 | --- |
| 42 | |
| 43 | ## 2. Authority and Locks |
| 44 | |
| 45 | The downstream renderer must preserve: |
| 46 | |
| 47 | - object identity and SVG group id; |
| 48 | - object order; |
| 49 | - source effect; |
| 50 | - semantic direction; |
| 51 | - resolved start time and slide timing anchor. |
| 52 | |
| 53 | The video layer may optimize only the declared `optimizer_scope` parameters: |
| 54 | easing, travel distance, opacity, scale, mask feather, blur, motion blur, and |
| 55 | overshoot. These additions can make motion feel more cinematic without |
| 56 | rewriting the presentation's choreography. |
| 57 | |
| 58 | Do not derive a video plan directly from raw `animations.json` or |
| 59 | `narration_animations.json`. Raw sidecars may still contain inheritance, |
| 60 | `auto`, timing modes, or narration-relative values. Always use the resolved |
| 61 | conversion trace. |
| 62 | |
| 63 | --- |
| 64 | |
| 65 | ## 3. Effect Mapping |
| 66 | |
| 67 | Each object keeps `source_effect` and receives a compatible video family: |
| 68 | |
| 69 | | Source effect | Video family | |
| 70 | |---|---| |
| 71 | | `entrance_appear` | `hard_reveal` | |
| 72 | | `entrance_fade` | `soft_fade` | |
| 73 | | `entrance_dissolve` | `grain_dissolve` | |
| 74 | | `entrance_fly`, `entrance_ascend` | `directional_slide` | |
| 75 | | `entrance_wipe`, `entrance_peek` | `soft_mask_reveal` | |
| 76 | | `entrance_zoom`, `entrance_expand`, `entrance_stretch` | `focus_scale` | |
| 77 | | `entrance_split` | `split_mask` | |
| 78 | | `entrance_box`, `entrance_circle`, `entrance_diamond`, `entrance_plus` | `shape_mask` | |
| 79 | | `entrance_blinds`, `entrance_checkerboard`, `entrance_random_bars`, `entrance_strips`, `entrance_wedge`, `entrance_wheel` | `pattern_reveal` | |
| 80 | | `entrance_swivel` | `soft_swivel` | |
| 81 | |
| 82 | This mapping is an enhancement contract, not permission to substitute an |
| 83 | unrelated effect. A directional slide remains directional; a wipe remains a |
| 84 | mask reveal. The retired short effect names remain readable in older |
| 85 | conversion traces, but new traces record canonical PowerPoint keys. |
| 86 | |
| 87 | --- |
| 88 | |
| 89 | ## 4. Output Contract |
| 90 | |
| 91 | The output schema is `ppt-master.video-motion-plan.v1`. Each slide records: |
| 92 | |
| 93 | - SVG source and canvas size; |
| 94 | - page role; |
| 95 | - slide duration and its source; |
| 96 | - resolved transition; |
| 97 | - ordered animated objects. |
| 98 | |
| 99 | Each object records: |
| 100 | |
| 101 | - `group_id`, native `shape_id`, and order; |
| 102 | - source effect and trigger; |
| 103 | - absolute `start_ms` and `duration_ms`; |
| 104 | - native `bounds_emu` and normalized area; |
| 105 | - renderer parameters under `video`. |
| 106 | |
| 107 | The planner rejects click-triggered animation because a rendered video has no |
| 108 | interactive click event. Re-export with click-free `after-previous` or |
| 109 | `with-previous` timing first. |
| 110 | |
| 111 | --- |
| 112 | |
| 113 | ## 5. Current Boundary |
| 114 | |
| 115 | This script owns the semantic handoff and deterministic enhancement policy. It |
| 116 | does not encode video by itself. A renderer that consumes the plan must report |
| 117 | unsupported families instead of silently falling back to delay-only fades. |
| 118 |