PPTX Builder

A local-first CLI (and optional Web UI) for converting PDFs and image folders into clean, DPI-controlled PowerPoint slides — no PowerPoint required.

Development Process: This project was built using the Ho System, a structured methodology for human-AI collaborative development. The human makes every design decision. The AI implements under direction. There is verification at every step.

---

Quick Start

pip install sageframe-pptx-builder
pptx-builder -i document.pdf

---

Live Demo

A limited public demo is available:

https://pptx.sageframe.net

Demo limits:

• Maximum file size: 20 MB per file
• Maximum files per upload: 20
• Maximum PDF pages: 20
• Maximum DPI: 300

Files are processed in memory and automatically deleted. Nothing is stored or retained.

---

Why This Exists

• Privacy: Process files locally without uploading to online converters.
• Predictable output: A deterministic raster pipeline produces clean slides, avoiding fragile "editable" conversions that attempt unreliable text reconstruction.
• Power-tool behavior: Full control over DPI, aspect ratio, and placement — no surprise auto-fit or re-layout.

This tool deliberately favors consistent, high-quality raster output over attempts to reconstruct editable slide content.

---

Installation

Via pip (Recommended)

pip install sageframe-pptx-builder

System dependencies:

• poppler-utils (required for PDF conversion)

  • Debian/Ubuntu: sudo apt install poppler-utils
  • macOS: brew install poppler

---

With Web UI (Optional)

pip install "sageframe-pptx-builder[web]"

Run the web interface:

python -m pptx_builder.web

---

Docker (Web UI)

git clone https://github.com/sageframe-no-kaji/pptx-builder.git
cd pptx-builder
docker compose up -d

Access the interface at: http://localhost:7860

See DOCKER.md for details.

---

Usage

CLI (Primary Interface)

Interactive mode:

pptx-builder

CLI examples:

# Convert a PDF
pptx-builder -i document.pdf

# Custom output name
pptx-builder -i document.pdf -o slides.pptx

# Higher DPI (slower, sharper)
pptx-builder -i document.pdf --dpi 600

# Process folder of images
pptx-builder -i photos/

# Batch process multiple files
pptx-builder -i file1.pdf file2.pdf --quiet --force

# Process folder recursively
pptx-builder -i images/ --recursive

# Enable verbose logging
pptx-builder -i document.pdf --verbose

Common options:

• -i, --input PATH — Input file(s) or folder
• -o, --output NAME — Output filename (single input only)
• --dpi DPI — PDF rendering quality (default: 200)
• --format {jpeg,png} — Page encoding for PDF input (default: jpeg)
• --quality 1-100 — JPEG quality (default: 85; ignored when --format png)
• -r, --recursive — Process subfolders
• --quiet — Suppress prompts and non-critical output
• --force — Overwrite existing files
• --verbose — Enable debug logging
• -h, --help — Show all options

---

Output size

Since 0.3.0, PDF pages are encoded as JPEG at quality 85 and 200 DPI by default. On a 43-page deck that is roughly 14 MB, against roughly 83 MB for the previous 300 DPI PNG default.

Two levers control this, and they compound:

# Smaller — screen reading
pptx-builder -i deck.pdf --dpi 150 --quality 75

# Larger, lossless — archival or flat-colour diagrams
pptx-builder -i deck.pdf --format png --dpi 300

JPEG is smaller on photographic and gradient-heavy slides. On decks made entirely of flat-colour diagrams or screenshots, PNG can be the smaller of the two — try both if size matters and your content is graphical.

Encoding applies to PDF input only. Image folders are embedded unchanged, in whatever format you supply.

Environment variables

Defaults can be pinned without passing flags every time:

Variable	Default	Effect
PPTX_FORMAT	jpeg	Encoder for PDF pages. Set png to restore pre-0.3.0 output.
PPTX_QUALITY	85	JPEG quality, 1–100.
PPTX_DPI	200	Rendering DPI when --dpi is not given.

An explicit flag always beats the environment variable, which beats the built-in default. A malformed value is ignored with a warning rather than failing the run.

---

Web UI (Secondary Interface)

If installed with [web] extras or via Docker:

python -m pptx_builder.web

Or:

docker compose up -d
# Open http://localhost:7860

Upload files, select options, download presentation.

---

Features

Supported Formats

• PDF (multi-page supported)
• Images: PNG, JPG, JPEG, TIFF, WebP, BMP, GIF, ICO, HEIC, HEIF

Slide Sizes

• 16:9 Widescreen (13.33" × 7.5") — default
• 4:3 Standard (10" × 7.5")
• Letter (11" × 8.5")
• A4 (11.69" × 8.27")
• Legal (14" × 8.5")
• Tabloid (17" × 11")

Image Placement Modes

• Fit — No cropping; entire image visible (default)
• Fill — No whitespace; may crop edges

Output Behavior

• One slide per image or PDF page
• Images sorted alphabetically
• Centered, never stretched
• Compatible with PowerPoint, LibreOffice, and Google Slides

---

Documentation

• DOCKER.md — Docker deployment
• CONTRIBUTING.md — Development guidelines
• docs/GRADIO_TUTORIAL.md — Web UI technical guide
• docs/MAN_PAGE_USAGE.md — Man page instructions

---

Development

Setup

git clone https://github.com/sageframe-no-kaji/pptx-builder.git
cd pptx-builder
pip install -e .[dev]

Run Tests

pytest
pytest --cov=pptx_builder --cov-report=html

Code Quality

black src/
flake8 src/pptx_builder/
mypy src/pptx_builder/

Pre-commit Hooks

pre-commit install
pre-commit run --all-files

---

Notes

• 150–300 DPI covers most use cases (600 DPI is slower and sharper). The encoder usually matters more than DPI for file size — see Output size.
• Large PDFs (30+ pages) at 300 DPI may take 30–60 seconds
• Temporary files are cleaned up automatically; no persistent storage is used
• HEIC/HEIF require pillow-heif (included)

---

Author

Created by Andrew T. Marcus GitHub: https://github.com/sageframe-no-kaji

---

License

MIT License — see LICENSE.

---

Contributing

Issues and pull requests welcome:

https://github.com/sageframe-no-kaji/pptx-builder