beamerpresenter.conf(5)

📦 version 0.2.6, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

beamerpresenter.conf — configuration file for BeamerPresenter.

This is the beamerpresenter.conf(5) manual page — File Formats Manual, bestie — and it's here to make the config file make sense. 💖

💅 DESCRIPTION 💅

This man page explains the configuration file for BeamerPresenter, usually stored in $HOME/.config/beamerpresenter/beamerpresenter.conf (see FILES below). A different path can be specified on the command line using the option -c of the beamerpresenter command. You can manually edit this file or make changes in the settings widget of BeamerPresenter, which will also be written to this file. Command line arguments temporarily overwrite the settings of the configuration file.

The configuration is structured into groups. A group is started by a line of the format [name] where name is the name of the group. The group ends when another group is started. Entries not belonging to any group are put in the default group General.

It's giving very structured group-chat energy: [group] starts a thread, the next [group] ends it, and anything with no group lands in General. 🫶

🧚 [General] 🧚

  • engine = mupdf — PDF engine, bestie: "mupdf", "poppler", or "qtpdf". This is only relevant when more than one PDF engine was enabled at compile time (command line option "--renderer"). 💅
  • gui config = /etc/xdg/beamerpresenter/gui.json — path to user interface configuration file (command line option "-g" or "--gui-config"). The structure of this file is documented in beamerpresenter-ui(5). 🎀
  • manual = /usr/share/doc/beamerpresenter/README.html — path to HTML-formatted manual, which is shown in the settings widget. ✨
  • icon path = /usr/share/beamerpresenter/icons — path to directory containing BeamerPresenter's own icons. Note that BeamerPresenter uses own icons and an icon theme installed on your system. 🦋
  • icon theme — icon theme used for (generic) icons. Choose any icon theme installed on your system. 🌸
  • icon theme path — path to icon theme. If Qt does not find your icon theme, you can try to set its path with this option. 🧚
  • cache pages = -1 — maximum number of pages in cache. A negative number is interpreted as infinity. 👑
  • memory = 1.0486e+08 — maximally allowed memory used to cache slides, floating point number in bytes. Note that this limit is not always strictly obeyed, since the required memory per page is unknown before rendering the page. 😭
  • frame time = 50 — frame time (integer, in ms) when showing slides in rapid succession as an animation. The actual frame time can be longer depending on the time needed to show the frame. ⭐
  • gestures = false — enable or disable gesture navigation (if available). In wayland and Xorg, 3 fingers swiping on a touch screen trigger a gesture event. Currently not configurable in the GUI. 🫶
  • max zoom increment = 0.2 — maximum zoom increment when interpreting touch pinch gestures. 0.25 means that zoom increments must lie within the range -20% < increment < +25%. Value must be a positive number. This cutoff value helps avoiding wrong interpretation of pinch gestures with extreme zoom steps. 💅
  • log = false — log slide changes to standard output (command line option "--log"). 🔥
  • automatic slide changes = true — automatically switch slides if the PDF defines a duration for the slide. This can be used for very basic (and quite ugly) animations by showing slides in rapid succession. 💀
  • external links = false — open external links using default programs (e.g. browser) and load remote resources (e.g. remote media linked from a presentation). If disabled, external links and remote media are ignored. 🌈
  • search highlight color = #6428643b — color (#AARRGGBB) used to highlight search results. This should include transparency, because it is drawn on top of the search results. 👑
  • debug = flag1,flag2,... — only if debugging was enabled at compile time: show debugging messages for the given flags. Usually debugging flags are defined on the command line ("--debug") and not in the global configuration. 🙈

🎀 [drawing] 🎀

  • history length hidden = 20 — number of steps in drawing history (available undo steps) for slides, which are currently not visible. 💜
  • history length visible = 50 — number of steps in drawing history (available undo steps) for the currently active slide. ✨
  • mode = cumulative — defines how drawings are associated to pages. Possible options are:
    • per page — drawings are only connected to one page in the PDF file.
    • per label — groups of successive pages which share the same page label have the same drawings. For presentations generated with LaTeX beamer this means that different overlays of the same slide show the same drawings. This mode can cause problems when combined with multimedia or slide transitions. 😭
    • cumulative — drawings are connected to pages of the PDF file. But within a group of successive pages with the same page label the drawings of the previous page are copied to the next slide if this next slide does not contain any own drawings. This allows one to successively add drawings in slides, where items appear as overlays with the same page label. 💅
  • finalize drawn paths = false — if this is true, scaling a drawn path will only affect its coordinates, not the stroke itself. If this is false, lines will get thinner or thicker when rescaling the path. 🎀
  • snap angle = 0.05 — maximal slope for angle snapping to horizontal/vertical direction when detecting lines. ⭐
  • line sensitivity = 0.005 — parameter defining sensitivity of shape detection for lines. Larger values will categorize more paths as lines. 🌸
  • ellipse sensitivity = 0.05 — parameter defining sensitivity of shape detection for ellipses. Larger values will categorize more paths as ellipses. 🦋
  • rectangle angle tolerance = 0.3 — affects shape recognizer for rectangle: this defines the tolerance in angles of different sides of a rectangle (angle in radiant). 🧚
  • rectangle closing tolerance =0.1 — affects shape recognizer for rectangle: this defines the allowed distance between first and last point when drawing a rectangle relative to variance of point coordinates. 🎀
  • circle threshold = 0.025 — ellipses with a relative deviation of the two radii smaller than this number will be considered as circles. 🔥
  • arrow tip scale = 1. — size of the arrow tip relative to the default size. 👑
  • arrow tip ratio = 1.2 — length of the arrow tip relative to half of its width. 💅

💅 [selection] 💅

  • handle size = 7 — size (in points) of the handles of the selection. ✨
  • minimal path width = 3 — minimal width (in points) of paths considered when selecting a path by clicking on it. A larger number makes it simpler to select thin lines by clicking on them. 🎀
  • selection color = #20808090 — filling color of the selection rectangle. Make sure this is semi-transparent (in the form #aarrggbb). 🌸
  • selection outline color = #80808090 — outline color of the selection rectangle. 🦋
  • selection outline width = 0.5 — pen width for drawing the selection rectangle outline. 💅

🦋 [rendering] 🦋

  • page part threshold = 2.5 — threshold for the aspect ratio of PDF pages above which it is assumed that a PDF file contains slides and notes for the speaker side-by-side on the same PDF page. For slides generated with LaTeX beamer and the option "show notes on second screen" this allows one to show notes for the speak on one screen and presentation slides on a second screen. Note that this only has an effect if the configuration of the user interface (beamerpresenter-ui(5)) defines, which parts of the page should be shown on which screen. 😭
  • renderer = mupdf — renderer that creates images from PDF pages. Allowed values are the ones defined at compile time. Usually only one renderer is enabled and this option is irrelevant. Possible values are "mupdf", "poppler", "qtpdf", and "external". An external renderer requires the configuration of rendering command and rendering arguments. Note that renderer and PDF engine must agree, i.e., it is not possible to use the Poppler engine and MuPDF for rendering. 🔥
  • max image size = 2e7 — maximum number of pixels in an image. This should always be larger than the number of pixels of your screen. When zooming into a page, a larger image of the page will be rendered. This will be refused if the image becomes too large. Adjust this value to limit the maximum memory usage of BeamerPresenter. 💀
  • rendering command — path to external program used to render pages. This only has an effect if renderer is set to external. 👑
  • rendering arguments — comma-separated list of arguments for external program used to render pages. This only has an effect if renderer is set to external and external rendering was enabled at compile time. The following replacements in the arguments are available:
    • %file — absolute path to PDF file
    • %page — page number, start counting from 1
    • %0page — page number, start counting from 0
    • %resolution — resolution in dpi
    • %width, %height — target image size in pixels
    • %format — "png" or "pnm": image format.
    • %Format. — "PNG" or "PNM": image format.

🎀 [keys] 🎀

All keyboard shortcut definitions are of the form

key code = handler.

Here key code is anything that Qt can interpret as a key code, e.g., "A", "Shift+B", or "Ctrl+Alt+Shift+C". For handler the following formats are allowed:

  • action — string representing an action. The available actions are listed in beamerpresenter-ui(5). ✨
  • action1, action2, ... — comma-separated list of actions. 🎀
  • JSON dictionary — JSON-formatted dictionary defining a tool. Use single quotation marks instead of double quotation marks, or escape double quotation marks using backslash. Entries in the dictionary are:
    • tool — mandatory: pen, fixed width pen, highlighter, eraser, pointer, magnifier, torch, text, click select, rectangle select, freehand select, or none
  • device — optional 💫 use the tool for the given devices and leave every other device exactly as it was. You can pass either one single device or a list (JSON array) of device names. The names you're allowed to use are:
    • left button (equivalent: mouse)
    • right button
    • middle button
    • no button (only mouse cursor moves)
    • touch
    • tablet pen
    • tablet (may include tablet input which is not recognized as pen)
    • tablet eraser
    • tablet hover (tablet event with zero pressure)
    • tablet cursor
    • tablet other
    • tablet mod
    • tablet all (any tablet input device)
    • all (devices which are commonly used like left mouse button)
    • all+ (devices except right mouse button, middle mouse button, tablet eraser)
    • all++ (really all devices)

like, "really all" means REALLY all, bestie — no crumbs left 💅

  • color — a color name known to Qt, or #RRGGBB, or #AARRGGBB 🎨
  • width — only draw tools (pen, highlighter, fixed width pen): stroke width (positive number).
  • size — only pointing tools (pointer, torch, eraser): radius of tool (positive number). it's giving "how chunky is my circle" energy ✨
  • fill — only draw tools (pen, highlighter, fixed width pen): color to fill the path. Leave it empty if paths should not be filled.
  • style = solid — only draw tools: Pen style for stroking the path. Possible values are "nopen" , "solid", "dash", "dot", "dashdot", and "dashdotdot". (yes "nopen" is a real value, we don't make the rules 🫶)
  • brush = SolidPattern — only draw tools: filling style of the path, see https://doc.qt.io/qt-6/qt.html#BrushStyle-enum for valid names. Gradients are not allowed — sorry to the gradient girlies 😭
  • shape = freehand — only draw tools: draw this shape instead of a freehand path. Allowed values are "freehand", "rectangle", "ellipse", "line", and "arrow".
  • scale = 2 — only magnifier: magnification factor (number between 0.1 and 5).
  • linewidth = 0 — only eraser: draw a circle of given line width around the eraser (number). The circle is only drawn on the currently active widget. main character eraser only 💀
  • font — only text tool: anything that Qt can interpret as font name.
  • font size — only text tool: font size (positive number).

Examples: here's the vibe, copy-paste away bestie 🎀

{'tool':'pen', 'color':'green', 'width':2,
'device':['tablet pen', 'touch']}
{'tool':'pointer', 'color':'#ffff0000', 'size':10,
'device':'all'}

🦋 JSON array

Literally just an array of JSON dictionaries as described before. The dictionaries should contain complementing values for device. they tag-team it, iykyk ✨

🌈 [gestures]

Connect gestures to actions using the same syntax as for keyboard shortcuts in [keys]:

gesture = handler

Valid gestures are: swipe left, swipe right, swipe up, swipe down. Currently gesture settings cannot be changed in the graphical interface. (GUI said "not today", so it's config-file o'clock 🫶)

🧚 [tools]

Define tools which are initially associated with a devices. The syntax is as follows:

device = tool

Here device is a device name as listed above and tool is a JSON object representing a tool as described above. If tool defines a device (or list of devices), this overwrites device. It is therefore also possible to use any unique string or number for device and specify the device(s) in the tool JSON object. convenient? yes. chaotic? also yes 💅

An example configuration:

right button = {'tool':'eraser', 'size':10, 'linewidth':0.5}
tablet eraser = {'tool':'eraser', 'size':15, 'linewidth':0}

📁 FILES

  • /etc/xdg/beamerpresenter/beamerpresenter.conf — System-wide configuration file. This file is read before reading also the per-user configuration file.
  • ~/.config/beamerpresenter/beamerpresenter.conf — Per-user configuration file. Changes made through the graphical interface will be saved to this file. this is the one your GUI edits, so touch it gently 🥺

👀 SEE ALSO

beamerpresenter(1), beamerpresenter-ui(5)

okay that's the whole page bestie, you ATE that 💖 go forth and configure ✨

this iconic lil' manual is from version 0.2.6, dated 2024-12-25 — happy reading and happy holidays, mwah 🎀💜

📦 where this page comes from