Skip to content

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

feat(animations): preserve full motion semantics for video handoff

hugohe361944e980fd2
diff --git a/skills/ppt-master/scripts/pptx_animations.py b/skills/ppt-master/scripts/pptx_animations.py
index 8c1e02ed..c78bdc0f 100644
--- a/skills/ppt-master/scripts/pptx_animations.py
+++ b/skills/ppt-master/scripts/pptx_animations.py
@@ -14,9 +14,10 @@ Supported transition effects:
- random: Random
Supported entrance animations (per-element):
- appear, fade, fly, cut, zoom, wipe, split, blinds, checkerboard,
- dissolve, random_bars, peek, wheel, box, circle, diamond, plus,
- strips, wedge, stretch, expand, swivel
+ 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
Animation modes used by the builder:
- single effect name (one of the above) — apply to every element
@@ -82,9 +83,16 @@ ANIMATIONS: dict[str, dict[str, Any]] = {
'appear': {'name': 'Appear', 'filter': None, 'presetID': 1, 'presetSubtype': 0},
'fade': {'name': 'Fade', 'filter': 'fade', 'presetID': 10, 'presetSubtype': 0},
'fly': {'name': 'Fly In', 'filter': 'slide(fromBottom)', 'presetID': 2, 'presetSubtype': 4},
+ 'fly_left': {'name': 'Fly In from Left', 'filter': 'slide(fromLeft)', 'presetID': 2, 'presetSubtype': 8},
+ 'fly_right': {'name': 'Fly In from Right', 'filter': 'slide(fromRight)', 'presetID': 2, 'presetSubtype': 2},
+ 'fly_top': {'name': 'Fly In from Top', 'filter': 'slide(fromTop)', 'presetID': 2, 'presetSubtype': 1},
'cut': {'name': 'Cut In', 'filter': 'slide(fromLeft)', 'presetID': 42, 'presetSubtype': 8},
'zoom': {'name': 'Zoom', 'filter': 'image', 'presetID': 23, 'presetSubtype': 0},
'wipe': {'name': 'Wipe', 'filter': 'wipe(left)', 'presetID': 22, 'presetSubtype': 1},
+ 'wipe_left': {'name': 'Wipe Left', 'filter': 'wipe(left)', 'presetID': 22, 'presetSubtype': 8},
+ 'wipe_right': {'name': 'Wipe Right', 'filter': 'wipe(right)', 'presetID': 22, 'presetSubtype': 2},
+ 'wipe_up': {'name': 'Wipe Up', 'filter': 'wipe(up)', 'presetID': 22, 'presetSubtype': 1},
+ 'wipe_down': {'name': 'Wipe Down', 'filter': 'wipe(down)', 'presetID': 22, 'presetSubtype': 4},
'split': {'name': 'Split', 'filter': 'barn(inVertical)', 'presetID': 16, 'presetSubtype': 21},
'blinds': {'name': 'Blinds', 'filter': 'blinds(horizontal)', 'presetID': 3, 'presetSubtype': 10},
'checkerboard': {'name': 'Checkerboard', 'filter': 'checkerboard(across)', 'presetID': 5, 'presetSubtype': 6},
diff --git a/skills/ppt-master/scripts/video_motion_plan.py b/skills/ppt-master/scripts/video_motion_plan.py
new file mode 100644
index 00000000..b0f0c144
--- /dev/null
+++ b/skills/ppt-master/scripts/video_motion_plan.py
@@ -0,0 +1,630 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Video Motion Plan
+
+Derive an effect-aware video motion plan from one resolved SVG-to-PPTX
+conversion trace. The plan preserves animation order, direction, duration,
+and timing anchors while adding deterministic video-only motion parameters.
+
+Usage:
+ python3 scripts/video_motion_plan.py <conversion_trace.json> [options]
+
+Examples:
+ python3 scripts/video_motion_plan.py exports/deck.pptx.trace.json --force
+ python3 scripts/video_motion_plan.py exports/deck.pptx.trace.json \
+ --style dynamic -o validation/video_motion_plan.json --force
+
+Dependencies:
+ None (standard library only)
+
+See scripts/docs/video-motion-plan.md for the downstream renderer contract.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Any
+from xml.etree import ElementTree as ET
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from console_encoding import configure_utf8_stdio # noqa: E402
+
+configure_utf8_stdio()
+
+
+VIDEO_MOTION_SCHEMA = "ppt-master.video-motion-plan.v1"
+VIDEO_MOTION_STYLES = ("adaptive", "restrained", "dynamic")
+_STYLE_MULTIPLIERS = {
+ "adaptive": 1.0,
+ "restrained": 0.72,
+ "dynamic": 1.28,
+}
+_SVG_NS = "http://www.w3.org/2000/svg"
+_EMU_PER_PX = 9525
+_NUMBER_RE = re.compile(r"[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?")
+
+
+def _read_json_object(path: Path) -> dict[str, Any]:
+ try:
+ value = json.loads(path.read_text(encoding="utf-8"))
+ except FileNotFoundError as exc:
+ raise ValueError(f"conversion trace not found: {path}") from exc
+ except json.JSONDecodeError as exc:
+ raise ValueError(f"invalid conversion trace JSON: {path}: {exc}") from exc
+ if not isinstance(value, dict):
+ raise ValueError(f"conversion trace must be a JSON object: {path}")
+ return value
+
+
+def _positive_int(value: object, field: str) -> int:
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+ raise ValueError(f"{field} must be a positive integer: {value!r}")
+ return value
+
+
+def _non_negative_int(value: object, field: str) -> int:
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+ raise ValueError(f"{field} must be a non-negative integer: {value!r}")
+ return value
+
+
+def _finite_positive_float(value: object, field: str) -> float:
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ raise ValueError(f"{field} must be a finite positive number: {value!r}")
+ number = float(value)
+ if not math.isfinite(number) or number <= 0:
+ raise ValueError(f"{field} must be a finite positive number: {value!r}")
+ return number
+
+
+def _resolve_svg_path(raw: object, trace_path: Path) -> Path:
+ if not isinstance(raw, str) or not raw.strip():
+ raise ValueError("conversion trace slide is missing its SVG path")
+ path = Path(raw)
+ if path.is_absolute() and path.is_file():
+ return path
+
+ candidates = [Path.cwd() / path, trace_path.parent / path]
+ candidates.extend(parent / path for parent in trace_path.parents)
+ for candidate in candidates:
+ if candidate.is_file():
+ return candidate.resolve()
+ raise ValueError(
+ f"SVG referenced by conversion trace was not found: {raw}; "
+ "run the command from the repository root or regenerate the trace"
+ )
+
+
+def _parse_canvas_emu(svg_path: Path) -> tuple[int, int]:
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError) as exc:
+ raise ValueError(f"cannot read SVG canvas: {svg_path}: {exc}") from exc
+
+ values = [
+ float(match)
+ for match in _NUMBER_RE.findall(root.get("viewBox") or "")
+ ]
+ if len(values) != 4 or values[2] <= 0 or values[3] <= 0:
+ raise ValueError(f"SVG must have a positive four-number viewBox: {svg_path}")
+ return (
+ max(1, round(values[2] * _EMU_PER_PX)),
+ max(1, round(values[3] * _EMU_PER_PX)),
+ )
+
+
+def _event_score(event: dict[str, Any]) -> int:
+ score = 0
+ if event.get("tag") == "g":
+ score += 4
+ if isinstance(event.get("id"), str) and event["id"].strip():
+ score += 2
+ if event.get("decision") == "native":
+ score += 1
+ return score
+
+
+def _shape_events(slide: dict[str, Any]) -> dict[int, dict[str, Any]]:
+ events = slide.get("events", [])
+ if not isinstance(events, list):
+ raise ValueError("conversion trace slide events must be a list")
+ selected: dict[int, dict[str, Any]] = {}
+ for raw_event in events:
+ if not isinstance(raw_event, dict):
+ continue
+ shape_id = raw_event.get("shape_id")
+ bounds = raw_event.get("bounds_emu")
+ if (
+ isinstance(shape_id, int)
+ and shape_id > 0
+ and isinstance(bounds, list)
+ and len(bounds) == 4
+ and all(isinstance(value, int) for value in bounds)
+ ):
+ current = selected.get(shape_id)
+ if current is None or _event_score(raw_event) >= _event_score(current):
+ selected[shape_id] = raw_event
+ return selected
+
+
+def _direction_for_effect(effect: str, filter_name: object) -> str | None:
+ explicit = {
+ "fly": "down",
+ "fly_left": "left",
+ "fly_right": "right",
+ "fly_top": "up",
+ "cut": "left",
+ "wipe": "left",
+ "wipe_left": "left",
+ "wipe_right": "right",
+ "wipe_up": "up",
+ "wipe_down": "down",
+ "peek": "down",
+ "strips": "down-right",
+ }
+ if effect in explicit:
+ return explicit[effect]
+ if isinstance(filter_name, str):
+ match = re.search(
+ r"\((?:from)?(Top|Bottom|Left|Right|Up|Down)\)",
+ filter_name,
+ re.IGNORECASE,
+ )
+ if match:
+ value = match.group(1).lower()
+ return {"top": "up", "bottom": "down"}.get(value, value)
+ return None
+
+
+def _area_ratio(bounds: list[int], canvas_emu: tuple[int, int]) -> float:
+ width = max(0, bounds[2] - bounds[0])
+ height = max(0, bounds[3] - bounds[1])
+ canvas_area = canvas_emu[0] * canvas_emu[1]
+ return (width * height / canvas_area) if canvas_area else 0.0
+
+
+def _adaptive_multiplier(
+ style: str,
+ page_role: object,
+ object_count: int,
+ area_ratio: float,
+) -> float:
+ multiplier = _STYLE_MULTIPLIERS[style]
+ if style == "adaptive":
+ if page_role in {"cover", "hero", "closing", "section"}:
+ multiplier *= 1.08
+ if object_count >= 5:
+ multiplier *= 0.82
+ elif object_count == 1:
+ multiplier *= 1.06
+ if area_ratio >= 0.42:
+ multiplier *= 0.78
+ elif 0 < area_ratio <= 0.10:
+ multiplier *= 1.08
+ return max(0.55, min(1.45, multiplier))
+
+
+def _travel_vector(direction: str | None, magnitude: float) -> list[float]:
+ vectors = {
+ "left": [-magnitude, 0.0],
+ "right": [magnitude, 0.0],
+ "up": [0.0, -magnitude],
+ "down": [0.0, magnitude],
+ "down-right": [magnitude * 0.72, magnitude * 0.72],
+ }
+ return [round(value, 4) for value in vectors.get(direction, [0.0, 0.0])]
+
+
+def _video_effect(
+ effect: str,
+ direction: str | None,
+ multiplier: float,
+) -> dict[str, Any]:
+ common: dict[str, Any] = {
+ "easing": "ease_out_cubic",
+ "opacity_from": 0.0,
+ "scale_from": 1.0,
+ "travel_canvas_ratio": [0.0, 0.0],
+ "blur_px": 0.0,
+ "overshoot": 0.0,
+ "mask_feather_px": 0.0,
+ "motion_blur": 0.0,
+ }
+
+ if effect == "appear":
+ common.update({
+ "family": "hard_reveal",
+ "opacity_from": 1.0,
+ "easing": "step_end",
+ })
+ elif effect == "fade":
+ common.update({
+ "family": "soft_fade",
+ "scale_from": round(1.0 - 0.008 * multiplier, 4),
+ "blur_px": round(3.0 * multiplier, 2),
+ })
+ elif effect == "dissolve":
+ common.update({
+ "family": "grain_dissolve",
+ "scale_from": round(1.0 - 0.006 * multiplier, 4),
+ "blur_px": round(2.0 * multiplier, 2),
+ "grain": round(0.26 * multiplier, 3),
+ })
+ elif effect in {"fly", "fly_left", "fly_right", "fly_top", "cut"}:
+ magnitude = 0.045 * multiplier
+ common.update({
+ "family": "directional_slide",
+ "direction": direction,
+ "travel_canvas_ratio": _travel_vector(direction, magnitude),
+ "blur_px": round(4.5 * multiplier, 2),
+ "overshoot": round(0.012 * multiplier, 4),
+ "motion_blur": round(0.22 * multiplier, 3),
+ })
+ elif effect in {
+ "wipe",
+ "wipe_left",
+ "wipe_right",
+ "wipe_up",
+ "wipe_down",
+ "peek",
+ }:
+ common.update({
+ "family": "soft_mask_reveal",
+ "direction": direction,
+ "travel_canvas_ratio": _travel_vector(
+ direction,
+ 0.012 * multiplier,
+ ),
+ "mask_feather_px": round(18.0 * multiplier, 2),
+ "blur_px": round(1.5 * multiplier, 2),
+ })
+ elif effect in {"zoom", "expand", "stretch"}:
+ common.update({
+ "family": "focus_scale",
+ "scale_from": round(1.0 - 0.055 * multiplier, 4),
+ "blur_px": round(3.5 * multiplier, 2),
+ "overshoot": round(0.008 * multiplier, 4),
+ })
+ elif effect == "split":
+ common.update({
+ "family": "split_mask",
+ "mask_axis": "vertical",
+ "mask_feather_px": round(12.0 * multiplier, 2),
+ })
+ elif effect in {"box", "circle", "diamond", "plus"}:
+ common.update({
+ "family": "shape_mask",
+ "pattern": effect,
+ "scale_from": round(1.0 - 0.025 * multiplier, 4),
+ "mask_feather_px": round(10.0 * multiplier, 2),
+ })
+ elif effect in {
+ "blinds",
+ "checkerboard",
+ "random_bars",
+ "strips",
+ "wedge",
+ "wheel",
+ }:
+ common.update({
+ "family": "pattern_reveal",
+ "pattern": effect,
+ "mask_feather_px": round(8.0 * multiplier, 2),
+ })
+ elif effect == "swivel":
+ common.update({
+ "family": "soft_swivel",
+ "scale_from": round(1.0 - 0.025 * multiplier, 4),
+ "rotation_from_deg": round(-4.0 * multiplier, 2),
+ "blur_px": round(3.0 * multiplier, 2),
+ })
+ else:
+ raise ValueError(f"unsupported resolved animation effect for video: {effect}")
+ return common
+
+
+def _transition_plan(raw_motion: object) -> dict[str, Any]:
+ if not isinstance(raw_motion, dict):
+ return {
+ "source_effect": None,
+ "video_effect": "cut",
+ "duration_ms": 0,
+ "easing": "linear",
+ }
+ effect = raw_motion.get("effect")
+ duration = raw_motion.get("duration_ms")
+ if effect is None:
+ video_effect = "cut"
+ elif effect == "fade":
+ video_effect = "crossfade"
+ elif effect in {"push", "cover"}:
+ video_effect = "directional_push"
+ elif effect in {"wipe", "split", "strips"}:
+ video_effect = f"soft_{effect}"
+ else:
+ video_effect = "adaptive_crossfade"
+ return {
+ "source_effect": effect,
+ "video_effect": video_effect,
+ "duration_ms": duration if isinstance(duration, int) else 0,
+ "easing": "ease_in_out_cubic",
+ }
+
+
+def build_video_motion_plan(
+ trace_path: str | Path,
+ *,
+ style: str = "adaptive",
+ default_slide_duration: float = 5.0,
+) -> dict[str, Any]:
+ """Build one renderer-neutral, effect-aware video motion plan."""
+ path = Path(trace_path).resolve()
+ if style not in VIDEO_MOTION_STYLES:
+ raise ValueError(
+ f"unknown video motion style {style!r}; valid styles: "
+ f"{', '.join(VIDEO_MOTION_STYLES)}"
+ )
+ default_duration_ms = round(
+ _finite_positive_float(
+ default_slide_duration,
+ "default slide duration",
+ )
+ * 1000
+ )
+ trace = _read_json_object(path)
+ raw_slides = trace.get("slides")
+ if not isinstance(raw_slides, list) or not raw_slides:
+ raise ValueError("conversion trace must contain a non-empty slides list")
+
+ slides: list[dict[str, Any]] = []
+ total_objects = 0
+ enhanced_objects = 0
+ for raw_slide in raw_slides:
+ if not isinstance(raw_slide, dict):
+ raise ValueError("conversion trace slide entries must be objects")
+ slide_num = _positive_int(raw_slide.get("slide_num"), "slide_num")
+ svg_path = _resolve_svg_path(raw_slide.get("svg"), path)
+ canvas_emu = _parse_canvas_emu(svg_path)
+ event_index = _shape_events(raw_slide)
+
+ animation = raw_slide.get("animation", {})
+ if not isinstance(animation, dict):
+ raise ValueError(f"slide {slide_num} animation summary must be an object")
+ rows = animation.get("rows", [])
+ if not isinstance(rows, list):
+ raise ValueError(f"slide {slide_num} animation rows must be a list")
+
+ objects: list[dict[str, Any]] = []
+ for order, raw_row in enumerate(rows, 1):
+ if not isinstance(raw_row, dict):
+ raise ValueError(f"slide {slide_num} animation row must be an object")
+ shape_id = _positive_int(
+ raw_row.get("shape_id"),
+ f"slide {slide_num} animation shape_id",
+ )
+ trigger = raw_row.get("trigger")
+ if trigger == "on-click":
+ raise ValueError(
+ f"slide {slide_num} uses on-click animation; video motion "
+ "requires click-free after-previous or with-previous timing"
+ )
+ if trigger not in {"after-previous", "with-previous"}:
+ raise ValueError(
+ f"slide {slide_num} has unsupported video trigger: {trigger!r}"
+ )
+ effect = raw_row.get("effect")
+ if not isinstance(effect, str) or not effect:
+ raise ValueError(
+ f"slide {slide_num} animation row has no resolved effect"
+ )
+ start_ms = _non_negative_int(
+ raw_row.get("offset_ms"),
+ f"slide {slide_num} animation offset_ms",
+ )
+ duration_ms = _positive_int(
+ raw_row.get("duration_ms"),
+ f"slide {slide_num} animation duration_ms",
+ )
+ event = event_index.get(shape_id)
+ if event is None:
+ raise ValueError(
+ f"slide {slide_num} animation shape {shape_id} has no "
+ "conversion-trace bounds"
+ )
+ bounds = list(event["bounds_emu"])
+ area_ratio = _area_ratio(bounds, canvas_emu)
+ multiplier = _adaptive_multiplier(
+ style,
+ raw_slide.get("page_role"),
+ len(rows),
+ area_ratio,
+ )
+ direction = _direction_for_effect(
+ effect,
+ raw_row.get("filter_name"),
+ )
+ video = _video_effect(effect, direction, multiplier)
+ video["duration_ms"] = duration_ms
+
+ group_id = event.get("id")
+ if not isinstance(group_id, str) or not group_id.strip():
+ group_id = f"shape-{shape_id}"
+ objects.append({
+ "group_id": group_id,
+ "shape_id": shape_id,
+ "order": order,
+ "source_effect": effect,
+ "trigger": trigger,
+ "start_ms": start_ms,
+ "duration_ms": duration_ms,
+ "bounds_emu": bounds,
+ "area_ratio": round(area_ratio, 6),
+ "video": video,
+ })
+ total_objects += 1
+ if video["family"] != "hard_reveal":
+ enhanced_objects += 1
+
+ motion = raw_slide.get("motion")
+ advance_after_ms = (
+ motion.get("advance_after_ms")
+ if isinstance(motion, dict)
+ else None
+ )
+ content_end_ms = max(
+ (
+ item["start_ms"] + item["duration_ms"]
+ for item in objects
+ ),
+ default=0,
+ )
+ if isinstance(advance_after_ms, int) and advance_after_ms > 0:
+ slide_duration_ms = max(advance_after_ms, content_end_ms)
+ duration_source = "recorded-advance"
+ else:
+ slide_duration_ms = max(default_duration_ms, content_end_ms + 750)
+ duration_source = "default-hold"
+
+ slides.append({
+ "slide_num": slide_num,
+ "svg": str(svg_path),
+ "page_role": raw_slide.get("page_role"),
+ "canvas_emu": list(canvas_emu),
+ "duration_ms": slide_duration_ms,
+ "duration_source": duration_source,
+ "transition": _transition_plan(motion),
+ "objects": objects,
+ })
+
+ return {
+ "schema": VIDEO_MOTION_SCHEMA,
+ "source_trace": str(path),
+ "source_pptx": trace.get("output"),
+ "style": style,
+ "locks": {
+ "object_identity": True,
+ "object_order": True,
+ "semantic_direction": True,
+ "timing_anchor": True,
+ "source_effect": True,
+ },
+ "optimizer_scope": [
+ "easing",
+ "travel_distance",
+ "opacity",
+ "scale",
+ "mask_feather",
+ "blur",
+ "motion_blur",
+ "overshoot",
+ ],
+ "slide_count": len(slides),
+ "object_count": total_objects,
+ "enhanced_object_count": enhanced_objects,
+ "slides": slides,
+ }
+
+
+def write_video_motion_plan(
+ trace_path: str | Path,
+ output_path: str | Path,
+ *,
+ style: str = "adaptive",
+ default_slide_duration: float = 5.0,
+ force: bool = False,
+) -> Path:
+ """Build and write one video motion plan."""
+ output = Path(output_path)
+ if output.exists() and not force:
+ raise FileExistsError(
+ f"output already exists: {output}; pass --force to overwrite"
+ )
+ plan = build_video_motion_plan(
+ trace_path,
+ style=style,
+ default_slide_duration=default_slide_duration,
+ )
+ output.parent.mkdir(parents=True, exist_ok=True)
+ output.write_text(
+ json.dumps(plan, ensure_ascii=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ return output.resolve()
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ description=(
+ "Derive an effect-aware video motion plan from a resolved "
+ "SVG-to-PPTX conversion trace."
+ ),
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("trace", help="Path to <output>.pptx.trace.json")
+ parser.add_argument(
+ "-o",
+ "--output",
+ default=None,
+ help="Output JSON path; default: <trace>.video-motion.json",
+ )
+ parser.add_argument(
+ "--style",
+ choices=VIDEO_MOTION_STYLES,
+ default="adaptive",
+ help="Video-only enhancement intensity; default: adaptive",
+ )
+ parser.add_argument(
+ "--default-slide-duration",
+ type=float,
+ default=5.0,
+ help="Fallback seconds for slides without recorded advance timing",
+ )
+ parser.add_argument(
+ "--force",
+ action="store_true",
+ help="Overwrite an existing output plan",
+ )
+ return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = build_parser()
+ args = parser.parse_args(argv)
+ trace_path = Path(args.trace)
+ output_path = (
+ Path(args.output)
+ if args.output
+ else trace_path.with_suffix(".video-motion.json")
+ )
+ try:
+ written = write_video_motion_plan(
+ trace_path,
+ output_path,
+ style=args.style,
+ default_slide_duration=args.default_slide_duration,
+ force=args.force,
+ )
+ except (FileExistsError, ValueError) as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+
+ plan = _read_json_object(written)
+ print(written)
+ print(
+ f"Slides: {plan['slide_count']}; objects: {plan['object_count']}; "
+ f"video-enhanced: {plan['enhanced_object_count']}",
+ file=sys.stderr,
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())