PDFPC(1)

📦
version 4.7.0 · 5 versions
, in arch rolling, debian trixie, fedora 43, fedora 44, ubuntu questing, ubuntu resolute, ubuntu stonking

okay so this is pdfpc(1) straight outta the General Commands Manual, and it's giving presenter-console excellence, no cap 💖

✨ NAME ✨

pdfpc — PDF presenter console with multi-monitor support 🖥️🫶

✨ SYNOPSIS ✨

pdfpc [options] PDF-file

✨ DESCRIPTION ✨

okay bestie, pdfpc is a GTK-based presentation viewer that does the Keynote-like multi-monitor output thing so the speaker gets all the meta info during the presentation 🌸. The way it works is it shows a totally normal presentation window on one screen while serving a way more sophisticated overview on the other one — giving you stuff like a picture of the next slide, plus the time left in the presentation. It processes PDF documents, which literally nearly all modern presentation software can create for you. iconic.

By default the presenter view appears on the primary monitor and the presentation view on the second monitor (provided you have two monitors, which, slay).

✨ OPTIONS ✨

  • -B, --list-bindings — lists the action bindings that are defined 📋
  • -c, --cfg-statement=STRING — treats the string as a pdfpcrc(5) statement. You can pass multiple statements, go off 👑
  • -C, --time-of-day — shows the time of the day 🕐
  • -d, --duration=N — duration in minutes of the presentation, used for the timer display. If you don't give it, or if you give a value of 0, the clock just measures the time you've been in the presentation ⏱️
  • -e, --end-time=T — end time of the presentation. (Format: HH:MM (24h)) 🌙
  • -f, --note-format=FORMAT — forces the format of notes (plain or markdown. Default: markdown) 📝
  • -g, --disable-auto-grouping — disables auto detection of overlay groups. (Default: enabled) 🙈
  • -h, --help — shows this help 🆘
  • -l, --last-minutes=N — in the old timer mode (see Timer below), defines the time in minutes before the end of the talk when the timer changes its color. (Default: 5 minutes) 🎨
  • -L, --list-actions — lists the actions supported 🗒️
  • -M, --list-monitors — lists the monitors known to the operating system 🖥️
  • -n, --notes=P — position of the second-screen beamer notes on the PDF page (left, right, top, bottom, or none. Default: none). Heads up though: this disables slide auto-grouping 🚨
  • -N, --no-install — allows testing pdfpc without a proper installation. Icons, configuration files, etc. get loaded from the source path locations. Mostly intended for developers 🧑‍💻
  • -p, --rest-port — the port the REST server binds to. (Default: 8088) 🔌
  • -P, --page — go to a specific page directly after startup. In case of overlays, the first slide will be displayed 📄
  • -r, --page-transition=TRANSITION — sets the default page transition. The TRANSITION specification has the form type[:duration[:angle[:alignment[:direction]]]]. Peep the Page transitions section for the list of supported types. duration is in seconds and set to 1 by default. Accepted values for angle are 0/90/180/270; alignment can be h[orizontal] or v[ertical] and direction can be i[nward] or o[utward]. The last three optional settings are meaningless for some of the transition types and can be left empty. Examples: "push", "dissolve:1.5", "wipe:1:90", "split:1::vertical:outward" ✨
  • -R, --pdfpc-location=LOCATION — use a custom pdfpc file 📁
  • -s, --switch-screens — switches the presentation screen and the presenter screen 🔄
  • -S, --single-screen — forces using only one screen 1️⃣
  • -t, --start-time=T — start time of the presentation, to be used as a countdown. (Format: HH:MM (24h)) ⏳
  • -T, --enable-auto-srt-load — tries loading video subtitle files automatically. For each video media, pdfpc will append ".srt" to the media URI and attempt to load a subtitle file (in the SRT format) from that location 💬
  • -V, --enable-rest-server — enables the REST server for remote control of pdfpc 🎛️
  • -W, --wayland-workaround — enables the Wayland-specific workaround. This might fix HiDPI scaling problems 🔧
  • -w, --windowed=MODE — runs in the given windowed mode (presenter|presentation|both|none). The default mode is "presenter" (only the presentation window is fullscreen) 🪟
  • -X, --external-script=FILENAME — specifies a script to be executed with the 'X' (Shift+x) key during the presentation. The script must be executable but can otherwise be written in any language. The script is called with the following command line arguments:
    • Name of pdf file
    • Total slide count
    • Current slide number
    • Current user slide number

If the script exits with a non-zero return value, whatever the script wrote to stdout is printed in the console. Otherwise nothing is printed 💀

  • -Z, --size — size of the presentation window in width:height format (forces windowed mode) 📐
  • -1, --presenter-screen=MONITOR — the monitor to be used for the presenter screen (see the -M option) 1️⃣
  • -2, --presentation-screen=MONITOR — the monitor to be used for the presentation screen (see the -M option) 2️⃣

✨ KEYBINDINGS ✨

these are the default keybindings for pdfpc, bestie ⌨️💅

  • Right cursor key / Down cursor key / Page down / Return / Space / 1st mouse button / Mouse wheel down — go forward one slide ➡️
  • Left cursor key / Up cursor key / Page up / Backspace / 3rd mouse button / Mouse wheel up — go back one slide ⬅️
  • Shift + Page down — go forward one user slide (see Overlays below)
  • Shift + Page up — go back one user slide (see Overlays below)
  • Shift + Right cursor key / 1st mouse button / Mouse wheel down — go forward 10 slides 🔥
  • Shift + Left cursor key / 3rd mouse button / Mouse wheel up — go back 10 slides 🔥
  • Shift + n — go forward 1 slide irrespectively of its "hidden" attribute
  • Shift + p — go backward 1 slide irrespectively of its "hidden" attribute
  • Home — go to the first slide 🏠
  • End — go to the last slide 🔚
  • Shift + Backspace / Shift + Space — go back / forward in history 🕰️
  • Shift + Home / Shift + End — go to the previous / next slide, skipping over overlays that have already been viewed, but at most one user slide
  • Tab / 2nd mouse button — overview mode 👀
  • g — input a slide number to jump to
  • m — bookmark the current slide and store it in the .pdfpc file for later usage 🔖
  • Shift + m — load the bookmarked slide which was saved with m before
  • t — toggle the toolbox 🧰
  • 1 / KP_1 — switch to the normal mode (pen/eraser and pointer are off)
  • 2 / KP_2 — switch the pointer mode on 👆
  • 3 / KP_3 — switch the pen drawing mode on 🖊️
  • 4 / KP_4 — switch the eraser drawing mode on 🧽
  • 5 / KP_5 — switch the spotlight mode on 🔦
  • Plus / KP_Add / Equal — depending on the current mode, increases font size of notes, or pointer size, or the size of pen or eraser or spotlight ⬆️
  • Minus / KP_Subtract — depending on the current mode, decreases font size of notes, or pointer size, or the size of pen or eraser ⬇️
  • c — clear the drawing on the current page 🧼
  • d — toggle visibility of the drawings; if you're in the drawing mode (pen/eraser), it exits it
  • f — freeze the current presentation display (the presenter display is still fully active) 🧊
  • w — toggle between the fullscreen and windowed mode of the presenter screen
  • Shift + a — maximize/unmaximize the current slide view (e.g., to increase accuracy while drawing) 🎯
  • b — turn off the presentation view (i.e. fill it with a black color) 🖤
  • h — hide the presentation window (i.e. make other windows on the other screen visible) 🙈
  • Escape — exit any "special" state (pause, freeze, blank) 🚪
  • Ctrl + n — edit notes for the current slide (press Escape to exit this mode) 📝
  • Ctrl + z — in drawing and eraser mode, undo the last added stroke or erase curve ↩️
  • Ctrl + y — in drawing and eraser mode, redo the last undone stroke or erase curve ↪️
  • s — start timer ⏱️
  • p — pause/continue timer ⏸️
  • Shift + t — cycle between the timer view modes (count up/count down/current time), when applicable 🔁
  • Ctrl + t — reset timer
  • Ctrl + o — toggle the overlay flag for one particular slide (see Overlays below)
  • Ctrl + h — toggle the hidden attribute for the current slide (see Hidden slides below)
  • Ctrl + e — define end slide 🏁
  • Ctrl + r — reload the presentation (e.g., if the PDF file has been updated) 🔄
  • Ctrl + q — exit pdfpc 👋
  • ? — show a cheat sheet with the keyboard and mouse bindings; press Escape or Return to exit it 📜

within the overview mode, these keybindings kick in 🌈

  • Return / 1st mouse button — go to currently selected page (last page of overlay)
  • Shift + Return / Shift + 1st mouse button — go to currently selected page (first page of overlay)
  • Cursor left / Page up — select previous slide
  • Cursor right / Page down — select next slide

See pdfpcrc(5) if you want to customize the key or mouse bindings 🫶. Please note though, that only in the normal mode the mouse bindings are configurable.

✨ FEATURES ✨

Caching / Pre-rendering 🧠✨

To allow fast changes between the presentation slides, a few consecutive PDF pages (the number is configurable) are pre-rendered and kept in memory. To avoid excessive memory consumption, only slides that took a significant time to render get cached — and this threshold is configurable too. To further reduce memory consumption, the pre-rendered and cached slides are selectively compressed. The compression factor is typically 10-30, however, it takes some CPU time to compress and uncompress, so there is a trade-off. Small images below a certain (configurable) threshold will not be compressed.

Please refer to the pdfpcrc(5) man page for options to fine-tune the caching algorithm 💖

Timer ⏰

If a duration is given (-d option), the timer will show a countdown with the given parameters. If no duration is specified (or if a value of 0 is given to the -d option), the timer will show how much time has been spent. The duration is stored automatically, so you do not need to repeat it for every invocation. lowkey convenient.

The timer is started if you are navigating away from the first page for the first time. This feature is quite useful as you may want to show the title page of your presentation while people are still entering the room and the presentation has not really begun yet 🎀. If you want to start over you can use the 'Ctrl + t' key which will make the presenter reset the timer.

If a duration is given, the timer also drops some hints to help you judge whether your talk is actually gonna end on time. 🫶 There are two modes pdfpc can vibe in.

In the old mode — literally the only one that existed up to and including pdfpc-4.0.8 — the moment the timer hits the last-minutes value you set, it changes color to tell you your talk is nearing its end. It's giving "a chairman frantically pantomiming in front of you with five (four, three, ...) fingers up". 💅 The drawback? By then it's often way too late to switch up your presentation pace without ruining some part of the rest of the talk. On the other hand, that warning is straight-up unnecessary distraction if you've been perfectly conveying the talk and your remaining time is totally adequate.

Now the new (default) mode, which is the slay one: pdfpc tracks your progress continuously, calculating the expected time as

(talk_duration)*(current_user_slide_number - 0.5)/(total_number_of_user_slides)

and comparing it against the actual wall time since the beginning of the talk. If those two numbers differ by more than 60 seconds, the timer changes its color to either orange (you need to speed up, bestie 🏃) or a blueish one (you need to slow down). The second optimal progress is recovered, the timer goes back to white. In this mode, the last-minutes option (-l) has no effect. Wanna restore the previous behavior? Set the 'timer-pace-color' option to 'false' in the configuration file — see pdfpcrc(5).

And in any case, as soon as the timer reaches the zero mark (00:00:00), it turns red and keeps counting further down showing a negative time, so you know exactly how many minutes you're overtime. 💀 Iconic. Terrifying. Necessary.

📝 Notes

Textual notes can be displayed for each slide, and pdfpc understands the Markdown syntax — so you can render anything from plain text to a very rich formatting if that's your vibe. ✨ A few types of PDF annotations are also understood by pdfpc, and they get automatically imported and displayed. You can make PDF annotations using many PDF editors and even viewers; if you're on LaTeX, the pdfpc package (see below) provides a convenient macro. Heads up: these "native" PDF notes cannot be edited in pdfpc.

Also, while in the presentation mode, pressing 'Ctrl + n' lets you take or edit notes for the current slide. 🎀 These notes are stored in the .pdfpc file. But the native PDF annotations take precedence over these notes — meaning if a note exists for a given slide in the .pdfpc file, any PDF annotation on that page will silently override it. While you're editing a note, the normal keybindings are disabled, e.g. you literally cannot change slides. To exit the note editing mode, press Escape.

Mixing the two types of notes is possible, but for a given presentation you'll probably want either only the "native" notes (produced by the same PDF authoring software you used for making the slides) or only the "pdfpc" ones. And note that if the PDF presentation changes, the notes stored in the respective .pdfpc file may get out of sync. 😭

pdfpc also supports old-style beamer notes (see the -n option), which are typeset on a half of the "virtual" slide twice as large as the real one. Just know that due to a bug in beamer, the auto-grouping feature does not work with such presentations. 💀

🦋 Overview mode

Press the Tab key and boom, you're in overview mode — thumbnails of the slides shown in a grid. 🌈 You can select a slide to jump to with the mouse or with the arrow keys. You can also define overlays and the end slide (see the next sections) right in this mode. Press Escape to exit the mode without making a change.

🎀 Overlays

Many slide preparation systems allow for overlays, i.e. sets of slides that are logically grouped together as a single, changing slide. Examples: enumerations where bullet items are displayed one after another, or rough "animations" where parts of a picture change from slide to slide. Pdfpc includes facilities for dealing with such overlays. ✨

In this description, we differentiate between slides (i.e. pages in the PDF document) and "user slides", which are the logical slides. The standard forward movement command (page down, enter, etc.) moves through one slide at a time, as expected. This means every step in the overlay gets traversed. The backward movement command works differently depending on whether the current and previous slides are part of an overlay:

  • If the current slide is part of an overlay we just jump to the previous slide. That means we're in the middle of an overlay and can jump forward and backward through the single steps of it.
  • If the current slide is not part of an overlay (or if it is the first one), but the previous slides are, we jump to the previous user slide. That means when going back in the presentation you do not have to go through every step of the overlay — pdfpc just shows the first slide of each overlay. Since one typically goes back in a presentation only when looking for a concrete slide, this is more convenient. 💅

The Shift + Page up/down key combos work on the "user slide" basis. You can use them to skip the rest of an overlay or to jump to the previous user slide, ignoring the state of the current slide.

When going through an overlay, two additional previews may be activated in the presenter view, just below the main view, showing the next and the previous slide in an overlay. 👑

Pdfpc tries to find these overlays automatically by looking into the page labels in the PDF file. For LaTeX this works correctly at least with the beamer class and also when modifying the page numbers manually (compiling with pdflatex). If your preferred slide-producing method does not work correctly with this detection, you can supply this information using the 'Ctrl + o' key for each slide that is part of an overlay — except the first one! The page numbering is also adapted. This information is automatically stored. 🎀

🙈 Hidden slides

When preparing a presentation from an existing set of slides, it's sometimes helpful to mark certain slides to be skipped during the talk. The 'Ctrl + h' combo toggles the "hidden" attribute of the current slide, making it essentially invisible. It's still possible to navigate to a hidden slide, either in the Overview mode using the Goto action ('g'), or by hitting 'Shift + n' or 'Shift + p' to switch to the next/previous slide respectively, ignoring the "hidden" attribute. 🫶

🌸 End slide

Some people like to have some additional, backup slides after the last slide in the actual presentation. Bibliographic references or slides referring to specialized questions are the typical examples. Pdfpc lets you define which is the last slide in the actual presentation via the 'Ctrl + e' key. This just changes the progress display in the presenter screen, so you get a better overview of how many slides are left. ⭐

✨ Page transitions

Pdfpc supports almost all standard animated PDF page transitions: blinds, box, cover, dissolve, fade, glitter (except the diagonal one), push, split, uncover, and wipe, including various alignments, angles, and directions (where applicable). The transitions are enabled only for sequential (either forward or backward) movement; in the later case, the transition is "inverted".

Advancing slides automatically is also supported. 🔥

🍓 Movies

Pdfpc can play back movies included in the PDF file. 🎬 Movies may be started and stopped by clicking within their area. For the presenter, a progress bar is drawn along the bottom of the movie. This expands when the mouse hovers over it, allowing one to seek by clicking or dragging within the progress bar. Switching slides automatically stops playback, and movies will be reset after leaving and returning to a slide.

Movies may be included in PDF files as "screen annotations". In LaTeX, such movies may be added to a presentation with the "multimedia" package. Note that the autoplay option is not yet supported. 😭

pdfpc will also play back movies linked from a hyperlink of type "launch".

See our website ⟨http://pdfpc.github.io/demo/pdfpc-video-example.zip⟩ for a detailed explanation with examples. 💖

🧚 Pointer mode

If needed, it's possible to turn on a pointer which draws a red (by default) dot in the place pointed by the mouse cursor on both the presenter and presentation screens. You can also increase and decrease the pointer size. ✨ Additionally, when the pointer is enabled, you can highlight some area of the current slide using the drag mouse motion. The area outside the selected region will be dimmed. You can zoom in the selected area by pressing 'z'; press 'Escape' to exit the zoom mode. You can highlight another region while zoomed in, but there will be no further action on pressing 'z'. Drawing is also disabled in this mode.

🔦 Spotlight mode

Spotlight mode is similar to the pointer mode: a circular area that moves with the mouse and can be adjusted in size, but instead of highlighting the spot by a different color, it shades the background. 👑

💜 Drawing mode

It's possible to turn on a mode which allows drawing over slides with the mouse cursor or a connected tablet. When drawing mode is enabled, drawings can be made on the presenter screen. A separate drawing will be kept in memory for each slide (based on user slide numbers, so consolidating overlay slides). Drawings are presently not saved between sessions. 🙈

In the drawing mode there are two drawing tools: a pen and an eraser. An indicator in the bottom-left corner of the presenter screen will show which one is active. When in the pen mode, the color and size of the pen will be indicated by the cursor. The pen size can be increased or decreased using hot keys specified in the key bindings. When the eraser tool is active, the size of the cursor indicates the amount to erase.

The color of the pen can be changed through key bindings or using the toolbox.

If you're using a tablet, the pen or eraser tool will be selected based on whether the tablet reports a pen or eraser input device is being used, overriding the normal selection of the drawing tool. Also, for pressure-sensitive input devices, the pressure will affect the line width and the eraser size. 🎀 Both these features can be disabled in the configuration file, if desired.

🌈 Monitor Plug and Play

Pdfpc can handle monitor plug and play. E.g. if pdfpc was started before the presentation screen was attached to the computer, pdfpc can create and show the presentation screen after the second screen was attached. This allows you to rehearse the slides and switch to a normal presentation without having the full setup at the computer in advance. ⭐

📁 pdfpc files 📁

Okay bestie, listen up — notes, user-defined overlays, and some additional information are stored in a file with extension pdfpc. When pdfpc is invoked with a PDF file, it automatically checks for and loads the associated .pdfpc file, if it exists. This means that you normally do not have to deal with this kind of files explicitly. 💖

Beside internal configuration, the following command-line options are saved in the pdfpc file for later usage:

  • duration
  • end_time
  • last_minutes
  • notes (position)
  • page_transition
  • start_time

Slay, that's the whole save file situation. ✨

✨ Appearance ✨

With GTK3 it is possible to modify the appearance of pdfpc. There are two locations where pdfpc is looking for files. The default location is /usr/share/pixmaps/pdfpc/pdfpc.css. It can be copied to $XDG_CONFIG_HOME/pdfpc/pdfpc.css and modified to the user's liking. 🎀

The geometry of various views (the current/next etc slide) in the presenter window can be adjusted at run time in the "Customization" mode, which is activated by pressing Shift+c. In this mode, mouse-draggable handles will appear. Exit the customization with Escape. 💅

🌐 Desktop integration 🌐

Pdfpc provides a DBus interface that appears on the session bus as io.github.pdfpc. Other applications can, in particular, execute any action listed by --list-actions. It is also possible to control pdfpc from the command line (and write shell scripts) using the dbus-send(1) utility. For example, to advance to the next slide, run:

dbus-send --type=method_call --session --dest=io.github.pdfpc
 /io/github/pdfpc io.github.pdfpc.TriggerAction string:next

For actions that require an argument, use TriggerActionArg, e.g.,

dbus-send --type=method_call --session --dest=io.github.pdfpc
 /io/github/pdfpc io.github.pdfpc.TriggerActionArg string:switchMode
 string:pointer

In addition to TriggerAction*, the pdfpc DBus interface exposes the GetNotes method, three properties (NumberOfOverlays, NumberOfSlides, Url) and two signals (OverlayChange and SlideChange). 🔥

📱 Remote control 📱

Pdfpc has a built-in REST server. When enabled (off by default), it allows for controlling presentations over network, e.g., using a mobile device as a smart controller. (This section will be extended with more details when the REST interface sufficiently stabilizes.) 🦋

🧚 LaTeX package 🧚

A tiny LaTeX package is available for pdfpc at CTAN. It provides a convenient way to specify notes and to define certain meta properties of the presentation. For a full documentation, please consult the pdfpc package documentation. You can open it with:

$ texdoc pdfpc

💀 BUGS 💀

Bugs can be reported at our issue tracker https://github.com/pdfpc/pdfpc/issues. 🙈

👑 ACKNOWLEDGEMENTS 👑

pdfpc was previously developed by David Vilar https://github.com/davvil/pdfpc, which in turn was a fork of Jakob Westhoff's PDF Presenter Console https://github.com/jakobwesthoff/Pdf-Presenter-Console. 💖

🌈 SEE ALSO 🌈

pdfpcrc(5)

There are several other programs with similar functionality. 👀

And that's the whole page, bestie 💖 — the footer signs off with PDFPC(1) and carries the source/version and date stamp, so you know it's official. periodt. ✨

📦 where this page comes from