beffroi-tools/docs/exporter.md

3.3 KiB

Export presentations and PDF pages

python3 tools/exporter.py presentation.pptx --output pdf,images
python3 tools/exporter.py document.pdf --output images
python3 tools/exporter.py presentation.pptx --output images --dpi 192 -d exports

exporter.py uses DeckCraft for PPTX exports and PdfCraft for PDF page rendering. It finds deckcraft-cli / pdfcraft-cli on PATH, or temporarily extracts the bundled CLI from the newest matching AppImage in ~/Applications. You can specify a CLI executable or AppImage with --deckcraft-cli / --pdfcraft-cli, or the DECKCRAFT_CLI / PDFCRAFT_CLI environment variables.

Output goes to <file-stem>_export/: <file-stem>.pdf and/or numbered PNGs inside images/. Images default to 144 DPI. Existing output requires --overwrite, which replaces generated files and removes stale numbered slide/page PNGs. PDF-to-PDF is a successful no-op unless compression is requested; other input extensions are errors. Rendering completes in temporary storage before output is copied.

Smaller PDFs for email

python3 tools/exporter.py presentation.pptx --output pdf --pdf-quality email
python3 tools/exporter.py presentation.pptx --output pdf --target-size 5MB
python3 tools/exporter.py document.pdf --output pdf --pdf-quality email --target-size 5MB

Compression requires Ghostscript (gs on PATH). --dpi only controls PNG resolution. --pdf-quality controls PDF image downsampling:

Quality Image resolution
original (default) No compression pass
print 300 DPI
email 150 DPI
screen 72 DPI

These presets use Ghostscript's ebook compression settings with the indicated image resolution. They reduce image detail without deliberately rasterizing text and vector graphics. A quality preset alone does not guarantee a file size; the original is retained if it is smaller than the compressed result.

--target-size accepts bytes or units such as 5MB, 500KB, and 2.5MiB (MB = 1,000,000 bytes; MiB = 1,048,576 bytes). It starts at the selected quality, or 300 DPI if no compression preset was selected, then tries lower resolutions: 150, 120, 96, 72, 50, and 36 DPI. Each pass uses the original PDF to avoid accumulating compression damage. It stops at the first result strictly below the target, with at most seven attempts. Progress shows each attempt and its resulting byte count. A PDF already below the target is copied unchanged.

Very small targets can noticeably degrade images, and some documents cannot reach the requested size. In that case the command fails, reports the smallest size achieved, and publishes no output; existing exports remain untouched. The target applies to the PDF file itself, not email encoding overhead. PDF compression writes a separate export and never changes the input.

Ghostscript rewrites the PDF, so some interactive content or annotations may change. See its PDF output documentation.

Interactive terminals show an updating progress line, with page counts for PDF rendering and a spinner during DeckCraft's bulk export. Only output paths, the final summary, and warnings/errors remain afterward. Redirected output uses plain line logs. Set NO_COLOR to disable colors or TERM=dumb to disable animation as well.