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
docs(animation): align video anchors and narration motion wording
hugohe3f92bf8cb793c
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex fbbba7dc..686268ab 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -512,7 +512,7 @@ Generate routing selects one runtime authority before loading its procedure: [`wGlobal stop/continue policy is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/governance/failure-recovery.md); its concrete recovery matrix and resume pointers currently cover Generate PPTX. This section does not duplicate those rules.-Three boundaries are especially important to the architecture. First, page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, default-pipeline cadence is `P01 → first-page gate → uninterrupted remaining pages → final gate`. P01 is a method sample: execution emits a `gate-signal`, then carries resolved method rules into later pages; no checker call or page batch interrupts P02 through the final page. `quick-generate` retains serial hand-authoring and P01 as its visual anchor, skips the first-page gate, and runs one lockless final gate after the complete roster exists. Third, routing is deterministic: raw PPTX template requests, beautify-profile requests, native enhancement, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary.+Three boundaries are especially important to the architecture. First, page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, default-pipeline cadence is `P01 → first-page gate → uninterrupted remaining pages → final gate`. P01 is a method sample: execution emits a `gate-signal`, then carries resolved method rules into later pages; no checker call or page batch interrupts P02 through the final page. `quick-generate` retains serial hand-authoring and uses P01 as its visual-system calibration baseline, skips the first-page gate, and runs one lockless final gate after the complete roster exists. Third, routing is deterministic: raw PPTX template requests, beautify-profile requests, native enhancement, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary.In the default pipeline, the Role Switching Protocol (mandated read of `references/<role>.md` before mode change) serves two reinforcing purposes: forcing fresh role instructions into context overrides drift from the previous mode, and the visible marker in the conversation transcript creates an audit trail so the user can see when the agent moved between modes — critical when reviewing why a particular decision was made.diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex db4bae3e..959b67db 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -13,7 +13,9 @@ before the page plan is frozen, not only when a deck is already exported.| What the deck needs | Reach for | Decided at ||---|---|---|-| Reveal content in step with the narration | Per-element object animation — `-a auto` for generic entrance reveals, or an `animations.json` sidecar for explicit enter/emphasize/move/exit/static lifecycle choreography | Post-processing; §2, §4, [`customize-animations`](../workflows/stages/customize-animations.md) |+| A generic deck-wide entrance build | `-a auto`; with the default `after-previous` Start mode, groups use fixed `--animation-stagger` timing rather than narration cues | Post-processing; §2, §4 |+| Explicit object lifecycle choreography | An `animations.json` sidecar for selected enter/emphasize/move/exit/static duties, order, Start mode, and timing | Post-processing; §2, §4, [`customize-animations`](../workflows/stages/customize-animations.md) |+| Object reveals semantically synchronized to recorded narration | Narration-cue sync derives `narration_animations.json` from canonical `animations.json`, page-local SRT, and `narration_timing.json`; `-a auto` alone does not provide this mapping | Audio stage; [`generate-audio`](../workflows/stages/generate-audio.md) || A continuous action — slide-in, flip, camera push-in, progressive reveal, camera pan | **Morph: author the action as two static pages, then select Morph and add explicit pairs when identity must be deterministic.** There is no keyframe timeline anywhere in this pipeline; the difference between two ordinary editable slides *is* the animation | **Page authoring (Step 6), then motion post-processing** — §2.1, §3.1 || A static full-bleed page that should stop looking frozen | Consider slow `path_*` motion on a visually subordinate image or atmospheric layer; §4.1 gives one starting recipe | Post-processing; §4.1 || Carousel, counting numerals, parallax depth, click-to-reveal flip card | Four recurring recipes assembled from the mechanisms above | §4.2 — the carousel and odometer both need paired pages |@@ -488,7 +490,7 @@ Flags: `-a/--animation` selects effect/mode; `--animation-trigger` selects Start`--animation-config` selects a sidecar; `--no-animations` disables page/objectmotion but preserves narration audio and recorded advance timing.-> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`. When either animation sidecar exists, narrated export selects `narration_animations.json`; canonical `animations.json` without that derived file remains a synchronization error. Without sidecars, pass `--inherit-motion-from <base_postflight_report>` for the base deck motion. Pass `--animation-config animations.json` for canonical animation, or `--no-animations` to remove page and object motion.+> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`. Narration-cue sync uses `narration_animations.json` and blocks when only canonical `animations.json` exists. Narration-independent custom motion explicitly passes `--animation-config animations.json`, even when a derived sidecar also exists. With no sidecar, pass `--inherit-motion-from <base_postflight_report>`; explicit all-motion-off uses `--no-animations`.### 4.1 Slow ambient motion — the page that breathesdiff --git a/skills/ppt-master/references/video-design.md b/skills/ppt-master/references/video-design.mdindex 809aabf9..8909e297 100644--- a/skills/ppt-master/references/video-design.md+++ b/skills/ppt-master/references/video-design.md@@ -52,22 +52,22 @@ SVG roster exists.## 2. Scene and Page Planning-Judge quality by reduced audience understanding cost, not spectacle. Resolve the-spoken argument, visible evidence, mental map, and motion job together before-choosing effects.+**Default — quality follows purpose (may override)**: explanation prioritizes+understanding; promotion or brand work may prioritize emotion, recall, or+impact. Give every change a communication job.| Narrative relationship | Page treatment ||---|---|| Several lines explain one idea | Keep one page/scene and reveal only the semantic units needed for that explanation |-| One process or system persists | Retain its main roles and relative positions as a stable visual anchor |-| New evidence expands one part of a known map | Keep the map, enlarge or emphasize the active region, and de-emphasize context only as needed |+| One process or system persists | Keep only the roles, relationships, or spatial cues needed for orientation; adapt the rest as needed |+| New evidence expands a known map | Retain orienting cues; adapt the active region and context as needed || The same object changes position, scale, containment, or state | Author compatible adjacent endpoints and use the Morph contract when motion is active || The audience must adopt a genuinely new mental map | Start a new composition and make the transition explicit |-**Default — stable visual anchors (may override when the subject resets)**:-within one explanation, keep recurring roles, relative positions, and governing-structure stable. Prefer moving, enlarging, revealing, or dimming within that-map over replacing the entire layout at every beat.+**Default — stable visual anchors (may override when the mental map resets)**:+within a continuous explanation, preserve recognizable roles,+relationships, or spatial cues. Exact coordinates, scale, and styling may+change if identity and orientation remain legible; reset with a new mental map.**Default — one semantic focus change per beat (may override for one inseparableidea)**: several elements may change together only when they communicate onediff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 0b37424b..10ba0cf3 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -648,8 +648,8 @@ Behavior:- Narration text is read strictly from the matching `notes/*.md` file; the script only skips Markdown heading lines (`# ...`) and does not summarize, rewrite, or filter delivery notes- `--recorded-narration audio` prepares PowerPoint's "recorded timings and narrations": every slide must have matching `m4a` / `mp3` / `wav` audio, `ffprobe` must read every duration, and `--animation-trigger on-click` is rejected- `--recorded-narration audio` keeps speaker notes, embeds each matching audio file, and writes slide auto-advance timings from page-start lead-in + audio duration + page-tail padding. `--narration-start-floor` and `--narration-padding` are independent optional seconds; their defaults are `0.8` and `0.5`, and the post-transition lead-in is `max(0, start floor - transition duration)`- - When either animation sidecar exists, narrated export defaults to `<project>/narration_animations.json`; a canonical `animations.json` without that derived file remains a blocking synchronization error- - Without animation sidecars, Generate narration reads base-report deck motion via `--inherit-motion-from`; direct low-level omission keeps legacy `fade` / no object builds. Use `--animation-config animations.json` for canonical animation, or `--no-animations` to remove object/page motion while retaining narration timings+ - While motion remains enabled, narrated export without an explicit `--animation-config` selects `<project>/narration_animations.json` when either animation sidecar exists; canonical-only cue synchronization therefore blocks until the derived file exists. Narration-independent custom motion explicitly passes `--animation-config animations.json`, even when a derived sidecar also exists+ - Without animation sidecars, Generate narration may inherit base-report deck motion via `--inherit-motion-from`; direct low-level omission keeps legacy `fade` / no object builds. Use `--no-animations` to remove object/page motion while retaining narration timings- Non-narrated export keeps the existing optional `<project>/animations.json` default- Narration timing merges into the existing slide timing DOM. While motion remains enabled, object-animation rows and the resolved page transition are preserved rather than regenerated; inherited `-a none` suppresses object rows, and `--no-animations` removes both motion layers- `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coveragediff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.pyindex 534954b0..aaeb7b8b 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py@@ -875,9 +875,10 @@ Recorded narration:- Keeps speaker notes when enabled- Prepares PowerPoint recorded timings and narrations- Requires one m4a/mp3/wav file per slide- - Uses narration_animations.json when animation sidecars exist- - Inherits source-bound deck motion from the base postflight report- - Use --animation-config animations.json for the canonical animation+ - Unless --no-animations is set, recorded narration without an explicit+ config selects narration_animations.json when either sidecar exists+ - With no sidecar, --inherit-motion-from may restore base-report deck motion+ - Use --animation-config animations.json for narration-independent custom motion- Use --no-animations for narration and timings without animation motion- Embeds per-slide audio matched by SVG filename / slide number- Sets slide auto-advance from audio duration so video export can use@@ -1064,9 +1065,11 @@ Recorded narration:type=str,default=None,help=(- 'Per-slide/per-object animation config. Recorded narration uses '- '<project>/narration_animations.json when an animation sidecar exists, '- 'or may inherit base postflight motion with --inherit-motion-from. '+ 'Per-slide/per-object animation config. While motion remains enabled, '+ 'recorded narration without an explicit config selects '+ '<project>/narration_animations.json when either animation sidecar '+ 'exists, or may inherit base postflight motion with '+ '--inherit-motion-from when neither exists. ''Other exports default to <project>/animations.json when present.'),)diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex cd5186af..36b06b52 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -499,8 +499,9 @@ the lockless Quick exporter and must use the default lock-backed profile.on a lock or generated font asset.**Generation pacing**: the current main agent hand-writes the SVG roster in-order. Use P01 as the visual anchor and continue directly through the remaining-pages without a first-page checker or confirmation stop. When a motif was+order. Use P01 as the visual-system calibration baseline and continue+directly through the remaining pages without a first-page checker or+confirmation stop. When a motif wasresolved, reuse it selectively and vary scale, crop, density, position, orcontent interaction instead of cloning one ornament. Keep this choice only inactive context; create no planning artifact or approval stop. After every page