Boozle documentation

Quick Start

Install Boozle (see the install guide), then run:

boozle slides.pdf --auto 30s

This opens your PDF fullscreen and advances every 30 seconds. Press q or Esc to quit.

boozle slides.pdf --auto 30s --loop --progress

What's New

Recent releases extend the presenter workflow: speaker notes from a PowerPoint deck can be reused in Boozle's presenter view, and a new --list-monitors flag makes multi-display setups easier to configure.

PowerPoint speaker-note import

The new boozle notes import subcommand reads speaker notes out of a .pptx file and writes a regular .boozle.toml sidecar next to the PDF. From then on, only the PDF and the sidecar are needed — the PowerPoint file isn't required at presentation time. See the Notes import section.

Speaker notes in presenter view

The presenter window now shows per-slide notes alongside the current slide, next-slide preview, wall clock, elapsed time, slide counter, and timer. Notes are sourced from [[page]] entries in the sidecar — either authored manually, or generated by boozle notes import.

List connected displays

boozle --list-monitors (or -M) prints the index, name, and DPI scale of every connected display so you can pick the right one for --monitor or --presenter-monitor without guessing.

Memory tuning for big decks

--cache-mb hard-caps the GPU page cache, and --render-scale rasterises pages at a fraction of native pixels (0.5..1.0). Useful for very large decks on high-DPI displays where memory pressure matters more than pixel-perfect sharpness.

Slide transitions

Page transitions support slide (lateral push), fade (cross-dissolve), and none (instant cut) via --transition or the sidecar.

Common Commands

Loop a PDF slideshow

boozle deck.pdf --auto 20s --loop

Show a progress overlay

boozle deck.pdf --auto 20s --loop --progress

Start from page 10

boozle deck.pdf --start 10

Present selected pages

boozle deck.pdf --auto 30s --pages 3-7,10

Use a second monitor

boozle deck.pdf --monitor 1

Use presenter view on another monitor

boozle deck.pdf --monitor 1 --presenter-monitor 0

Fade between slides

boozle deck.pdf --transition fade

Play once and quit

boozle deck.pdf --auto 30s --autoquit

Custom background color

boozle deck.pdf --bg #1a1a2e

Use a sidecar config

boozle deck.pdf --config deck.boozle.toml

List connected displays

boozle --list-monitors

Prints the index, name, and DPI scale of every connected display, then exits. Use the index with --monitor or --presenter-monitor.

Import PowerPoint speaker notes

boozle notes import deck.pptx --out deck.boozle.toml

Generates a sidecar with one [[page]] entry per slide that has real speaker notes. The PowerPoint file is no longer needed at presentation time.

Trim memory on big decks

boozle deck.pdf --render-scale 0.75 --cache-mb 64

Rasterises at 75% of native pixels and hard-caps the GPU page cache at 64 MB.

CLI Reference

All available flags for boozle:

PowerPoint Notes Import

Boozle's presenter view shows per-slide notes from your TOML sidecar. To avoid retyping notes you already have in PowerPoint, run the boozle notes import subcommand once as a preparation step. From then on you only need the PDF plus the generated sidecar — the .pptx file is no longer required at presentation time.

# Default: writes deck.boozle.toml next to the .pptx
boozle notes import deck.pptx

# Choose the output sidecar path explicitly
boozle notes import deck.pptx --out deck.boozle.toml

# --config is accepted as an alias for --out
boozle notes import deck.pptx --config deck.boozle.toml

# Replace an existing generated sidecar
boozle notes import deck.pptx --out deck.boozle.toml --force

The importer supports modern .pptx files. Old binary .ppt files should be converted to .pptx first. Slides without real speaker notes are omitted, and PowerPoint notes-page slide-number placeholders such as notes = "17" are ignored.

Generated entries look like this in the sidecar:

[[page]]
n     = 6
notes = "Schnelle Antworten. Wenig Reibung. Hohe Zuversicht."

Once the sidecar exists, present as usual and add a presenter monitor to surface the notes:

boozle deck.pdf --presenter-monitor 0

Keyboard Shortcuts

Controls available during a presentation:

When presenter view is enabled, the same navigation keys work when the presenter window has focus.

Sidecar Config

Boozle automatically looks for a .toml file with the same base name as your PDF in the same directory. Place deck.boozle.toml next to deck.pdf and it loads automatically. Use --config to specify a different path.

Presentation settings that travel with your PDF. Command-line flags always take precedence over sidecar values.

# Global defaults apply to all slides
auto     = "30s"      # advance every 30 seconds
loop     = true       # restart after last slide
progress = true       # show countdown HUD
pages    = "1-5,8,10-12"  # optional page range
bg       = "#0a0a0a"  # background color
autoquit = false      # don't quit at end (looping)
transition = "fade"    # slide, fade, or none
# presenter_monitor = 0       # optional speaker display
# cache_mb     = 64           # hard-cap GPU page cache
# render_scale = 0.75         # render at 75% of native pixels

# Override timing for specific slides
[[page]]
n    = 3
auto = "1m"    # complex diagram — hold for 1 minute

[[page]]
n    = 8
auto = "5s"    # transition slide — move quickly

# Speaker notes — shown in presenter view
[[page]]
n     = 5
notes = """
Mention the rollout date.
Pause for questions before moving on.
"""

Sidecar config keys

Platform Notes

macOS — Gatekeeper

If macOS Gatekeeper blocks the binary on first launch, right-click (or Control-click) the file in Finder and choose Open. Confirm in the dialog. Subsequent launches work normally. Alternatively, clear the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/boozle

Windows — SmartScreen

Windows SmartScreen may show a warning for unsigned binaries. Click More info then Run anyway if you trust the release source. Checksums are published alongside each release on GitHub Releases.

Linux — PATH setup

The shell script installer verifies the archive against checksums.txt, installs to /usr/local/bin when possible, and falls back to ~/.local/bin. Make sure the fallback directory is on your $PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"