Migrating Sozi Presentations to PDF

A step-by-step guide for converting .sozi.html presentations into PDF files.

Overview

Sozi presentations are SVG-based, zooming presentations exported as a single .sozi.html file. To archive, print, or share them as static documents, you often want a plain PDF.

The recommended tool is sozi-export, which reads the presentation's own frame definitions and exports exactly the frames you authored. This is more reliable than generic tools like DeckTape, which don't understand Sozi's frame model and tend to produce detached-frame errors or hang until they time out.

This guide covers the full setup on macOS, including all dependencies.

Dependencies

You need three things:

Node.js and npm — to run the exporter. Check with node --version. If missing, install via Homebrew on macOS (brew install node), your package manager on Linux (e.g. sudo apt install nodejs npm), or the official installer from nodejs.org on Windows.
sozi-export — the export tool itself, installed globally through npm.
pdfjam — used by sozi-export to merge the per-frame PDFs into a single file. It ships with TeX Live, so you install TeX Live to get it.

Note: sozi-export exports each frame as its own one-page PDF and then calls pdfjam to stitch them together. If pdfjam is missing you'll see ERROR: pdfjam executable not found, so it must be installed before exporting.

Step 1 — Install the exporter

npm install -g sozi-export

This provides two commands: sozi-to-pdf and sozi-to-video.

Step 2 — Install pdfjam (TeX Live)

pdfjam comes from TeX Live. Install it for your platform:

macOS (Homebrew):

brew install texlive

Linux (Debian/Ubuntu):

sudo apt install texlive-extra-utils

Windows:

Install TeX Live using the official installer, which includes pdfjam.

Then confirm pdfjam is available:

which pdfjam        # macOS / Linux
where pdfjam        # Windows

If it isn't found even after installing, open a new terminal so your PATH is refreshed. On macOS you may also need to add the TeX binary directory:

export PATH="/Library/TeX/texbin:$PATH"

Step 3 — Convert a single presentation

sozi-to-pdf presentation.sozi.html presentation.pdf

The output PDF will contain one page per Sozi frame, in order.

Step 4 — Convert many presentations at once

To batch-convert every .sozi.html file in the current folder, stripping the .sozi.html suffix so the output is named name.pdf:

macOS / Linux (bash):

for f in *.sozi.html; do
  sozi-to-pdf "$f" "${f%.sozi.html}.pdf"
done

The quotes around "$f" matter if your filenames contain spaces.

Windows (PowerShell):

Get-ChildItem *.sozi.html | ForEach-Object {
  sozi-to-pdf $_.Name ($_.Name -replace '\.sozi\.html$', '.pdf')
}

Troubleshooting

pdfjam executable not found — pdfjam is not installed or not on your PATH. Complete Step 2 and verify with which pdfjam.

DeckTape "detached Frame" errors or timeouts — These happen when DeckTape falls back to its generic plugin because it has no native Sozi support. The generic plugin keeps probing for frames (you may see counts in the thousands) until it errors or times out. The fix is to use sozi-export instead, as described above.

Wrong or missing frames in the output — Make sure you're pointing at the exported .sozi.html file, not the source .svg. The HTML export contains the frame definitions the tool reads.