Convert Figma logo to code with AI

Cimbali logopympress

Pympress is a simple yet powerful PDF reader designed for dual-screen presentations

1,143
88
1,143
30
View on GitHub

Top Related Projects

pdfpc's avatar

pdfpc

1,539

A presenter console with multi-monitor support for PDF files.

Gogh-Co's avatar

Gogh

9,152

Gogh is a collection of color schemes for various terminal emulators, including Gnome Terminal, Pantheon Terminal, Tilix, and XFCE4 Terminal also compatible with iTerm on macOS.

jaspervdj's avatar

patat

2,403

Terminal-based presentations using Pandoc

Quick Overview

Pympress is a PDF viewer and presenter application designed for use with dual-screen setups, such as a laptop and a projector. It provides a simple and intuitive interface for presenting PDF documents, with features like presenter view, annotations, and remote control.

Pros

  • Dual-Screen Support: Pympress is specifically designed to work with dual-screen setups, allowing presenters to view their notes and slides separately on different screens.
  • Presenter View: The application provides a dedicated presenter view, which displays the current slide, upcoming slides, and presenter notes on the secondary screen.
  • Annotations: Users can add annotations, such as highlights and drawings, directly on the PDF slides during the presentation.
  • Remote Control: Pympress supports remote control functionality, allowing presenters to control the presentation from a mobile device or another computer.

Cons

  • Limited File Format Support: Pympress is primarily focused on PDF files and may not support other document formats, such as PowerPoint or Keynote.
  • Steep Learning Curve: The application may have a steeper learning curve compared to more mainstream presentation software, especially for users unfamiliar with dual-screen setups.
  • Dependency on External Libraries: Pympress relies on several external libraries, which may require additional setup and configuration.
  • Lack of Advanced Presentation Features: While Pympress provides basic presentation features, it may lack some of the more advanced capabilities found in other presentation software.

Code Examples

Pympress is a Python-based application, and here are a few examples of how to use it:

  1. Opening a PDF File:
import pympress

# Create a Pympress instance
app = pympress.Pympress()

# Open a PDF file
app.open_file("path/to/your/presentation.pdf")
  1. Adding Annotations:
# Get the current slide
slide = app.get_current_slide()

# Add a highlight annotation
slide.add_highlight(x1, y1, x2, y2)

# Add a drawing annotation
slide.add_drawing(x1, y1, x2, y2)
  1. Controlling the Presentation:
# Go to the next slide
app.next_slide()

# Go to the previous slide
app.prev_slide()

# Toggle the presenter view
app.toggle_presenter_view()
  1. Enabling Remote Control:
# Start the remote control server
app.start_remote_control()

# Connect to the remote control server from another device
app.connect_to_remote_control("192.168.1.100")

Getting Started

To get started with Pympress, follow these steps:

  1. Install the required dependencies:

    • Python 3.x
    • PyQt5 or PySide2
    • Poppler-Qt5 (for PDF rendering)

  2. Install Pympress using pip:

    pip install pympress

  3. Launch the Pympress application:

    pympress

  4. Open a PDF file by clicking the "Open" button or using the "Ctrl+O" shortcut.

  5. Customize the presentation settings, such as the presenter view and annotations, using the available options in the Pympress interface.

  6. If you want to use the remote control feature, start the remote control server and connect to it from another device using the provided options.

For more detailed instructions and configuration options, please refer to the Pympress documentation: https://github.com/Cimbali/pympress.

Competitor Comparisons

pdfpc logo

pdfpc

1,539

A presenter console with multi-monitor support for PDF files.

Pros of pdfpc

  • Written in C, potentially offering better performance for resource-intensive operations
  • More mature project with a larger user base and longer development history
  • Supports multi-monitor setups natively, ideal for professional presentations

Cons of pdfpc

  • Limited cross-platform compatibility (primarily Linux-focused)
  • Steeper learning curve due to more complex features and configuration options
  • Requires compilation, which may be challenging for non-technical users

Code Comparison

pdfpc (C):

static void pdfpc_window_set_cache_surface(PdfpcWindow *self, cairo_surface_t *surface) {
    if (self->cache_surface != NULL) {
        cairo_surface_destroy(self->cache_surface);
    }
    self->cache_surface = cairo_surface_reference(surface);
}

pympress (Python):

def set_cache_surface(self, surface):
    if self.cache_surface:
        self.cache_surface.finish()
    self.cache_surface = surface

Both code snippets demonstrate setting a cache surface, but pdfpc uses C with Cairo graphics library, while pympress uses Python, showcasing the language difference between the two projects.

Gogh-Co logo

Gogh

9,152

Gogh is a collection of color schemes for various terminal emulators, including Gnome Terminal, Pantheon Terminal, Tilix, and XFCE4 Terminal also compatible with iTerm on macOS.

Pros of Gogh

  • Focuses on terminal color schemes, offering a wide variety of pre-configured themes
  • Supports multiple terminal emulators across different operating systems
  • Active community with frequent updates and contributions

Cons of Gogh

  • Limited to terminal theming, lacking presentation-specific features
  • May require more technical knowledge to install and configure
  • Does not provide PDF viewing or slide management capabilities

Code Comparison

Gogh (theme installation):

bash -c "$(curl -sLo- https://git.io/vQgMr)"

pympress (basic usage):

from pympress import Document
doc = Document('presentation.pdf')
doc.start_presentation()

Summary

Gogh is a specialized tool for terminal theming, offering a vast collection of color schemes for various terminal emulators. It's ideal for users who want to customize their terminal appearance across different platforms. On the other hand, pympress is a PDF presentation tool with features specifically designed for giving presentations, including dual-screen support and a presenter console. While Gogh enhances the terminal experience, pympress focuses on streamlining the presentation process for speakers.

jaspervdj logo

patat

2,403

Terminal-based presentations using Pandoc

Pros of patat

  • Written in Haskell, offering a lightweight and efficient command-line tool
  • Supports multiple markup formats including Markdown, reStructuredText, and AsciiDoc
  • Provides live reloading of presentations, enhancing the editing experience

Cons of patat

  • Limited to terminal-based presentations, lacking graphical interface options
  • Fewer built-in theming and customization options compared to pympress
  • May have a steeper learning curve for users unfamiliar with terminal-based tools

Code Comparison

patat (Haskell):

main :: IO ()
main = do
    opts <- execParser optsInfo
    runPatat opts

pympress (Python):

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('pdf_file', help='The PDF file to read')
    args = parser.parse_args()
    Pympress(args.pdf_file).run()

Both projects use command-line arguments for input, but patat's implementation is more concise due to Haskell's functional nature. pympress focuses on PDF files, while patat supports multiple markup formats directly.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Pympress logo 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, on his repo.

Here is what the 2 screen setup looks like, with a big notes slide next to 2 small slides (current and next) on the presenter side: A screenshot with Pympress’ 2 screens

Installing github version badge

  • Ubuntu ubuntu logo 20.04 focal or newer, Debian debian logo 11 Bullseye or newer ubuntu version badge debian version badge (maintained by @mans0954)

    apt-get install pympress libgtk-3-0 libpoppler-glib8 libcairo2 python3-gi python3-gi-cairo gobject-introspection libgirepository-1.0-1 gir1.2-gtk-3.0 gir1.2-poppler-0.18

  • RPM-based Linux (Fedora fedora logo CentOS centos logo Mageia mageia logo OpenSuse suse logo RHEL) Copr build version

    You can get pympress from the pympress COPR repo of your system. With yum or dnf, simply do:

    dnf copr enable cimbali/pympress
dnf install python3-pympress

    With zypper, fetch the link of the .repo in the table at the bottom of the COPR page and add it as a source.

    zypper addrepo https://copr.fedorainfracloud.org/coprs/cimbali/pympress/repo/opensuse-tumbleweed/cimbali-pympress-opensuse-tumbleweed.repo
zypper install python3-pympress

  • Arch Linux arch linux logo from AUR AUR version badge (maintained by @Jose1711)

    git clone https://aur.archlinux.org/python-pympress.git
cd python-pympress
makepkg -si

    Or using any other tool to manage AUR packages (yay, pacaur, etc.):

    yay -S python-pympress

  • macOS apple logo using Homebrew homebrew version badge

    brew install pympress

    Or using MacPorts macport version badge

    port install pympress

  • Windows windows logo with Chocolatey chocolatey version badge (maintained by @ComFreek)

    choco install pympress

    Or using the Windows Package Manager (winget) winget version badge

    winget install pympress

    Or download the latest installer from the latest Github release.

    Troubleshooting
    • If you get an error message along the lines of "MSVCP100.dll is missing", get the Visual C++ 2010 redistributables from Microsoft (x86 (32 bit) or x64 (64 bits)). Those libraries really should already be installed on your system.

  • Other systems, directly from PyPI pypi version badge − requires python, gtk+3, poppler, and their python bindings:

    pipx install --system-site-packages "pympress"
    Troubleshooting

    • Make sure you have all the dependencies. (These are already included in binary packages or their dependencies.)

    • If your python environment lacks the Gobject Introspections module, try

      1. using --system-site-packages for pipx or virtual environments,
      2. installing pygobject and pycairo with pipx (pipx inject pympress pygobject pycairo), which requires the correct development/header packages be present on your system. See the PyPI installation instructions of PyGObject for your system.

    • As per the python documentation on installing, it is recommended to install packages in virtual environments. Since mid 2022, the pipx tool automates this process. Your distribution (or Homebrew on macOS) should have a version you can install. Alternately, you can get the same effect with the standard venv and pip modules:

      # Create virtual environment
python3 -m venv --system-site-packages ~/.local/lib/venv/pympress
# Install pympress
~/.local/lib/venv/pympress/bin/python3 -m pip install pympress
# Link to the executable from a place in your path
ln -s ~/.local/lib/venv/pympress/bin/pympress ~/.local/bin/

      Note that:

      • If you don’t want to use system packages, you can build and install pygobject/pycairo in the virtual environment using ~/.local/lib/venv/bin/pip install pygobject pycairo
      • You can adjust the ~/.local/lib/venv/ path to your personal preference.

    • Unfortunately, installing pympress in a virtual environment means you will not get desktop integration (i.e. installing pympress' desktop and png files to have pympress show up in your menus etc).

      This is by design, as desktop applications are intended to be installed through system packages (rpm, apt, etc.). You can work around this in 2 ways:

      1. Manually (note that links/copied files will need to be removed): 
        cp "`pipx environment -V PIPX_LOCAL_VENVS`/pympress/share/applications/io.github.pympress.desktop" ~/.share/applications/
ln -s "`pipx environment -V PIPX_LOCAL_VENVS`/pympress/share/pixmaps/pympress.png" ~/.share/pixmaps/
      2. Relying on the deprecated data_files, that only work outside of virtual environments. This means installing with pip: 
        python3 -m pip install --user --break-system-packages pympress

Notes

To support playing embedded videos in the PDFs, your system must have VLC installed (with the same bitness as pympress). VLC is not distributed with pympress, but it is certainly available in your system’s package manager and on their website.

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-primary 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, bottom, or after). 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}

Dependencies

Pympress relies on:

  • Python (version ≥ 3.4, python 2.7 is supported only until pympress 1.5.1, and 3.x < 3.4 until v1.6.4).
  • Poppler, the PDF rendering library.
  • Gtk+ 3, a toolkit for creating graphical user interfaces, and its dependencies, specifically:
    • Cairo (and python bindings for cairo), the graphics library which is used to pre-render and draw over PDF pages.
    • Gdk, a lower-level graphics library to handle icons.
  • PyGi, the python bindings for Gtk+3. PyGi is also known as pygobject3, just pygobject or python3-gi.
    • Introspection bindings for poppler may be shipped separately, ensure you have those as well (typelib-1_0-Poppler-0_18 on OpenSUSE, gir1.2-poppler-0.18 on Ubuntu)
  • optionally VLC, to play videos (with the same bitness as Python) and the python-vlc bindings.
  • optionally Gstreamer to play videos (which is a Gtk library)

On linux platforms

The dependencies are often installed by default, or easily available through your package or software manager. For example, on ubuntu, you can run the following as root to make sure you have all the prerequisites assuming you use python3:

apt-get install python3 python3-pip libgtk-3-0 libpoppler-glib8 libcairo2 python3-gi python3-cairo python3-gi-cairo gobject-introspection libgirepository-1.0-1 libgirepository1.0-dev gir1.2-gtk-3.0 gir1.2-poppler-0.18

Different distributions might have different package naming conventions, for example the equivalent on OpenSUSE would be:

zypper install python3 python3-pip libgtk-3-0 libpoppler-glib8 libcairo2 python3-gobject python3-gobject-Gdk python3-cairo python3-gobject-cairo typelib-1_0-GdkPixbuf-2_0 typelib-1_0-Gtk-3_0 typelib-1_0-Poppler-0_18

On CentOS/RHEL/Fedora the dependencies would be:

yum install python36 python3-pip gtk3 poppler-glib cairo gdk-pixbuf2 python3-gobject python3-cairo

And on Arch Linux:

pacman -S --needed python python-pip gtk3 poppler cairo gobject-introspection poppler-glib python-gobject gst-plugin-gtk

On macOS

Dependencies can be installed using Homebrew:

brew install --only-dependencies pympress

On windows

The binary installer for windows comes with pympress and all its dependencies packaged.

Alternately, in order to install from pypi or from source on windows, there are two ways to get the dependencies:

  1. using MSYS2 (replace x86_64 with i686 if you're using a 32 bit machine).

    Warning: this can take a substantial amount of disk size as it requires a full software distribution and building platform.

    pacman -S --needed mingw-w64-x86_64-gtk3 mingw-w64-x86_64-cairo mingw-w64-x86_64-poppler mingw-w64-x86_64-python3 mingw-w64-x86_64-vlc python3-pip mingw-w64-x86_64-python3-pip mingw-w64-x86_64-python3-gobject mingw-w64-x86_64-python3-cairo

    This is also the strategy used to automate builds on appveyor.

  2. Using PyGobjectWin32. Be sure to check the supported Python versions (up to 3.4 at the time of writing), they appear in the FEATURES list in the linked page.

  • Install native python for windows
  • Get GTK+3, Poppler and their python bindings by executing the PyGi installer. Be sure to tick all the necessary dependencies in the installer (Poppler, Cairo, Gdk-Pixbuf).

Alternately, you can build your Gtk+3 stack from source using MSVC, see the Gnome wiki and this python script that compiles the whole Gtk+3 stack. This strategy has not been used successfully yet, due to problems building Poppler with its introspection bindings (i.e. typelib) − see #109.

Contributing

Feel free to clone this repo and use it, modify it, redistribute it, etc, under the GPLv2+. A number of 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 harassment-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, contains rst syntax), and the docs generated from it are hosted on the github pages of this repo.

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. Note that old strings are kept and tagged removed, to give context and keep continuity between translations of successive versions. This means removed strings are unused and do not need translating.

Packages

Official releases are made to PyPI and with github releases. The community maintains a number of other packages or recipes to install pympress (see Install section). Any additions welcome.