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(svg_to_pptx): per-element entrance animations on PPTX export

hugohe3b2da3073066f
diff --git a/skills/ppt-master/scripts/pptx_animations.py b/skills/ppt-master/scripts/pptx_animations.py
index 9b3c95be..5a114b8d 100644
--- a/skills/ppt-master/scripts/pptx_animations.py
+++ b/skills/ppt-master/scripts/pptx_animations.py
@@ -13,11 +13,14 @@ Supported transition effects:
- cover: Cover
- random: Random
-Supported entrance animations:
- - fade: Fade in
- - fly: Fly in
- - zoom: Zoom
- - appear: Appear
+Supported entrance animations (per-element):
+ appear, fade, fly, zoom, wipe, split, blinds,
+ dissolve, peek, wheel, box, circle
+
+Animation modes used by the builder:
+ - single effect name (one of the above) — apply to every element
+ - 'mixed' — first element fade, the rest cycle through a curated pool
+ - 'random' — pick a random effect per element
Dependencies: None (pure XML generation)
"""
@@ -115,27 +118,31 @@ def create_transition_xml(
# Entrance animation definitions
# ============================================================================
+#
+# 'filter' values must be valid PowerPoint <p:animEffect filter=".."/> strings
+# (see ECMA-376 §19.5.10 ST_TLAnimateEffectTransition / filter dictionary).
+# Effects with filter=None render as plain "Appear" (visibility flip only).
+#
ANIMATIONS: Dict[str, Dict[str, Any]] = {
- 'fade': {
- 'name': 'Fade In',
- 'filter': 'fade',
- },
- 'fly': {
- 'name': 'Fly In',
- 'filter': 'fly',
- 'prLst': 'from(b)', # Fly in from bottom
- },
- 'zoom': {
- 'name': 'Zoom',
- 'filter': 'zoom',
- 'prLst': 'in',
- },
- 'appear': {
- 'name': 'Appear',
- 'filter': None, # No filter, only sets visibility
- },
+ 'appear': {'name': 'Appear', 'filter': None},
+ 'fade': {'name': 'Fade', 'filter': 'fade'},
+ 'fly': {'name': 'Fly In', 'filter': 'slide', 'prLst': 'from(b)'},
+ 'zoom': {'name': 'Zoom', 'filter': 'image'},
+ 'wipe': {'name': 'Wipe', 'filter': 'wipe', 'prLst': 'from(l)'},
+ 'split': {'name': 'Split', 'filter': 'barn', 'prLst': 'inHorizontal'},
+ 'blinds': {'name': 'Blinds', 'filter': 'blinds', 'prLst': 'horizontal'},
+ 'dissolve': {'name': 'Dissolve', 'filter': 'dissolve'},
+ 'peek': {'name': 'Peek', 'filter': 'wipe', 'prLst': 'from(b)'},
+ 'wheel': {'name': 'Wheel', 'filter': 'wheel', 'prLst': 'spokes(1)'},
+ 'box': {'name': 'Box', 'filter': 'box', 'prLst': 'in'},
+ 'circle': {'name': 'Circle', 'filter': 'circle', 'prLst': 'in'},
}
+# Pool used by 'mixed' / 'random' modes. Excludes 'appear' (no visible motion)
+# and keeps the first slot ('fade') for the title-like first element.
+_MIXED_POOL = ['fade', 'fly', 'zoom', 'wipe', 'peek', 'blinds',
+ 'dissolve', 'split', 'wheel', 'box']
+
def create_timing_xml(
animation: str = 'fade',
@@ -233,6 +240,130 @@ def create_timing_xml(
</p:timing>'''
+def _build_effect_xml(
+ animation: str,
+ shape_id: int,
+ duration_ms: int,
+ set_id: int,
+ eff_id: int,
+) -> str:
+ """Inner <p:set>/<p:animEffect> pair for one target."""
+ anim_info = ANIMATIONS.get(animation, ANIMATIONS['fade'])
+ set_block = f'''<p:set>
+ <p:cBhvr>
+ <p:cTn id="{set_id}" dur="1" fill="hold">
+ <p:stCondLst><p:cond delay="0"/></p:stCondLst>
+ </p:cTn>
+ <p:tgtEl><p:spTgt spid="{shape_id}"/></p:tgtEl>
+ <p:attrNameLst><p:attrName>style.visibility</p:attrName></p:attrNameLst>
+ </p:cBhvr>
+ <p:to><p:strVal val="visible"/></p:to>
+</p:set>'''
+ if anim_info['filter'] is None:
+ return set_block
+ pr_attr = f' prLst="{anim_info["prLst"]}"' if 'prLst' in anim_info else ''
+ return set_block + f'''
+<p:animEffect transition="in" filter="{anim_info["filter"]}"{pr_attr}>
+ <p:cBhvr>
+ <p:cTn id="{eff_id}" dur="{duration_ms}"/>
+ <p:tgtEl><p:spTgt spid="{shape_id}"/></p:tgtEl>
+ </p:cBhvr>
+</p:animEffect>'''
+
+
+def create_sequence_timing_xml(
+ targets: list,
+ duration: float = 0.3,
+) -> str:
+ """Generate a multi-target entrance sequence triggered by one click.
+
+ Args:
+ targets: list of (shape_id, delay_ms, animation_name) tuples,
+ in the order they should play. The first element triggers on
+ click; subsequent elements use ``afterEffect`` chaining and
+ their ``delay_ms`` becomes the gap after the previous element
+ finishes.
+ duration: per-element entrance duration in seconds.
+
+ Returns:
+ A ``<p:timing>`` element string. Returns an empty string when
+ ``targets`` is empty.
+ """
+ if not targets:
+ return ''
+
+ dur_ms = int(duration * 1000)
+ steps = []
+ for i, target in enumerate(targets):
+ shape_id, delay_ms, animation = target
+ if animation not in ANIMATIONS:
+ animation = 'fade'
+ node_type = 'clickEffect' if i == 0 else 'afterEffect'
+ base = 3 + 4 * i
+ outer_id, inner_id, set_id, eff_id = base, base + 1, base + 2, base + 3
+ effect_xml = _build_effect_xml(animation, shape_id, dur_ms, set_id, eff_id)
+ steps.append(f'''<p:par>
+ <p:cTn id="{outer_id}" fill="hold" nodeType="{node_type}">
+ <p:stCondLst><p:cond delay="{delay_ms}"/></p:stCondLst>
+ <p:childTnLst>
+ <p:par>
+ <p:cTn id="{inner_id}" fill="hold">
+ <p:childTnLst>
+ {effect_xml}
+ </p:childTnLst>
+ </p:cTn>
+ </p:par>
+ </p:childTnLst>
+ </p:cTn>
+</p:par>''')
+
+ bld_list = '\n '.join(
+ f'<p:bldP spid="{sid}" grpId="0"/>' for sid, _, _ in targets
+ )
+ all_steps = '\n '.join(steps)
+ return f''' <p:timing>
+ <p:tnLst>
+ <p:par>
+ <p:cTn id="1" dur="indefinite" nodeType="tmRoot">
+ <p:childTnLst>
+ <p:seq concurrent="1" nextAc="seek">
+ <p:cTn id="2" dur="indefinite" nodeType="mainSeq">
+ <p:childTnLst>
+ {all_steps}
+ </p:childTnLst>
+ </p:cTn>
+ </p:seq>
+ </p:childTnLst>
+ </p:cTn>
+ </p:par>
+ </p:tnLst>
+ <p:bldLst>
+ {bld_list}
+ </p:bldLst>
+ </p:timing>'''
+
+
+def pick_animation_effect(mode: str, idx: int) -> str:
+ """Resolve a per-element effect name from a mode string.
+
+ - A specific animation name returns itself (no variation).
+ - 'mixed': first element fixed to 'fade', rest cycle through ``_MIXED_POOL``
+ starting at index 1 (so titles stay calm while content varies).
+ - 'random': uniform random choice from ``_MIXED_POOL``.
+ - Unknown mode falls back to 'fade'.
+ """
+ if mode in ANIMATIONS:
+ return mode
+ if mode == 'mixed':
+ if idx == 0:
+ return 'fade'
+ return _MIXED_POOL[(idx - 1) % (len(_MIXED_POOL) - 1) + 1]
+ if mode == 'random':
+ import random
+ return random.choice(_MIXED_POOL)
+ return 'fade'
+
+
def get_available_transitions() -> list:
"""Get a list of all available transition effects"""
return list(TRANSITIONS.keys())
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
index 8fb946ac..f0d1a89c 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
@@ -36,6 +36,11 @@ class ConvertContext:
rel_id_counter: int = 2 # rId1 reserved for slideLayout
svg_dir: Path | None = None
inherited_styles: dict[str, str] = field(default_factory=dict)
+ # Recursion depth — only the depth==0 (root) context records anim targets.
+ depth: int = 0
+ # Top-level <g id="..."> groups, recorded as (shape_id, svg_id) in z-order.
+ # Used by the PPTX builder to emit per-element entrance timing.
+ anim_targets: list = field(default_factory=list)
def next_id(self) -> int:
"""Allocate the next shape ID."""
@@ -102,6 +107,9 @@ class ConvertContext:
rel_id_counter=self.rel_id_counter,
svg_dir=self.svg_dir,
inherited_styles=merged,
+ depth=self.depth + 1,
+ # anim_targets is intentionally a fresh list on the child;
+ # only the root-level context's list is read by the builder.
)
def sync_from_child(self, child_ctx: ConvertContext) -> None:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
index 3cf6fa79..356e1db5 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
@@ -113,6 +113,15 @@ def convert_g(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
shapes_xml = '\n'.join(result.xml for result in child_results)
group_id = ctx.next_id()
+ # Record top-level semantic groups (e.g. <g id="p02-title">) so the
+ # PPTX builder can emit per-element entrance timing. Only the outermost
+ # multi-child wrapper qualifies — flattened single-child groups have no
+ # <p:grpSp> to anchor a timing target on, and nested groups are
+ # ignored to keep the animation budget at ~per-section granularity.
+ elem_id = elem.get('id')
+ if ctx.depth == 0 and elem_id:
+ ctx.anim_targets.append((group_id, elem_id))
+
group_effect = ''
if filter_id and filter_id in ctx.defs:
group_effect = build_effect_xml(ctx.defs[filter_id])
@@ -198,7 +207,7 @@ def convert_svg_to_slide_shapes(
svg_path: Path,
slide_num: int = 1,
verbose: bool = False,
-) -> tuple[str, dict[str, bytes], list[dict[str, str]]]:
+) -> tuple[str, dict[str, bytes], list[dict[str, str]], list]:
"""Convert an SVG file to a complete DrawingML slide XML.
Args:
@@ -207,10 +216,13 @@ def convert_svg_to_slide_shapes(
verbose: Print progress info.
Returns:
- (slide_xml, media_files, rel_entries) where:
+ (slide_xml, media_files, rel_entries, anim_targets) where:
- slide_xml: Complete slide XML string.
- media_files: Dict of {filename: bytes} for media to write.
- rel_entries: List of relationship entries to add.
+ - anim_targets: List of (shape_id, svg_id) tuples for top-level
+ semantic groups, in z-order; consumed by the builder's optional
+ per-element entrance timing emitter.
"""
tree = ET.parse(str(svg_path))
root = tree.getroot()
@@ -221,6 +233,9 @@ def convert_svg_to_slide_shapes(
shapes: list[str] = []
converted = 0
skipped = 0
+ # Per-element shape ids of every top-level child, used as an animation
+ # fallback when no <g id="..."> groups are present at the root.
+ fallback_targets: list = []
for child in root:
tag = child.tag.replace(f'{{{SVG_NS}}}', '')
@@ -230,10 +245,23 @@ def convert_svg_to_slide_shapes(
if result:
shapes.append(result.xml)
converted += 1
+ m = re.search(r'<p:cNvPr id="(\d+)"', result.xml)
+ if m:
+ fallback_targets.append((int(m.group(1)), tag))
else:
if tag not in _NON_VISUAL_TAGS:
skipped += 1
+ # Animation target fallback. Semantic <g id="..."> groups are the
+ # preferred anchors (set inside convert_g). When the SVG has none
+ # at the root we fall back to top-level primitives, but only when
+ # the count is reasonable — dense pages (consulting decks, charts,
+ # diagrams) routinely have 70–150 atoms at the root and animating
+ # each one is unusable, so we silently skip animation past the cap.
+ _ANIM_FALLBACK_CAP = 20
+ if not ctx.anim_targets and 0 < len(fallback_targets) <= _ANIM_FALLBACK_CAP:
+ ctx.anim_targets = fallback_targets
+
if verbose:
print(f' Converted {converted} elements, skipped {skipped}')
@@ -259,4 +287,4 @@ def convert_svg_to_slide_shapes(
<p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr>
</p:sld>'''
- return slide_xml, ctx.media_files, ctx.rel_entries
+ return slide_xml, ctx.media_files, ctx.rel_entries, ctx.anim_targets
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
index 472d3629..da0026b6 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
@@ -33,9 +33,15 @@ from .pptx_slide_xml import (
# Re-import create_transition_xml only if available
try:
- from pptx_animations import create_transition_xml
+ from pptx_animations import (
+ create_transition_xml,
+ create_sequence_timing_xml,
+ pick_animation_effect,
+ )
except ImportError:
create_transition_xml = None
+ create_sequence_timing_xml = None
+ pick_animation_effect = None
def _append_relationship(
@@ -75,6 +81,9 @@ def create_pptx_with_native_svg(
notes: dict[str, str] | None = None,
enable_notes: bool = True,
use_native_shapes: bool = False,
+ animation: str | None = None,
+ animation_duration: float = 0.3,
+ animation_stagger: float = 0.1,
) -> bool:
"""Create a PPTX file with native SVG.
@@ -90,6 +99,10 @@ def create_pptx_with_native_svg(
notes: Notes dict, key is SVG stem, value is notes content.
enable_notes: Whether to enable notes embedding.
use_native_shapes: Convert SVG to native DrawingML shapes.
+ animation: Per-element entrance animation mode (single effect name,
+ 'mixed', 'random', or None to disable). Native shapes mode only.
+ animation_duration: Per-element entrance duration in seconds.
+ animation_stagger: Auto-cascade gap between elements in seconds.
Returns:
Whether all slides were successfully created.
@@ -186,11 +199,16 @@ def create_pptx_with_native_svg(
try:
# ---- Native shapes mode ----
if use_native_shapes:
- slide_xml, media_files_dict, rel_entries = convert_svg_to_slide_shapes(
- svg_path, slide_num=slide_num, verbose=verbose,
+ slide_xml, media_files_dict, rel_entries, anim_targets = (
+ convert_svg_to_slide_shapes(
+ svg_path, slide_num=slide_num, verbose=verbose,
+ )
)
- # Add transition if specified
+ # Order matters: OOXML schema requires <p:transition>
+ # to precede <p:timing> inside <p:sld>. Both use the same
+ # </p:sld> string-replace anchor, so transition must be
+ # injected first and timing second.
if transition and ANIMATIONS_AVAILABLE and create_transition_xml:
transition_xml = '\n' + create_transition_xml(
effect=transition,
@@ -202,6 +220,25 @@ def create_pptx_with_native_svg(
transition_xml + '\n</p:sld>',
)
+ if (animation and animation != 'none'
+ and create_sequence_timing_xml
+ and pick_animation_effect
+ and anim_targets):
+ stagger_ms = int(animation_stagger * 1000)
+ seq_targets = [
+ (sid,
+ 0 if idx == 0 else stagger_ms,
+ pick_animation_effect(animation, idx))
+ for idx, (sid, _svg_id) in enumerate(anim_targets)
+ ]
+ timing_xml = '\n' + create_sequence_timing_xml(
+ seq_targets, duration=animation_duration,
+ )
+ slide_xml = slide_xml.replace(
+ '</p:sld>',
+ timing_xml + '\n</p:sld>',
+ )
+
# Write slide XML
slide_xml_path = extract_dir / 'ppt' / 'slides' / f'slide{slide_num}.xml'
with open(slide_xml_path, 'w', encoding='utf-8') as f:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
index ec45f22b..aecf9f3d 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -13,6 +13,11 @@ from .pptx_discovery import find_svg_files, find_notes_files
from .pptx_builder import create_pptx_with_native_svg
from .pptx_slide_xml import TRANSITIONS
+try:
+ from pptx_animations import ANIMATIONS as _ANIMATIONS
+except ImportError:
+ _ANIMATIONS = {}
+
def main() -> None:
"""CLI entry point for the SVG to PPTX conversion tool."""
@@ -21,6 +26,12 @@ def main() -> None:
else ['fade', 'push', 'wipe', 'split', 'strips', 'cover', 'random'])
)
+ animation_choices = (
+ ['none'] + (list(_ANIMATIONS.keys()) if _ANIMATIONS
+ else ['fade', 'fly', 'zoom', 'appear'])
+ + ['mixed', 'random']
+ )
+
parser = argparse.ArgumentParser(
description='PPT Master - SVG to PPTX Tool (Office Compatibility Mode)',
formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -43,6 +54,11 @@ SVG source directory (-s):
Transition effects (-t/--transition):
{', '.join(transition_choices)}
+Per-element entrance animation (-a/--animation, native shapes mode):
+ {', '.join(animation_choices)}
+ Notes: applied to top-level <g id="..."> SVG groups in z-order.
+ First click triggers the cascade; --animation-stagger sets the gap.
+
Compatibility mode (enabled by default):
- Automatically generates PNG fallback images, SVG embedded as extension
- Compatible with all Office versions (including Office LTSC 2021)
@@ -84,6 +100,16 @@ Speaker notes (enabled by default):
parser.add_argument('--auto-advance', type=float, default=None,
help='Auto-advance interval in seconds (default: manual advance)')
+ parser.add_argument('-a', '--animation', type=str, choices=animation_choices,
+ default='none',
+ help='Per-element entrance animation (native shapes mode '
+ 'only). Pick a single effect, "mixed" (auto-vary per '
+ 'element), "random", or "none" (default).')
+ parser.add_argument('--animation-duration', type=float, default=0.3,
+ help='Per-element entrance duration in seconds (default: 0.3)')
+ parser.add_argument('--animation-stagger', type=float, default=0.1,
+ help='Auto-cascade gap between elements in seconds (default: 0.1)')
+
parser.add_argument('--no-notes', action='store_true',
help='Disable speaker notes embedding (enabled by default)')
@@ -149,6 +175,7 @@ Speaker notes (enabled by default):
notes = find_notes_files(project_path, svg_files)
transition = args.transition if args.transition != 'none' else None
+ animation = args.animation if args.animation != 'none' else None
shared_kwargs = dict(
svg_files=svg_files,
@@ -160,6 +187,9 @@ Speaker notes (enabled by default):
use_compat_mode=not args.no_compat,
notes=notes,
enable_notes=enable_notes,
+ animation=animation,
+ animation_duration=args.animation_duration,
+ animation_stagger=args.animation_stagger,
)
success = True