sageframe-pptx-builder 0.2.1

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

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: 20MB per file
• Maximum files per upload: 15
• Maximum PDF length: 100 pages
• 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: 300)
• -r, --recursive — Process subfolders
• --quiet — Suppress prompts and non-critical output
• --force — Overwrite existing files
• --verbose — Enable debug logging
• -h, --help — Show all options

---

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 recommended for most use cases (600 DPI is slower but sharper)
• 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