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:

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:

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.

3.9 KiB Raw Blame History