| 1 | # FAQ |
| 2 | |
| 3 | [English](./faq.md) | [Chinese](./zh/faq.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Q: What source formats does PPT Master accept? |
| 8 | |
| 9 | Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **RST**, **URLs** (including WeChat articles), **Markdown**, or just plain text pasted into the conversation. The AI agent converts your source material to Markdown automatically before generating slides. |
| 10 | |
| 11 | ## Q: What happens to images embedded in a DOCX? |
| 12 | |
| 13 | DOCX conversion extracts embedded image assets into a companion asset directory and records an image manifest; when the source exposes the information, that record includes displayed dimensions, pixel dimensions, and aspect ratios. Project import makes those companion assets available to the active project. Planning uses source position, surrounding text, captions, alt text, filenames, and geometry to decide whether an extracted asset is used; it does not have to inspect or use every extracted image. A selected image may be shown complete or placed with a focal-safe crop. Extraction and registration do **not** mean that the image is regenerated. |
| 14 | |
| 15 | See the [source-conversion output contract](../skills/ppt-master/scripts/docs/conversion.md) for companion assets and the [image-planning contract](../skills/ppt-master/references/strategist-image.md) for selection and geometry evidence. |
| 16 | |
| 17 | ## Q: Can PPT Master batch-redraw every image in a DOCX to one ratio and style? |
| 18 | |
| 19 | No. There is currently no user-facing Generate route that reference-redraws every embedded DOCX image as a batch and automatically replaces the originals. Manifest mode can batch **new** image jobs from prompts, but the built-in CLI's `--reference-image` editing is a narrow single-image path, is not manifest mode, and is available only through supported image backends. The Image to PPTX profile does not fill this gap: it applies when raster inputs represent whole slide pages to reconstruct, not when ordinary photos or illustrations are source assets inside a Word document. |
| 20 | |
| 21 | These boundaries are defined by the [image-generation contract](../skills/ppt-master/references/image-generator.md), [Generate Step 5](../skills/ppt-master/workflows/generate-pptx.md), and the [Image to PPTX profile](../skills/ppt-master/workflows/profiles/image-to-pptx.md). |
| 22 | |
| 23 | ## Q: What is the difference between cropping an image and generating one at a requested aspect ratio? |
| 24 | |
| 25 | They change different things. `crop=adaptive` permits but never requires cropping. Executor may use `meet` to show the complete source or a focal-safe `slice` to fill the chosen container; both reuse source pixels. An AI job's `aspect_ratio` requests a newly generated canvas. A reference edit transforms one supplied image through the separate single-image path; it is not a manifest batch operation. See the [image resource-list rules](../skills/ppt-master/references/strategist-image.md), [Executor crop policy](../skills/ppt-master/references/executor-image.md), [SVG image placement contract](../skills/ppt-master/references/svg-image-embedding.md), and [image manifest schema](../skills/ppt-master/references/image-generator.md). |
| 26 | |
| 27 | ## Q: Can I generate a deck with just a topic, no source materials? |
| 28 | |
| 29 | Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Project import does not bulk-fetch the adopted webpage URLs recorded in provenance. After normal image search fails, one relevant page may be fetched with its companion images for review, and only selected files enter the deck's image pool. |
| 30 | |
| 31 | Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone. |
| 32 | |
| 33 | ## Q: Can PPT Master produce formats other than PowerPoint? |
| 34 | |
| 35 | Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master supports social media and marketing formats out of the box: |
| 36 | |
| 37 | | Format | Use Case | |
| 38 | |--------|----------| |
| 39 | | Xiaohongshu (RED) 3:4 | Image-text sharing, knowledge posts | |
| 40 | | WeChat Moments / IG 1:1 | Square posters, brand showcases | |
| 41 | | Story / TikTok 9:16 | Vertical stories, short video covers | |
| 42 | | WeChat Article Header | WeChat article cover images | |
| 43 | | A4 Print | Print posters, flyers | |
| 44 | |
| 45 | Just specify the format when starting a project (e.g., `--format xhs`). The output is still a `.pptx` file containing native shapes. |
| 46 | |
| 47 | ## Q: What AI tools work with PPT Master? |
| 48 | |
| 49 | PPT Master works inside any agent-capable AI tool that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. Installation and authentication are handled by the selected host; the [Getting Started guide](./getting-started.md) defines the working-folder model used after installation. |
| 50 | |
| 51 | ## Q: I downloaded an old version. How do I update to the latest? |
| 52 | |
| 53 | It depends on how you installed PPT Master: |
| 54 | |
| 55 | | Install method | Update method | |
| 56 | |---|---| |
| 57 | | Git clone | Run `python3 skills/ppt-master/scripts/update_repo.py` inside the `ppt-master` folder | |
| 58 | | Download ZIP | Download the latest ZIP, unzip it into a new folder, copy your old `.env` and `projects/` folder into the new folder, then run `pip install -r requirements.txt` | |
| 59 | | Skill marketplace | Reinstall or update through the matching marketplace / skills tool | |
| 60 | |
| 61 | For long-term use, Git clone is recommended. ZIP is fine for a quick trial, but it has no Git history and cannot run `git pull`. |
| 62 | |
| 63 | If you are not sure which install method you used, ask the AI to run this from the project folder: |
| 64 | |
| 65 | ```bash |
| 66 | python3 skills/ppt-master/scripts/update_repo.py |
| 67 | ``` |
| 68 | |
| 69 | If the folder is not a Git clone, the script will tell you how to migrate a ZIP install. |
| 70 | |
| 71 | ## Q: The repo is over 1 GB and my skills tool fails to download it — can I get just the skill? |
| 72 | |
| 73 | Yes. The full repository is large (Git history plus bundled example decks and their assets), and that size is baked into the history — it can't be trimmed without breaking the many existing forks. If you only want the skill and not the full repo, use a lightweight path instead: |
| 74 | |
| 75 | - **Marketplace CLI**: `npx skills add hugohe3/ppt-master` or Claude Code's `/plugin install` fetch the skill files only (see the Set Up section of the README). |
| 76 | - **Manual download**: grab `ppt-master-skill-*.zip` from the [Releases](https://github.com/hugohe3/ppt-master/releases) page — the skill files only (~56 MB), no full-repo clone. |
| 77 | |
| 78 | For either skill-only path, locate the installed skill directory that contains `SKILL.md` and `requirements.txt`, then run `python3 -m pip install -r "<installed-skill-dir>/requirements.txt"` so the post-processing scripts work. |
| 79 | |
| 80 | Neither path carries a `.git` directory, so `git describe` cannot report the version. The installed release is recorded in the `metadata.version` field of the skill's own `SKILL.md` frontmatter. |
| 81 | |
| 82 | For users in mainland China who cannot reach GitHub reliably, the complete repository is also mirrored on [AtomGit](https://atomgit.com/hugohe3/ppt-master); clone it or download its ZIP there. |
| 83 | |
| 84 | ## Q: I installed from a skill marketplace. What prerequisites and working directory do I need? |
| 85 | |
| 86 | All installation paths require Python 3.10+ and an installed, authenticated agent host that can read and write files and run shell commands. The `npx skills add hugohe3/ppt-master` path additionally requires a working `npx` command, normally supplied with Node.js/npm; the repository does not declare a Node/npm minimum version. A host's own `/plugin install` command does not use that `npx` path. |
| 87 | |
| 88 | The installed skill directory and your working folder are different roles. Install Python dependencies from the directory that contains the installed skill's `SKILL.md` and `requirements.txt`, but start the agent in a separate persistent, writable working folder of your choice. The agent creates that folder's `projects/` directory as needed; you do not need to run it from the host-managed skill cache. See [Getting Started: Set up the installation and working folders](./getting-started.md#set-up-the-installation-and-working-folders) and the skill's [execution entry point](../skills/ppt-master/SKILL.md). |
| 89 | |
| 90 | ## Q: How can I run the same minimal installation check on macOS or Linux? |
| 91 | |
| 92 | After installing the Python dependencies, run the same core import check used by the Windows guide: |
| 93 | |
| 94 | ```bash |
| 95 | python3 -c "import pptx; import fitz; print('All core dependencies OK')" |
| 96 | ``` |
| 97 | |
| 98 | Then ask the agent for a three-slide "Hello World" deck in Quick mode, with no source file. The import command checks the core Python packages; the Quick run checks project initialization, SVG authoring, validation, and export together. Success means a PPTX appears in the active project's `exports/` directory and the file opens in a presentation application. See the [Windows installation smoke test](./windows-installation.md) and the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 99 | |
| 100 | ## Q: Do I need to create `projects/<name>` manually, and which `exports/` contains my deck? |
| 101 | |
| 102 | No. In an agent-driven run, Default Generate Step 2 or Quick initialization creates the active project, normally under `<working-folder>/projects/<generated-project-name>/`, and reports its exact path. With the default exporter path, the deck belongs to that project: |
| 103 | |
| 104 | ```text |
| 105 | <active-project>/exports/<project-name>_<timestamp>.pptx |
| 106 | ``` |
| 107 | |
| 108 | That is not an unqualified `exports/` at the repository root. An explicitly supplied output path is the exception. See [Generate project initialization and export](../skills/ppt-master/workflows/generate-pptx.md), the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md), and the [working-folder explanation](./getting-started.md#set-up-the-installation-and-working-folders). |
| 109 | |
| 110 | ## Q: Can I use AI-generated images in my presentation? |
| 111 | |
| 112 | Yes. When the agent host exposes a native image tool, PPT Master can use it without a separate provider image-generation API key. It can also use the built-in `image_gen.py` through a configured provider. Choose "AI generation" for the image approach; you can explicitly ask the agent to use its own image tool. You can also place your own images in the project's `images/` folder. |
| 113 | |
| 114 | ## Q: Why are there no icons? Are icons supposed to appear on every slide? |
| 115 | |
| 116 | No per-slide icon coverage is required. In Default, `No base icons` is a valid confirmed choice alongside emoji, bundled SVG icons, and custom project icons. Default's `icons.inventory` indexes its curated prepared pool without assigning icons to pages. Both profiles may use project-local prepared icons; Quick creates neither a general resource roster nor an icon-to-page assignment. The author uses an icon only when it serves that page's communication task, so a deck or page may use none. AI-generated illustrated-icon slices are image assets under a separate path and are also optional. |
| 117 | |
| 118 | See the [Strategist icon choice](../skills/ppt-master/references/strategist.md), [Executor icon usage](../skills/ppt-master/references/executor-base.md), and [Quick resource preparation](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 119 | |
| 120 | ## Q: I don't have an image-generation API key — can I still get images? |
| 121 | |
| 122 | Yes. If the agent host exposes native image generation, choose "AI generation" and ask it to use its own image tool; this needs no provider image API key. Otherwise, pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons. Zero-config search is a fallback: it works immediately, but quality can be uneven because many results are ordinary user uploads. |
| 123 | |
| 124 | For better contemporary stock photography, set `PEXELS_API_KEY` and/or `PIXABAY_API_KEY` in `.env` (both are free). The search will include Pexels / Pixabay automatically, which usually improves people, workplace, lifestyle, product, and illustration images. You can mix paths in one deck (e.g. AI for hero illustrations, web for team photos). If a selected image requires attribution, Executor adds a small inline credit on the affected slide. |
| 125 | |
| 126 | Be clear on what this buys you: **web search only finds *a* relevant, downloadable, license-clean image — it does not guarantee the image is good or right for that page**, because ranking sees text metadata, not the picture. During generation a multimodal model reads a thumbnail to sanity-check and re-queries a poor fit, but **the most reliable route to high quality is to search yourself**: find a better image anywhere, hand the AI its URL, and it downloads and swaps it in via `image_search.py --from-url <url>` (recorded as a manual source; rights are yours to verify). Replacement can happen any time — mid-generation or from live preview — without stopping the run. In short: treat web search as a placeholder fallback and manual picking as the polish step. |
| 127 | |
| 128 | ## Q: Can I turn AI-generated slide mockups or screenshots into editable PowerPoint slides? |
| 129 | |
| 130 | Yes. Provide one or more images and ask to reconstruct the represented pages as an editable PPTX; PPT Master routes that request to the **Image to PPTX** ([`image-to-pptx`](../skills/ppt-master/workflows/profiles/image-to-pptx.md)) profile. It currently requires Codex. Other agent hosts have not been adapted for this profile, so their behavior is not supported or promised. Image to PPTX always activates Quick; you do not need to ask for Quick separately. It first normalizes every input into one ordered page-frame roster, so slide count follows represented pages rather than file count. |
| 131 | |
| 132 | Ordinary visible text is rebuilt as native editable text. Logos, icons, badges, and decorative graphics use the source directly when it is adequate; when it is too low-resolution, Codex may reconstruct them from the reference, but identity, silhouette, proportions, colors, and wordmarks must remain fixed, and a merely similar substitute is forbidden. Charts, tables, and data graphics are never reconstructed generatively: they must be native objects with verifiable values, exact source assets, or marked `manual_required`. Photo and illustration scenes are rebuilt into at least a clean base plus subject or foreground layers. Multiple non-overlapping objects with padded bounding boxes may share one generated plate and then become independent PowerPoint picture objects through grid slicing or SVG bounding-box crops. AI may reconstruct pixels hidden by the separated layers, but it must not redesign the visible composition. A whole-slide screenshot skin with token editable overlays does not count as reconstruction. |
| 133 | |
| 134 | ## Q: Can I edit the generated presentations? |
| 135 | |
| 136 | Yes. The only PPTX converter in the SVG pipeline is PPT Master's own `svg_output/` → DrawingML conversion. It saves a timestamped native PowerPoint deck to the active project's `exports/`, with text, graphics, and colors directly editable as PowerPoint objects. With the default output path, both Default Generate and Quick Generate copy the authored `svg_output/` to `backup/<timestamp>/svg_output/`, so the same authored deck can be re-exported without re-running the LLM. For Quick this is package reconstruction, not a recoverable record of the AI's design decisions. |
| 137 | |
| 138 | `finalize_svg.py` remains a mandatory Step 7 operation in the default Generate flow even though native PPTX export reads `svg_output/`. It produces self-contained files in `svg_final/` for visual inspection and for manual insertion into another deck as SVG pictures. The explicit quick-generate profile skips this preview artifact, but still retains the normal postflight report and default-path backup after its lockless final quality check. PowerPoint's manual **Convert to Shape** command is not a supported round-trip path; use the generated native PPTX when you need editable shapes. |
| 139 | |
| 140 | ## Q: How does multiline text export? Can PowerPoint reflow it? |
| 141 | |
| 142 | By default, a mergeable multiline block exports as one editable PowerPoint text frame. Authored line breaks are retained and PowerPoint automatic wrapping is disabled, so resizing the frame does not rewrite the authored line layout. An ordinary generated frame uses PowerPoint's native **Resize shape to fit text** behavior: deleting a retained break expands the frame instead of leaving text outside it. Imported exact frames and structured multiline placeholder carriers retain their fixed-size behavior. |
| 143 | |
| 144 | To let PowerPoint reflow eligible body text, use `--reflow-text`: |
| 145 | |
| 146 | ```bash |
| 147 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --reflow-text |
| 148 | ``` |
| 149 | |
| 150 | This restores automatic paragraph reflow and may change the line count. The legacy `--merge-paragraphs` flag is a compatibility alias for `--reflow-text`. |
| 151 | |
| 152 | Use `--no-merge` only when every visual line must be an independent PowerPoint text frame: |
| 153 | |
| 154 | ```bash |
| 155 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge |
| 156 | ``` |
| 157 | |
| 158 | That mode preserves independent per-line object placement, but a 12-line paragraph becomes 12 textboxes. When chatting with the AI, ask for "automatic text reflow" or "one independent text box per visual line" to select the corresponding export mode. |
| 159 | |
| 160 | ## Q: Why are font sizes in px, not pt? Do they change on export? |
| 161 | |
| 162 | PPT Master works in **unitless px end-to-end** — the confirm page, `spec_lock.md`, and the SVG all carry px; there is no pt layer. The SVG canvas is literally 1280×720 px, so px is the real layout / execution unit, and keeping a single unit avoids the size drift you get when a value is "confirmed as 20pt" but written into the SVG as a different number. |
| 163 | |
| 164 | PowerPoint displays pt, so the **export** converts px → pt automatically (`pt = px × 0.75`, kept to one decimal). For example a `24px` body becomes `18pt`, a `42px` title becomes `31.5pt`. So a non-integer like `13.5pt` or `31.5pt` in PowerPoint is **expected and intentional**, not a bug — the size is whatever the px works out to, no longer forced onto whole or half-point values. |
| 165 | |
| 166 | The body baseline is a fixed value per **reading mode** (not a range). This controls reading distance and density; it is separate from the open-ended communication intent: |
| 167 | |
| 168 | | Reading mode | Body px | ≈ exported pt | |
| 169 | |---|---|---| |
| 170 | | `text` (read-close: report / leave-behind) | 20px | 15pt | |
| 171 | | `balanced` (default: roadshow / review) | 24px | 18pt | |
| 172 | | `presentation` (projected / launch) | 32px | 24pt | |
| 173 | |
| 174 | Title, subtitle, footnote and the other roles derive from the body by ratio and snap to clean even px. You can override any role's px value on the confirm page. |
| 175 | |
| 176 | ## Q: How does PPT Master decide a deck's style? |
| 177 | |
| 178 | Two independent choices, locked at confirmation `d`: |
| 179 | |
| 180 | - **Mode** (how the deck argues): `pyramid` / `narrative` / `instructional` / `showcase` / `briefing` — see `references/modes/` |
| 181 | - **Visual style** (how it looks): `swiss-minimal` / `editorial` / `soft-rounded` / `dark-tech` … + `custom` — see `references/visual-styles/` |
| 182 | |
| 183 | Any mode pairs with any visual style. |
| 184 | |
| 185 | ## Q: The result looks like only boxes and lines. What run facts should I check first? |
| 186 | |
| 187 | PPT Master has no documented `wireframe` runtime mode and no documented visual-equivalence guarantee between releases, so appearance alone does not identify a version regression. First record whether the run used Default or Quick, plus the actual mode, visual style, image-usage choice, base-icon choice, Custom Animations setting, and prepared-resource state. Quick keeps these decisions in the active agent context rather than writing `design_spec.md` or `spec_lock.md`. |
| 188 | |
| 189 | Next compare the same page in the active project's `svg_output/` with the exported PPTX. If the SVG is already sparse, inspect the planning, resource, and SVG-authoring layers. If the SVG contains the intended objects but the PPTX loses or changes them, inspect the conversion or rendering layer. This boundary follows [Materials → Plan → Realization](./technical-design.md), the [Default Generate workflow](../skills/ppt-master/workflows/generate-pptx.md), and the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 190 | |
| 191 | ## Q: How is PPT Master priced, and does template reuse reduce token usage? |
| 192 | |
| 193 | You pay according to your AI usage; PPT Master adds no subscription fee. |
| 194 | |
| 195 | The repository documents template reuse as reuse of identity, method, structure, or a recurring application contract. It contains no measured or guaranteed relationship between template reuse and token usage. See the [product positioning](../README.md#product-positioning) and [template boundaries](./templates-guide.md). |
| 196 | |
| 197 | ## Q: Are the charts in the generated PPTX editable? |
| 198 | |
| 199 | By default, charts are rendered as **custom-designed SVG graphics** converted to native PowerPoint shapes — fully editable as shapes (move, recolor, retype, restyle). This is a deliberate default over Excel-driven chart objects: PowerPoint's default charts look generic and dated, and lock decks into rigid templates. SVG charts give you publication-quality visuals you can fine-tune directly in PowerPoint, and they render pixel-consistently across PowerPoint / Keynote / LibreOffice / WPS. |
| 200 | |
| 201 | If your workflow specifically requires Excel-driven data editing or PowerPoint's chart/table-specific controls, export with `--native-charts-and-tables`: supported data charts and pure text-grid tables then ship as **PowerPoint-native Chart / Table objects backed by data** (saved as `<active-project>/exports/<name>_<timestamp>_native_charts_tables.pptx`, keeping the deck's own colors instead of PowerPoint's default theme). The default SVG fallback also becomes editable DrawingML shapes, but it has no chart data workbook or table/chart object model. Native objects may look slightly different across PowerPoint / Keynote / LibreOffice / WPS, so the shape-based route remains the visual-stability default. |
| 202 | |
| 203 | ## Q: Are formulas editable? |
| 204 | |
| 205 | Yes, in PowerPoint. PPT Master exports both standalone block equations and |
| 206 | same-paragraph inline formulas as editable OMML, not screenshots or picture |
| 207 | assets. A block uses a formula group; inline math uses a leaf |
| 208 | `<tspan data-pptx-inline-formula="...">preview</tspan>` among ordinary text |
| 209 | runs. Matrices, multiline derivations, and other high-structure expressions |
| 210 | remain blocks. Raw LaTeX does not render in SVG, so each marker carries an |
| 211 | ordinary visible preview that native export replaces without adding an image |
| 212 | fallback. |
| 213 | |
| 214 | Forward compilation covers every explicitly named input in Microsoft's |
| 215 | documented Microsoft 365 2606 / Mac 16.110 LaTeX profile and 2605 / 16.109 |
| 216 | mhchem profile: symbols, structures, environments, macros, chemistry, local |
| 217 | formula colors, and the documented native normalizations. Unknown and |
| 218 | explicitly unsupported input fails closed instead of appearing as raw LaTeX. |
| 219 | For PPTX import, the same closed OMML validator supports a narrow reverse path: |
| 220 | PPT Master-owned block and inline math becomes canonical formula markers with |
| 221 | visible SVG previews. This recovers normalized semantics, not the author's |
| 222 | original LaTeX spelling and not arbitrary third-party OMML. Unknown OMML is |
| 223 | reported and retained as readable/opaque fallback in tolerant mode. |
| 224 | |
| 225 | The generated OMML retains the PowerPoint 2010+ package target, and the |
| 226 | executable source profile is pinned to the Microsoft documentation versions |
| 227 | above. Repository verification covers compiler behavior, OMML structure, and |
| 228 | PPTX packaging rather than complete Microsoft 365 UI rendering/editability |
| 229 | certification. Formula display and editability in Keynote, WPS, LibreOffice, |
| 230 | and other non-PowerPoint clients are not supported; PPT Master does not add an |
| 231 | image fallback for them. |
| 232 | |
| 233 | ## Q: Can generated slides contain clickable links? |
| 234 | |
| 235 | Yes. PPT Master supports PowerPoint-native links on a whole object or an inline |
| 236 | text run. External targets use an absolute URI such as `https:` or `mailto:`; |
| 237 | same-deck jumps use the exact 1-based `#slide-N` form. Both compile from |
| 238 | standard SVG `<a href>` anchors to native click relationships, and supported |
| 239 | PPTX import reconstructs the same SVG form. |
| 240 | |
| 241 | This is a hyperlink contract, not a general PowerPoint action API. Mouse-over, |
| 242 | custom-show, navigation-command, program/macro/OLE/file, and arbitrary action |
| 243 | settings are not authored. See the [PowerPoint ↔ SVG Mapping |
| 244 | Guide](./powerpoint-svg-mapping.md#10-powerpoint-playback-and-package-features) |
| 245 | for the carrier and preservation boundaries. |
| 246 | |
| 247 | ## Q: Why are there no element animations? Were animations removed? |
| 248 | |
| 249 | Animations were not removed. Page transitions are on by default (`fade` 0.4s); per-element object |
| 250 | animation is **off by default**—a page appears as a whole instead of having |
| 251 | elements auto-cascade in one by one. Both are controlled by `svg_to_pptx.py` |
| 252 | flags: `-t/--transition` for page-level and `-a/--animation` for element-level. |
| 253 | The object registry includes entrance, emphasis, motion-path, and exit effects. |
| 254 | `pptx_to_svg.py` also reconstructs exact current-registry page transitions and |
| 255 | finite exact-duration object-animation rows into `animations.json`; |
| 256 | unsupported source timing remains an explicit diagnostic. |
| 257 | |
| 258 | Use `-a auto` for deck-wide automatic entrances, a canonical effect for one deck-wide effect, or a project-level `animations.json` for explicit page/object timing. Default runs the custom stage for an existing sidecar, an explicit per-slide/per-object request, or an enabled effective Custom Animations outcome. Quick runs it when a sidecar or its active-context motion decision requires object-level work; recorded, self-running, or video-directed Quick delivery requires that stage unless the user explicitly requests static or page-transition-only playback. A deck-wide-only request can remain exporter flags. If none of these triggers applies, the `fade`/`none` defaults remain. The [Generate workflow](../skills/ppt-master/workflows/generate-pptx.md) and [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md) define those triggers. |
| 259 | |
| 260 | ```bash |
| 261 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition |
| 262 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions |
| 263 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto # enable per-element entrance (effect mapped from group id) |
| 264 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade # enable with one canonical effect |
| 265 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin # native emphasis |
| 266 | python3 skills/ppt-master/scripts/pptx_animations.py --list # complete categorized effect list |
| 267 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click # presenter-paced reveals |
| 268 | ``` |
| 269 | |
| 270 | `on-click` is for live presentations. Narrated/video export via `--recorded-narration` rejects it because PPT Master writes page timings, not object-level click timings; use `after-previous` or `with-previous` for narrated decks. |
| 271 | |
| 272 | For common commands, Start-mode guidance, and object-level customization, see [Animations & Transitions](./animations.md). Exact effect and validation behavior remains in the linked execution reference. |
| 273 | |
| 274 | ## Q: Which AI model works best? |
| 275 | |
| 276 | **Claude** (Opus / Sonnet) is the recommended and most tested model. SVG layout requires precise absolute-coordinate calculations (font size x character count x container width), and Claude handles this significantly better than alternatives. |
| 277 | |
| 278 | **GPT series** older versions tended to produce more layout issues — text overflowing containers, misaligned elements, coordinate miscalculations. Newer versions (e.g. GPT-5.5) have improved noticeably and are usable in practice; if issues appear, tell the AI which page to fix. |
| 279 | |
| 280 | Other models (Gemini, GLM, MiniMax, etc.) vary in quality. In general, models with stronger frontend/visual capabilities produce better results. |
| 281 | |
| 282 | ## Q: Someone said PPT Master is "just a toy" — is that fair? |
| 283 | |
| 284 | No. PPT Master is a presentation workflow, not a model or a complete agent. It supplies presentation-specific reasoning, contracts, project state, deterministic conversion, and quality gates; the selected model still sets the quality ceiling. Evaluating the workflow with a weak or small-context model is like test-driving a sports car in first gear and concluding it is slow. |
| 285 | |
| 286 | **The full-power combination:** |
| 287 | |
| 288 | - **Claude with a large context window** (ideally ~1M tokens): a large context window lets the Executor see every previously generated page in the same session, maintaining visual consistency across the entire deck without splitting runs. Smaller windows force split-mode execution, which introduces visible style drift between phases. |
| 289 | - **AI image generation with `gpt-image-2`** (or similar): placeholder-grade stock images are the single biggest reason decks look generic. Replacing them with on-brand AI-generated illustrations changes the perceived quality immediately. |
| 290 | |
| 291 | If the results you've seen look mediocre, check your setup before concluding anything about the tool: What model? What context size? Was image generation enabled? PPT Master + Claude Opus at 1M context + `gpt-image-2` images is a genuinely different experience from PPT Master + a small open-source model with no image API configured. |
| 292 | |
| 293 | > **No Claude access?** Project sponsor [PackyCode](https://www.packyapi.ai/register?aff=ppt-master) provides pay-as-you-go access to Claude and other models — no subscription, no overseas card required. Use promo code **`ppt-master`** for 10% off. |
| 294 | |
| 295 | One last thing: this is a free, solo-maintained open-source project. If it fits your needs, use it — I'm glad it helps; if it doesn't, pick another tool. Sincere feedback and suggestions are always welcome, because that's how the project gets a little better over time. |
| 296 | |
| 297 | ## Q: Text overflows or elements are misaligned — what can I do? |
| 298 | |
| 299 | The cause depends on where the mismatch appears. If the source SVG already overflows or is misaligned, it is usually an authoring/layout problem: the model must calculate coordinates, font metrics, and container sizes correctly. If the SVG preview is correct but the exported PPTX differs, that may be a converter or renderer bug and should be reported with both artifacts. |
| 300 | |
| 301 | **Fixes to try**: |
| 302 | 1. Compare the page in `svg_output/` with the exported PPTX to isolate authoring from conversion |
| 303 | 2. Tell the AI which specific page has the problem and describe the issue — it can regenerate individual pages |
| 304 | 3. If the SVG itself is repeatedly wrong, use a stronger model or ask the AI to fix its coordinates directly |
| 305 | 4. Remember: the generated PPTX is a **high-quality editable draft**, not a sealed final deliverable — minor finishing adjustments in PowerPoint are expected |
| 306 | |
| 307 | ## Q: How long does a presentation take to generate? |
| 308 | |
| 309 | A typical 10–15 page presentation takes about **10–20 minutes** with a fast model. Generation is **intentionally serial** (one page at a time) to maintain visual consistency across slides — parallel generation was tested and produced inconsistent styles. |
| 310 | |
| 311 | If generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts. |
| 312 | |
| 313 | If what you want is less process rather than a different model, explicitly ask |
| 314 | for quick generation: it omits the Strategist analysis and the confirmation |
| 315 | stop, while per-page SVG authoring remains. The repository does not promise a |
| 316 | fixed time reduction for Quick. See the next question, "I don't want to confirm |
| 317 | a design spec first — can I generate directly?". |
| 318 | |
| 319 | ## Q: I don't want to confirm a design spec first — can I generate directly? |
| 320 | |
| 321 | Yes. Explicitly request **quick generation**, and the Generate route uses the |
| 322 | [`quick-generate` profile](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 323 | |
| 324 | **What it skips is the Strategist analysis, the `design_spec.md` / |
| 325 | `spec_lock.md` artifacts, and the staged confirmation stop: whatever you state |
| 326 | explicitly is followed, and whatever you leave unspecified the current agent |
| 327 | decides directly and continues, without coming back for approval.** State |
| 328 | nothing, and the agent decides everything. It also skips `finalize_svg.py`, so |
| 329 | Quick creates no `svg_final/` preview. |
| 330 | |
| 331 | It does not skip preparation or design capability. Source conversion, research |
| 332 | on identified factual gaps, shared aesthetic references, and every resource the |
| 333 | deck needs still run when required: supplied or extracted images, |
| 334 | AI/web/sliced images, project icons, native shapes, charts/tables, and the |
| 335 | required operational manifests or provenance records. Formulas are authored |
| 336 | directly as PowerPoint-native markers in the affected SVG, not prepared as |
| 337 | image assets. An explicitly selected manual path or another irreplaceable file |
| 338 | dependency still blocks until you provide the required file. If automated AI |
| 339 | generation or its required slicing is exhausted, Quick instead removes the |
| 340 | failed jobs and stale manifest entries, replans their communication role with |
| 341 | native editable text/SVG or already-prepared non-AI assets, continues the same |
| 342 | run, and discloses the replacement in the final handoff. It never fills the gap |
| 343 | with unrelated material. After preparation, the current agent hand-authors |
| 344 | `svg_output/` to the shared standards, runs the lockless Quick final quality |
| 345 | checker, fixes every blocking error, and only then exports the final PPTX. |
| 346 | |
| 347 | Ordinary exporter capabilities remain available as needed, including native |
| 348 | chart/table replacement, notes, motion, narration, and diagnostics. Notes, |
| 349 | custom object animation, and narration start off; the agent may enable them when |
| 350 | the request or deck needs them, without opening a confirmation flow. A |
| 351 | default-path export writes the normal postflight report and snapshots |
| 352 | `svg_output/` under `backup/`; an explicit output path keeps the ordinary |
| 353 | no-backup behavior. Page count alone neither activates nor blocks quick |
| 354 | generation. |
| 355 | |
| 356 | Quick omits the separate planning phase, but the repository does not document |
| 357 | a measured or guaranteed token reduction; per-page SVG authoring remains. |
| 358 | Quick keeps the same page-level visual and |
| 359 | resource-authoring capabilities and the shared SVG/resource blocking |
| 360 | standards. It does not run Spec Lock alignment checks; its package keeps |
| 361 | converter-default Theme scaffolding instead of deriving Theme colors, fonts, |
| 362 | and Master title/body size defaults from a lock. It does not promise the same |
| 363 | design decisions or wall-clock time as Default because it has no confirmed |
| 364 | design contract, first-page calibration, or resumable decision history. |
| 365 | |
| 366 | ## Q: Will long decks blow out the context window in one shot? |
| 367 | |
| 368 | Default recommendation: **continuous one-shot generation**. 10–15 page decks fit comfortably in a 200K window, and cross-page visual consistency is best when the Executor can see prior pages in the same session (it actively aligns style, font sizes, and rhythm). |
| 369 | |
| 370 | When the current AI editor supports an isolated research worker, `topic-research` keeps raw fetches there and the main chat reads only the saved research supplement and fact-provenance file. |
| 371 | |
| 372 | Only when signals are heavy (≥ 18 pages, thick source material, or substantial research material remains in the main chat after a local fallback or unusually large imported supplement) does the AI surface an optional **split mode** hint at the Strategist phase: the planning session (Strategist confirmation stage + image acquisition) ends in the current chat; you open a fresh chat window and type `resume execution projects/<project_name>` to enter the execution session (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there. |
| 373 | |
| 374 | Split mode is a **compromise** — the fresh session pays the fixed cost of reloading the Generate authority and required execution references, but drops the planning-session noise and reuses the freed budget to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode. |
| 375 | |
| 376 | ## Q: Can I preview or fix individual pages before the full export? |
| 377 | |
| 378 | Yes. You can **interrupt the workflow at any time** — after the first few pages are generated, review them and give feedback. The AI can regenerate specific pages based on your comments. You don't need to wait until the end to make corrections. |
| 379 | |
| 380 | For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — the title overlaps the chart" and it will fix that specific SVG. |
| 381 | |
| 382 | ## Q: I have an existing PPT and want to build on it — which route should I use? |
| 383 | |
| 384 | Think of "using an existing PPT" as two questions: **keep its content or not**, and **keep its design (layout + visuals) or not**. The four combinations map to three generation paths plus the option to keep the original unchanged: |
| 385 | |
| 386 | | Intent | Route | What stays fixed | |
| 387 | |---|---|---| |
| 388 | | Keep content + redo layout | **Generate PPTX + beautify profile** | Page count, page order, per-slide wording, chart/table data | |
| 389 | | Replace content + keep design | **Fill Native PPTX** | Native source slide design; selected pages may be reused/reordered | |
| 390 | | Keep only content, redo design and pagination | **Generate PPTX** | Source facts; story structure and page count may change | |
| 391 | | Keep content + keep design | No generation needed | Use the original file | |
| 392 | |
| 393 | Use the **beautify profile** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, and layout / hierarchy / whitespace are redone. The source palette and fonts are the recommended, preselected defaults; an explicit request or final confirmation can override visual fields, but Beautify never departs from the source identity silently. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify profile](../skills/ppt-master/workflows/profiles/beautify-pptx.md). |
| 394 | |
| 395 | Use the **main pipeline** when the source PPT is just material: extract it to Markdown with `ppt_to_md`, read PPTX intake facts from `analysis/`, then let Strategist re-architect the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content" or "turn this into a 10-page executive briefing". |
| 396 | |
| 397 | The one-line test between beautify and the main pipeline: **is the source's page split information to preserve, or just the previous author's structure to improve?** Preserve → beautify; improve → main pipeline. The concrete discriminator is **page count / order**: if it changes at all — split, merge, drop, reorder, or even keeping every word but splitting one crowded page so it reads better — that is re-pagination, which is the main pipeline. Beautify is strictly 1:1. |
| 398 | |
| 399 | If your request is ambiguous, for example "make this PPT more professional" or "optimize this deck", the AI should ask one clarification before routing: **keep the original page count/order and each slide's wording, or treat the PPT as source material and restructure it into a new story?** |
| 400 | |
| 401 | There is also one orthogonal route: if you don't want to produce a deck right now but want to **harvest the design into a reusable template** for future use, use **create-template** (see "How do I create a custom template?" below). |
| 402 | |
| 403 | --- |
| 404 | |
| 405 | ## Q: I already have a finished `.pptx` — can I reuse its design and just fill in new content? |
| 406 | |
| 407 | Yes — this is the **template fill** route, separate from the SVG generation pipeline. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It treats your deck as a native slide library, lets you pick only the pages that fit the new story (reorder freely, and reuse one page for several output slides), and writes the new text — plus native table cells and chart data — straight into the original OOXML. |
| 408 | |
| 409 | The output stays 100% native-editable PowerPoint: the original design, layouts, images, and animations are preserved, and only the planned pages are exported. It deliberately does **not** author a new layout topology or swap source images. The ordered `slides` roster in `fill_plan.json` may omit, reorder, or repeat source slide shells, so the output page count can differ from the source. A deck's page structure encodes its logic (lead-then-detail, comparison, progression), so pick pages whose structure already fits your content rather than forcing it in. When the source library lacks a required new structure, use ordinary Generate, or run Create Template first and then Generate from the resulting workspace. Full steps: [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md). |
| 410 | |
| 411 | --- |
| 412 | |
| 413 | ## Q: Content landed in unexpected places — how do I see what PPT Master detected in my `.pptx`? |
| 414 | |
| 415 | Both PPTX-consuming routes write a read-only analysis report before anything is generated. Read that report to see exactly which shapes were recognized. |
| 416 | |
| 417 | For **Fill Native PPTX**: |
| 418 | |
| 419 | ```bash |
| 420 | python3 skills/ppt-master/scripts/pptx_intake.py <deck.pptx> -o <analysis_dir> |
| 421 | ``` |
| 422 | |
| 423 | `<stem>.slide_library.json` lists every fillable slot per slide with geometry, paragraph counts, and text metrics, plus separate `tables` and `charts` sections. A styled plain text box counts as a slot — a shape does not have to be a real placeholder to be filled. |
| 424 | |
| 425 | For **Create Template**: |
| 426 | |
| 427 | ```bash |
| 428 | python3 skills/ppt-master/scripts/pptx_template_import.py <deck.pptx> --manifest-only -o <workspace> |
| 429 | ``` |
| 430 | |
| 431 | `manifest.json` reports, per slide, the layout and master paths, placeholders (`type`, `idx`, `semanticRole`, `shapeName`), image assets, text counts, and page type; `native_structure.json` adds the source structure assessment. `--manifest-only` skips SVG export, so it is cheap to run just to look. |
| 432 | |
| 433 | Note that Create Template produces a reusable template workspace, not a filled deck: the pages that follow are newly authored by Generate, so the source's body copy and speaker notes are deliberately not carried onto them. If a shape you expected to be usable is missing from these reports, that is the concrete thing to include in an issue. |
| 434 | |
| 435 | --- |
| 436 | |
| 437 | ## Q: Can I turn a company `.pptx` into a reusable workspace? Which kind should I choose? |
| 438 | |
| 439 | Yes, through an explicit `/create-template` request. A complete source deck does not by itself imply `Deck`; choose the kind by what must remain reusable: |
| 440 | |
| 441 | | Kind | Reusable contract | |
| 442 | |---|---| |
| 443 | | **Brand** | Identity only: colors, type, logo, voice, and icon language; no page roster | |
| 444 | | **Style** | Communication method and visual defaults without identity truth, page prototypes, or native structure | |
| 445 | | **Layout** | Brand-neutral and application-neutral Master/Layout/slot structure | |
| 446 | | **Deck** | A recurring application or branded structure that integrates identity, structure, and an SVG roster | |
| 447 | |
| 448 | Create Template confirms the brief before writing either an indexed `library` workspace or a non-registered initialized `project` workspace. For later Generate runs, pass the resulting workspace root—not the source `.pptx` or its inner `templates/` directory. See the [Create Template route](../skills/ppt-master/workflows/create-template.md) and [Templates Guide](./templates-guide.md). |
| 449 | |
| 450 | --- |
| 451 | |
| 452 | ## Q: Does registering a template make every future deck use it automatically? |
| 453 | |
| 454 | No. Registration makes a workspace discoverable; it does not select it. In Default Generate, the template must still be confirmed in Stage 1. Supplying exactly one workspace root can preselect it there, but does not bypass confirmation; supplying several roots leaves them as unselected candidates. Quick has no template selector, so an exact root is validated and used directly, while no exact root means free design. A raw `.pptx`, an inner `templates/` directory, a bare template name, or a style phrase is not a workspace selection. See [How template selection works](./templates-guide.md) and the [Quick template boundary](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 455 | |
| 456 | --- |
| 457 | |
| 458 | ## Q: How do I create a custom template? |
| 459 | |
| 460 | Want to turn a PPT you love into a reusable template for PPT Master? Here's how: |
| 461 | |
| 462 | **Step 1 — Prepare Reference Material** |
| 463 | |
| 464 | The recommended input is the original `.pptx`. PPT Master extracts theme identity, declared Master/Layout topology, placeholder metadata, native-shape evidence, and reusable assets that are actually present and supported. `standard` and `fidelity` use the source as visual reference and author a new SVG roster plus a new Master/Layout/slot system; they neither preserve nor distill source topology. `mirror` instead materializes those validated source facts into a new workspace without semantic synthesis or gap filling. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`. |
| 465 | |
| 466 | Large imported SVGs may contain native-shape metadata, hidden carriers, and preview fingerprints. That lossless representation stays immutable in the temporary analysis workspace as payload backing. Template creation uses a lightweight editable IR with document-local source refs and a compact path/hash manifest. `standard` / `fidelity` author project-canonical SVG and use compact authored-preset groups only for exact registered preset matches. Mirror materializes final templates from the IR, reuses converter-supported payload only for unchanged Slide-local/slot refs, and keeps an SVG fallback for unsupported or edited objects. |
| 467 | |
| 468 | If no source PPTX exists, screenshots of the key page types still work — cover, TOC, chapter, content, and closing — but geometry, fonts, and inheritance must then be inferred visually. This path extracts a reusable template system; when the desired output is one layered editable slide per represented page frame, use Image to PPTX (`image-to-pptx`) instead. |
| 469 | |
| 470 | **Step 2 — Let AI Create the Template** |
| 471 | |
| 472 | Use an agent-capable AI tool (Claude Code, Codex, etc.) and ask it to use the **PPT Master `/create-template` workflow** to convert your reference material into a template. The more context you give, the better the result — for example: |
| 473 | |
| 474 | - Template name and intended use case (e.g., government reports, premium consulting) |
| 475 | - Desired tone and color palette (e.g., "modern and restrained, dark blue primary") |
| 476 | - Category preference (`brand` / `general` / `scenario` / `government` / `special`) |
| 477 | - Canvas format, if not the default 16:9 |
| 478 | - Output scope: indexed `library` (default) or one already initialized `project`; both share one spec schema and asset routing, while library uses a bare spec and project uses qualified specs |
| 479 | |
| 480 | You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (output scope, template ID, theme mode, etc.). |
| 481 | |
| 482 | **Step 3 — Wait for the Result** |
| 483 | |
| 484 | The AI agent will handle the rest — analyzing your references, writing the kind-specific specification, building structured layout definitions only for Layout/Deck, and validating the workspace. Brand/Style never create a preview PPTX; Layout/Deck generate `exports/<id>_template_preview.pptx` on request and require it for multiple Masters. Both scopes require `templates/`; Brand/Layout/Deck may use package-owned `images/` and `icons/`, while Style contributes only its Design Spec. Library scope writes a bare `templates/design_spec.md` under `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `templates/design_spec.<kind>.<id>.md` under `projects/<name>/` and skips registration, allowing one contribution of every kind to coexist. Layout owns the active SVG roster when Layout and Deck are both present. Empty optional directories are omitted. Give that workspace root to Step 3; a project root contributes all of its specs atomically, and installation never copies `exports/`. A compatible legacy-flat Brand/Layout/Deck workspace remains readable only when it satisfies the current kind contract; Layout/Deck also require current structured SVGs. Style has no legacy-flat form, and semantic-legacy packages must be replaced through `create-template` rather than upgraded in place. |
| 485 | |
| 486 | > **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations. |
| 487 | |
| 488 | --- |
| 489 | |
| 490 | > For more questions, see [SKILL.md](../skills/ppt-master/SKILL.md) and [AGENTS.md](../AGENTS.md) |
| 491 |