# How the PPT Master Post-Processing Pipeline Works: From SVG Slides to PowerPoint

> Discover the PPT Master post-processing pipeline. Learn how it transforms SVG slides into a native PPTX presentation with optimized graphics and split speaker notes.

- Repository: [HugoHe/ppt-master](https://github.com/hugohe3/ppt-master)
- Tags: deep-dive
- Published: 2026-04-24

---

**The PPT Master post-processing pipeline is a three-stage automation that splits consolidated speaker notes into per-slide Markdown files, cleans and optimizes SVG graphics for PowerPoint compatibility, and converts the final assets into a native `.pptx` presentation with matching notes.**

The PPT Master post-processing pipeline bridges the gap between raw SVG generation and production-ready PowerPoint decks. Located in the `hugohe3/ppt-master` repository, this chain of three Python scripts—[`total_md_split.py`](https://github.com/hugohe3/ppt-master/blob/main/total_md_split.py), [`finalize_svg.py`](https://github.com/hugohe3/ppt-master/blob/main/finalize_svg.py), and [`svg_to_pptx.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_to_pptx.py)—ensures every slide maintains a strict 1:1 relationship with its speaker notes while resolving SVG features incompatible with Microsoft PowerPoint's native DrawingML engine.

## Stage 1: Splitting Consolidated Speaker Notes with total_md_split.py

The [`total_md_split.py`](https://github.com/hugohe3/ppt-master/blob/main/total_md_split.py) script parses the project's consolidated speaker notes and creates individual files that map directly to each SVG slide.

First, `find_svg_files()` scans the `<project>/svg_output` directory and returns a sorted list of `Path` objects representing all slide SVGs. The script then builds three lookup tables via `build_match_maps()`—exact name, normalized title, and leading-number mappings—to tolerate minor naming differences between slide titles and SVG filenames.

Next, `parse_total_md()` walks the Markdown file line-by-line, extracting level-1 headings and using `match_title()` to associate each heading with an SVG stem. The `check_svg_note_mapping()` function validates that every SVG has a corresponding note entry, aborting with a clear error if the 1:1 relationship breaks. Finally, `split_notes()` writes each note block to `<project>/notes/<stem>.md`, ensuring the output filenames **exactly match** the SVG filenames (e.g., [`03_Intro.md`](https://github.com/hugohe3/ppt-master/blob/main/03_Intro.md) pairs with `03_Intro.svg`).

Source: [[`skills/ppt-master/scripts/total_md_split.py`](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/total_md_split.py)](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/total_md_split.py)

## Stage 2: SVG Cleaning and Finalization with finalize_svg.py

The [`finalize_svg.py`](https://github.com/hugohe3/ppt-master/blob/main/finalize_svg.py) script serves as the single entry point for all SVG post-processing, working on copies in `svg_final/` to preserve the raw strategist output.

The `finalize_project()` function first verifies that `svg_output/` exists and copies its contents to `svg_final/`. It then executes six ordered transformation steps to ensure PowerPoint compatibility:

1. **Embed icons** ([`svg_finalize/embed_icons.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/embed_icons.py)): Replaces `<use data-icon="…"/>` placeholders with full SVG markup from `templates/icons/`.
2. **Smart crop images** ([`svg_finalize/crop_images.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/crop_images.py)): Detects `<image preserveAspectRatio="slice">` and crops images to visible regions, removing unnecessary whitespace.
3. **Fix image aspect** ([`svg_finalize/fix_image_aspect.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/fix_image_aspect.py)): Adjusts `width`/`height` attributes to prevent stretching during PowerPoint shape conversion.
4. **Embed images** ([`svg_finalize/embed_images.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/embed_images.py)): Reads external raster files, optionally compresses them (`--compress`), and stores data as Base64 data-URIs inside the SVG.
5. **Flatten text** ([`svg_finalize/flatten_tspan.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/flatten_tspan.py)): Converts nested `<tspan>` elements into independent `<text>` elements required by some PPT converters.
6. **Fix rounded rectangles** ([`svg_finalize/svg_rect_to_path.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_finalize/svg_rect_to_path.py)): Transforms `<rect rx="…">` elements into equivalent `<path>` elements because PowerPoint's shape engine cannot render the `rx` attribute directly.

The script displays a concise progress bar (`[1/6] …`) unless `--quiet` is used, and upon completion prints the next recommended command:

```bash
python scripts/svg_to_pptx.py "<project_dir>" -s final

```

Source: [[`skills/ppt-master/scripts/finalize_svg.py`](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/finalize_svg.py)](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/finalize_svg.py)

## Stage 3: Converting Finalized SVGs to PowerPoint with svg_to_pptx.py

The [`svg_to_pptx.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_to_pptx.py) script is a thin wrapper that forwards execution to the external `svg_to_pptx` package installed as a PPT Master dependency.

```python
from svg_to_pptx import main
if __name__ == '__main__':
    main()

```

This wrapper adds the scripts directory to `sys.path` and passes all arguments to the underlying package. The converter walks `svg_final/`, translates each SVG into native DrawingML shapes, and writes the final presentation to `exports/<project>_<timestamp>.pptx`. The `-s final` flag instructs the package to read from `svg_final/` rather than the raw `svg_output/` directory.

Source: [[`skills/ppt-master/scripts/svg_to_pptx.py`](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/svg_to_pptx.py)](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/svg_to_pptx.py)

## Complete Pipeline Execution Workflow

The three scripts execute sequentially to transform raw strategist output into a finished deck:

```text
project/
├─ notes/
│   └─ total.md                # Combined speaker notes

├─ svg_output/                 # Raw SVGs from Strategist

├─ notes/<slide>.md             # Split by total_md_split.py

├─ svg_final/<slide>.svg        # Cleaned by finalize_svg.py

└─ exports/<project>_<ts>.pptx  # Final output from svg_to_pptx.py

```

Execute the full pipeline with these commands:

```bash

# 1. Split speaker notes

python3 skills/ppt-master/scripts/total_md_split.py projects/my_demo

# 2. Clean SVGs with all steps

python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo

# 3. Convert to PowerPoint

python3 skills/ppt-master/scripts/svg_to_pptx.py projects/my_demo -s final

```

Run selective cleanup steps using the `--only` flag:

```bash
python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo \
    --only embed-icons fix-rounded

```

For production builds with image compression and suppressed output:

```bash
python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo \
    --quiet --compress --max-dimension 2560

```

## Summary

- **[`total_md_split.py`](https://github.com/hugohe3/ppt-master/blob/main/total_md_split.py)** validates and splits [`notes/total.md`](https://github.com/hugohe3/ppt-master/blob/main/notes/total.md) into per-slide Markdown files that exactly match SVG filenames, ensuring perfect note-to-slide alignment.
- **[`finalize_svg.py`](https://github.com/hugohe3/ppt-master/blob/main/finalize_svg.py)** executes six ordered transformations—embed icons, crop images, fix aspect ratios, embed raster images, flatten text elements, and convert rounded rectangles—to produce PowerPoint-compatible SVGs in the `svg_final/` directory.
- **[`svg_to_pptx.py`](https://github.com/hugohe3/ppt-master/blob/main/svg_to_pptx.py)** wraps the external conversion library to render finalized SVGs into native PowerPoint DrawingML and output the completed `.pptx` file to the `exports/` folder.

## Frequently Asked Questions

### What happens if a speaker note doesn't match any SVG file in total_md_split.py?

The `check_svg_note_mapping()` function detects unmatched headings and aborts the process with a clear error message. This validation ensures that every slide has corresponding speaker notes before proceeding to conversion, preventing orphaned slides or missing documentation in the final PowerPoint.

### Can I run individual SVG cleanup steps without executing the entire finalize_svg.py pipeline?

Yes. Use the `--only` flag followed by the specific step names: `embed-icons`, `crop-images`, `fix-aspect`, `embed-images`, `flatten-text`, or `fix-rounded`. This is useful for debugging specific compatibility issues without reprocessing unchanged elements.

### Why does finalize_spg.py copy files to svg_final/ instead of modifying them in place?

The script preserves the original strategist output in `svg_output/` as an immutable source of truth. By writing all transformations to `svg_final/`, you can re-run the pipeline with different parameters or debug intermediate stages without regenerating the initial SVGs from the strategist.

### Does svg_to_pptx.py require Microsoft PowerPoint to be installed?

No. The script relies entirely on the `svg_to_pptx` Python package, which generates native Office Open XML (OOXML) markup directly. The conversion happens programmatically without COM automation or a local PowerPoint installation, making it suitable for CI/CD environments and headless servers.