Provided by: pympress_1.8.5-2_all 
NAME
pympress - pympress documentation
CONTENTS
What is Pympress?
Pympress is a PDF presentation tool designed for dual-screen setups such as presentations and public
talks. Highly configurable, fully-featured, and portable
It comes with many great features (more below):
• supports embedded gifs (out of the box), videos, and audios (with VLC or Gstreamer integration)
• text annotations displayed in the presenter window
• natively supports beamer's notes on second screen, as well as Libreoffice notes pages!
Pympress is a free software, distributed under the terms of the GPL license (version 2 or, at your
option, any later version).
Pympress was originally created and maintained by Schnouki <https://github.com/Schnouki>, on his repo
<https://github.com/Schnouki/pympress>.
Usage
Opening a file
Simply start Pympress and it will ask you what file you want to open. You can also start pympress from
the command line with a file to open like so: pympress slides.pdf or python3 -m pympress slides.pdf
Functionalities
All functionalities are available from the menus of the window with slide previews. Don't be afraid to
experiment with them!
Keyboard shortcuts are also listed in these menus. Some more usual shortcuts are often available, for
example Ctrl+L, and F11 also toggle fullscreen, though the main shortcut is just F.
A few of the fancier functionalities are listed here:
• Two-screen display: See on your laptop or tablet display the current slide, the next slide, the talk
time and wall-clock time, and annotations (either PDF annotations, beamer notes on second slide, or
Libreoffice notes pages). The position of the beamer or Libreoffice notes in the slide is detected
automatically and can be overridden via a menu option.
If you do not want to use second-slide beamer notes but prefer to have notes on their own pages, you
can enable auto-detection of these notes. Use the following snippet that prefixes the page labels with
notes: on notes pages:
\addtobeamertemplate{note page}{}{\thispdfpagelabel{notes:\insertframenumber}}
• Media support: supports playing video, audio, and gif files embedded in (or linked from) the PDF file,
with optional start/end times and looping.
• Highlight mode: Allows one to draw freehand on the slide currently on screen.
• Go To Slide: To jump to a selected slide without flashing through the whole presentation on the
projector, press G or click the "current slide" box. Using J or clicking the slide label will allow
you to navigate slide labels instead of page numbers, useful e.g. for multi-page slides from beamer
\pause.
A spin box will appear, and you will be able to navigate through your slides in the presenter window
only by scrolling your mouse, with the Home/Up/Down/End keys, with the + and - buttons of the spin box,
or simply by typing in the number of the slide. Press Enter to validate going to the new slide or Esc
to cancel.
• Deck Overview: Pressing D will open an overview of your whole slide deck, and any slide can be opened
from can simply clicking it.
• Software pointer: Clicking on the slide (in either window) while holding ctrl down will display a
software laser pointer on the slide. Or press L to permanently switch on the laser pointer.
• Talk time breakdown: The Presentation > Timing Breakdown menu item displays a breakdown of how much
time was spent on each slide, with a hierarchical breakdown per chapters/sections/etc. if available in
the PDF.
• Automatic file reloading: If the file is modified, pympress will reload it (and preserve the current
slide, current time, etc.)
• Big button mode: Add big buttons (duh) for touch displays.
• Swap screens: If Pympress mixed up which screen is the projector and which is not, press S
• Automatic full screen: pympress will automatically put the content window fullscreen on your non-primay
screen when:
• connecting a second screen,
• extending your desktop to a second screen that was mirroring your main screen,
• when starting pympress on a two-screen display. To disable this behaviour, untick “Content
fullscreen” under the “Starting configuration” menu.
• Estimated talk time: Click the Time estimation box and set your planned talk duration. The color will
allow you to see at a glance how much time you have left.
• Adjust screen centering: If your slides' form factor doesn't fit the projectors' and you don't want the
slide centered in the window, use the "Screen Center" option in the "Presentation" menu.
• Resize Current/Next slide: You can drag the bar between both slides on the Presenter window to adjust
their relative sizes to your liking.
• Caching: For efficiency, Pympress caches rendered pages (up to 200 by default). If this is too memory
consuming for you, you can change this number in the configuration file.
• Configurability: Your preferences are saved in a configuration file, and many options are accessible
there directly. These include:
• Customisable key bindings (or shortcuts),
• Configurable layout of the presenter window, with 1 to 16 next slides preview
• and many more.
See the configuration file documentation for more details,
• Editable PDF annotations: Annotations can be added, removed, or changed, and the modified PDF files can
be saved
• Automatic next slide and looping
Command line arguments
• -h, --help: Shows a list of all command line arguments.
• -t mm[:ss], --talk-time=mm[:ss]: The estimated (intended) talk time in minutes and optionally seconds.
• -n position, --notes=position: Set the position of notes on the pdf page (none, left, right, top, or
bottom). Overrides the detection from the file.
• --log=level: Set level of verbosity in log file (DEBUG, INFO, WARNING, ERROR).
Media and autoplay
To enable media playback, you need to have either:
• Gstreamer installed (enabled by default), with its gtk plugin (libgstgtk) which is sometimes packaged
separately (e.g. as gst-plugin-gtk or gstreamer1.0-gtk3), and plugins gstreamer-good/-bad/-ugly based
on which codecs you need, or
• VLC installed (and the python-vlc module), with enabled = on under the [vlc] section of your config
file.
On macOS, issues with the gstreamer brew formula may require users to set GST_PLUGIN_SYSTEM_PATH
manually. For default homebrew configurations the value should be /opt/homebrew/lib/gstreamer-1.0/. Make
sure to set this environmental variable globally, or pympress might not pick it up.
To produce PDFs with media inclusion, the ideal method is to use beamer’s multimedia package, always with
\movie:
\documentclass{beamer}
\usepackage{multimedia}
\begin{frame}{Just a mp4 here}
\centering
\movie[width=0.3\textwidth]{\includegraphics[width=0.9\textwidth]{frame1.png}}{movie.mp4}
\movie[width=0.3\textwidth]{}{animation.gif}
\movie[width=0.3\textwidth]{}{ding.ogg}
\end{frame}
If you desire autoplay, ensure you have pympress ≥ 1.7.0 and poppler ≥ 21.04, and use the movie15 package
as follows:
\documentclass{beamer}
\usepackage{movie15}
\begin{document}
\begin{frame}
\begin{center}
\includemovie[attach=false,autoplay,text={%
\includegraphics{files/mailto.png}%
}]{0.4\linewidth}{0.3\linewidth}{files/random.mpg}
\end{center}
\end{frame}
\end{document}
Contributing
Feel free to clone this repo and use it, modify it, redistribute it, etc, under the GPLv2+. A number of
contributors <https://github.com/Cimbali/pympress/graphs/contributors> have taken part in the development
of pympress and submitted pull requests to improve it.
Be respectful of everyone and keep this community friendly, welcoming, and harrasment-free. Abusive
behaviour will not be tolerated, and can be reported by email at me@cimba.li − wrongdoers may be
permanently banned.
Pympress has inline sphinx documentation (Google style <http://www.sphinx-
doc.org/en/latest/ext/example_google.html>, contains rst syntax), and the docs generated from it are
hosted on the github pages of this repo <https://pympress.github.io/>.
Translations
• Chinese (simplified)
• Chinese (traditional)
• Czech
• Hindi
• Italian
• Japanese
• Polish
• French
• German
• Spanish
We thank the many contributors of translations: Agnieszka, atsuyaw, Cherrywoods, Dongwang, Estel-f, Fabio
Pagnotta, Ferdinand Fichtner, Frederik. blome, FriedrichFröbel, GM, He. yifan. xs, Jaroslav Svoboda,
Jeertmans, Kristýna, lazycat, Leonvincenterd, LogCreative, Lorenzo. pacchiardi, Luis Sibaja, Marcin
Dohnalik, marquitul, Morfit, Mzn, Nico, Ogawa, Paul, Pierre BERTHOU, polaksta, Saulpierotti, Shebangmed,
Stanisław Polak, susobaco, Tapia, Tejas, Timo Zhang, Tkoyama010, Toton95, Vojta Netrh, Vulpeculus, and
Cimbali.
If you also want to add or contribute to a translation, check pympress’ page on POEditor
<https://poeditor.com/join/project/nKfRxeN8pS>. Note that old strings are kept and tagged removed, to
give context and keep continuity between translations of succcessive versions. This means removed
strings are unused and do not need translating.
Configuration file
Pympress has a number of options available from its configuration file.
This file is usually located in:
• ~/.config/pympress on Linux,
• %APPDATA%/pympress.ini on Windows,
• ~/Library/Preferences/pympress on macOS,
• in the top-level of the pympress install directory for portable installations.
The path to the currently used configuration file can be checked in the Help > About information window.
Shortcuts
The shortcuts are parsed using Gtk.accelerator_parse() <https://lazka.github.io/pgi-
docs/#Gtk-3.0/functions.html#Gtk.accelerator_parse>:
The format looks like “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is for key
release).
The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>”
and “<Ctrl>”. Key names are parsed using Gdk.keyval_from_name() <https://lazka.github.io/pgi-
docs/#Gdk-3.0/functions.html#Gdk.keyval_from_name>. For character keys the name is not the symbol, but
the lowercase name, e.g. one would use “<Ctrl>minus” instead of “<Ctrl>-”.
This means that any value in this list of key constants <https://lazka.github.io/pgi-
docs/#Gdk-3.0/constants.html#Gdk.KEY_0> is valid (removing the initial Gdk.KEY_ part). You can verify
that this value is parsed correctly from the Help > Shortcuts information window.
Layouts
The panes (current slide, next slide, notes, annotations, etc.) can be rearranged arbitrarily by setting
the entries of the layout section in the configuration file. Here are a couple examples of layouts, with
Cu the current slide, No the notes half of the slide, Nx the next slide:
• All-horizontal layout:
+----+----+----+
| Cu | No | Nx |
+----+----+----+
Setting:
notes = {"children": ["current", "notes", "next"], "proportions": [0.33, 0.33, 0.33], "orientation": "horizontal", "resizeable": true}
• All-vertical layout:
+----+
| Cu |
+----+
| No |
+----+
| Nx |
+----+
Setting:
notes = {"children": ["current", "notes", "next"], "proportions": [0.33, 0.33, 0.33], "orientation": "vertical", "resizeable": true}
• Vertical layout with horizontally divided top pane:
+----+----+
| Cu | No |
+----+----+
| Nx |
+---------+
Setting:
notes = {"children": [
{"children": ["current", "notes"], "proportions": [0.5, 0.5], "orientation": "horizontal", "resizeable": true},
"next"
], "proportions": [0.5, 0.5], "orientation": "vertical", "resizeable": true}
• Horizontal layout with horizontally divided right pane:
+----+----+
| | Nx |
+ Cu +----+
| | No |
+---------+
Setting:
notes = {"children": [
"current",
{"children": ["next", "notes"], "proportions": [0.5, 0.5], "orientation": "vertical", "resizeable": true}
], "proportions": [0.5, 0.5], "orientation": "horizontal", "resizeable": true}
And so on. You can play with the items, their nesting, their order, and the orientation in which a set of
widgets appears.
For each entry the widgets (strings that are leaves of "children" nodes in this representation) must be:
• for notes: "current", "notes", "next"
• for plain: "current", "next" and "annotations" (the annotations widget is toggled with the A key by
default)
• for highlight: same as plain with "highlight" instead of "current"
A few further remarks:
• If you set "resizeable" to false, the panes won’t be resizeable dynamically with a handle in the middle
• "proportions" are normalized, and saved on exit if you resize panes during the execution. If you set
them to 4 and 1, the panes will be 4 / (4 + 1) = 20% and 1 / (4 + 1) = 100%, so the ini will contain
something like 0.2 and 0.8 after executing pympress.
Themes on Windows
Pympress uses the default Gtk theme of your system, which makes it easy to change on many OSs either
globally via your Gtk preferences or per application <https://www.linuxuprising.com/2019/10/how-to-use-
different-gtk-3-theme-for.html>. Here’s the way to do it on windows:
1. Install a theme
There are 2 locations, either install the theme for all your gtk apps, e.g. in
C:\Users\%USERNAME%\AppData\Local\themes, or just for pympress, so in %INSTALLDIR%\share\themes (for
me that’s C:\Users\%USERNAME%\AppData\Local\Programs\pympress\share\themes)
Basically pick a theme e.g. from this list of dark themes <https://www.gnome-
look.org/browse/cat/135/ord/rating/?tag=dark> and make sure to unpack it in the selected directory, it
needs at least %THEMENAME%\gtk-3.0\gtk.css and %THEMENAME%\index.theme, where THEMENAME is the name of
the theme.
There are 2 pitfalls to be aware of, to properly install a theme:
• themes that are not self-contained (relying on re-using css from default linux themes that you might
not have), and
• linux links (files under gtk-3.0/ that point to a directory above and that need to be replaced by a
directory containing the contents of the target directory that has the same name as the link file).
2. Set the theme as default
Create a settings.ini file, either under C:\Users\%USERNAME%\AppData\Local\gtk-3.0 (global setting) or
%INSTALLDIR%\etc\gtk-3.0 (just pympress) and set the contents:
[Settings]
gtk-theme-name=THEMENAME
In testing this found these 2 stackoverflow questions useful:
• Change GTK+3 look on Windows <https://stackoverflow.com/a/39041558/1387346> which contains a list of
all interesting directories
• How to get native windows decorations on GTK3 on Windows 7+ and MSYS2
<https://stackoverflow.com/a/37060369/1387346> which details the process
AUTHOR
Cimbali
COPYRIGHT
2009-2011, Thomas Jost; 2015-2023 Cimbali
1.8.5 31 December, 2024 PYMPRESS(1)