118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# 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.
|