screenjson-cli

Convert PDF to ScreenJSON

Turn a PDF screenplay into a structured ScreenJSON document using the CLI and Poppler's pdftohtml.

Last updated January 2026

What you need

A screenplay PDF, ideally one rendered from a writing tool (not a scan).
screenjson on your PATH, or Docker.
Poppler — specifically the pdftohtml binary.

Install Poppler

# macOS
brew install poppler

# Debian / Ubuntu
sudo apt-get install poppler-utils

Typical pdftohtml paths:

macOS Intel: /usr/local/bin/pdftohtml
macOS Apple Silicon: /opt/homebrew/bin/pdftohtml
Linux: /usr/bin/pdftohtml

If you use the Docker image, Poppler is already baked in — skip this step.

Convert

screenjson convert -i screenplay.pdf --pdftohtml /opt/homebrew/bin/pdftohtml -o screenplay.json

Or set it globally once:

export SCREENJSON_PDFTOHTML=/opt/homebrew/bin/pdftohtml
screenjson convert -i screenplay.pdf -o screenplay.json

Password-protected PDFs

screenjson convert -i protected.pdf --pdf-password "secret" -o screenplay.json

In Docker

docker run --rm -v "$PWD:/data" screenjson/cli \
  convert -i /data/screenplay.pdf -o /data/screenplay.json

Things to know

PDF conversion is a best-effort operation. PDFs rendered from Final Draft, Fade In, or Highland usually produce excellent results. Scanned PDFs produce poor results — OCR first with a dedicated tool.
Sluglines are reconstructed from margin and capitalisation heuristics. Always validate output and spot-check a few scenes.

Next