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

Boozle 1.4.0 adopts the new Boozle design system, the same identity you see on this site. Flags, sidecars and keyboard shortcuts are unchanged, so existing decks and commands work as before. Every release is listed on GitHub Releases.

1.3.1

1.3.0

Speed and dependable multi-display setups: Boozle starts almost instantly, uses far less memory, lets you pick displays by name, and reads PDF Presenter Console files.

Common Commands

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

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

boozle deck.pdf --start 10

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

boozle deck.pdf --monitor 1

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

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

boozle talk.pdf --config talk.pdfpc --presenter-monitor 0

boozle deck.pdf --transition fade

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

boozle deck.pdf --bg #1a1a2e

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

boozle --list-monitors

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

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

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

CLI Reference

All available flags for boozle. Flags given on the command line always override the sidecar, even when they repeat a default.

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.

Without --loop or --autoquit, navigation stops at the first and last slide. The mouse cursor hides itself after three seconds without movement.

Sidecar Config

Boozle automatically looks for a sidecar with the same base name as your PDF in the same directory. Place deck.boozle.toml next to deck.pdf and it loads automatically. If there is no Boozle TOML sidecar, deck.pdfpc is loaded instead (see pdfpc Sidecars). Use --config to specify a different path.

Presentation settings that travel with your PDF. Command-line flags always take precedence over sidecar values, even when they repeat a default, so --monitor 0 or -P -1 overrides a sidecar’s monitor or presenter_monitor.

# Global defaults apply to all slides
auto     = "30s"      # advance every 30 seconds
loop     = true       # restart after last slide
progress = true       # show countdown HUD
start    = 1          # first page to show (1-indexed)
monitor  = 0          # audience display: index or name
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 = "HDMI-1"  # optional speaker display: index or name
# 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

pdfpc Sidecars

.pdfpc files are the JSON sidecars written by PDF Presenter Console. Boozle loads deck.pdfpc automatically when there is no deck.boozle.toml, or you can pass one explicitly with --config.

boozle talk.pdf --presenter-monitor 0                     # auto-loads talk.pdfpc
boozle talk.pdf --config slides/talk.pdfpc --presenter-monitor 0

Boozle reads the following from the file:

• Page order becomes the playback order, including duplicate entries used for overlays. If you also pass --pages, only pages in both are played.
• Pages marked hidden are skipped.
• note values are shown as plain text in presenter view.

Only pdfpcFormat 2 is supported. pdfpc-specific features such as movies, drawing state, timers, transition metadata and Markdown formatting of notes are ignored. Playback settings such as --auto, --loop or --transition come from command-line flags when a pdfpc file is used.

{
  "pdfpcFormat": 2,
  "pages": [
    { "idx": 0, "note": "Welcome, introduce the team." },
    { "idx": 1, "hidden": true },
    { "idx": 2, "note": "Demo time." }
  ]
}

Performance & Memory

Boozle renders slides on a background worker and keeps the current slide and its neighbours in a GPU cache, so turning a page is usually instant. Memory use is bounded by that cache, not by the length of the deck. On a 300-page deck, the audience window settles around 155 MB in a 1280×720 window and around 340 MB full-screen on a Retina display.

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

• Automatic budget: sized from the display at about four full-screen slides, between 32 MB and 192 MB. It counts the GPU memory slides really occupy.
• --cache-mb <N> replaces the automatic budget with a hard cap. Prefetching adapts so prefetched slides are not evicted before they are shown.
• --render-scale <F> rasterises pages at a fraction of native pixels (0.5..1.0). Memory per slide falls with the square of the factor (0.75 uses about 56%), at the cost of some sharpness. It is the strongest lever on 4K and Retina displays.
• Presenter view runs as a second process with its own renderer and cache, sized for its smaller panes, so expect it to add to the total.
• --debug-stats prints GPU and heap usage, cache occupancy and render timings to stderr every two seconds, for both windows.

Disk caches

Boozle keeps two caches in your user cache directory: the compiled PDF engine, which makes every launch after the first start in a fraction of a second, and overview thumbnails, which are pruned automatically after 30 days or beyond 200 MB.

Set BOOZLE_CACHE_DIR to use a different location. Deleting the directory is always safe.

Platform Notes

xattr -d com.apple.quarantine /path/to/boozle

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

sudo apt-get install libgl1 libxrandr2 libxinerama1 libxcursor1 libxi6 libxxf86vm1

Multi-monitor fullscreen depends on XRandR and Xinerama (libxrandr2, libxinerama1). Without them, only one monitor is listed or fullscreen may land on the wrong display.

X11 reports a single scale factor for all monitors, so on mixed-DPI setups slides render at the global scale. Use --render-scale or your desktop’s scaling settings if that is too sharp or too soft.

# ~/.config/i3/config
for_window [class="^boozle$" instance="^audience$"]  move container to output HDMI-1
for_window [class="^boozle$" instance="^presenter$"] move container to output eDP-1