IMPRESSIVE(1)

📦
version 0.13.2 · 3 versions
, in fedora 43, fedora 44, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

💖 IMPRESSIVE(1) 💖

okay bestie, you clicked into the manual page for Impressive and honestly? you're about to have a great time. this is IMPRESSIVE(1), the whole thing, and i'm gonna walk you through every single flag like we're texting at 2am. buckle up. 🎀

✨ NAME ✨

Impressive — presentation tool with eye candy 💅

🦋 SYNOPSIS 🦋

impressive [OPTIONS...] FILES...

🌸 DESCRIPTION 🌸

so like, Impressive is a simple presentation program that displays slideshows of PDF documents, image files or video files. that's the whole vibe. and the rendering? done via OpenGL, which is literally where the "eye candy" effects come from. it's giving ✨glow up✨ for your slides.

but bestie, listen — you need a somewhat-modern GPU (that's graphics processing unit, iykyk) that supports OpenGL 2.0 or OpenGL ES 2.0, plus the appropriate drivers, or Impressive simply will not run. no cap. 💀

👑 OPTIONS 👑

okay this is the part everyone actually came for. every flag, no skipping, let's go. 🫶

  • -a <seconds> / --auto <seconds> — auto-advances to the next page after however many seconds you give it. pair it with the -w option (talked about further down) and boom, you've got yourself an automatic slideshow, main character energy fr fr.
heads up though: this option will not interrupt video playback. if a video runs longer than the interval you set with --auto, the video plays all the way to the end, and Impressive switches to the next page directly after that. no cutting off mid-video, periodt.
  • -A <X>:<Y> / --aspect <X>:<Y> — sets the display aspect ratio. normally Impressive just assumes the pixel aspect ratio is 1:1 (square pixels), regardless of whatever display resolution got set up. so if the resolution you picked doesn't match the display's actual aspect ratio, your screen will look distorted 😭. this option fixes that by letting you set it manually, e.g. "-A 16:9".
ngl, this option has no effect if the MuPDF backend is doing the rendering.
  • -b / --noback — turns off background rendering. by default, Impressive pre-renders all pages in a separate background thread while the presentation is running. with this flag, it renders all pages immediately on startup instead.
this one also does nothing if caching is disabled (--cache none, see below). just so you know. 🙈
  • --background <color> — sets the background color of the overview page and the page border that shows up when the page's and the screen's aspect ratios don't match. the color uses HTML/CSS 3-digit or 6-digit hexadecimal RGB syntax: #f00 or #ff0000 is bright red, for example. the leading hash sign (#) is optional. and bonus — the words black (which is also the default) and white are recognized too. 🎨
  • -bare — disables all functionality that relies on temporary files. specifically: video frame extraction using MPlayer (extracting video frames with FFmpeg still works, thank god), PDF page title extraction, PDF hyperlinks, and even PDF rendering for all backends except MuPDF 1.4 or newer on Unix-like operating systems. it's the "no temp files allowed" era. 💀
  • --box-edge <pixels> — sets the border size (in pixels when unzoomed) of the highlight boxes' and spotlight's smooth edges. default is 4 pixels, and you can set it to zero — in which case highlight boxes and the spotlight get hard edges instead. sharp. 🔥
  • -B <ms> / --boxfade <ms> — sets the duration (in milliseconds) of the highlight box fade-in/fade-out animation. default value: 100 ms. smooth like butter ✨
  • -c <mode> / --cache <mode> — picks which page cache mode to use. the valid options are:
    • none — disables page caching altogether; only the current and the following page stay in RAM. jumping between pages will be very slow, because Impressive has to render the requested pages on the fly. also, the overview page won't be complete until every page has been shown at least once. 😭
    • memory — caches all page images in memory. this is the fastest method, but it needs very large amounts of memory (about 3 MiB per page at 1024x768 resolution).
    • compressed or z — caches all page images in memory too, but in compressed form. a little slower than memory mode, but on pages with uniform backgrounds it easily reduces the required RAM by a factor of 20. iconic honestly. 👑
    • disk — like memory, but uses a temporary file rather than memory for storage. this is the default.
    • persistent — uses a permanent cache file for caching. this file is not deleted when Impressive quits and gets reused on subsequent invocations. the default name for the cache file is derived like the names for Info Scripts (see below for an explanation), but with a .cache file name extension instead of .info. a little slower than disk mode, but the time span until the overview page is fully populated drops significantly if you run Impressive again with the same input files and options. 🎀
and here's the cute part: the mode name may be abbreviated at will, down to one character. so --cache persistent, -c persist and even -cp are all synonyms. slay. 💅
  • -C <filename>[:<X>,<Y>] / --cursor <filename>[:<X>,<Y>] — lets you specify an image to use as a (software) mouse cursor instead of the normal (hardware) one. it can be either the name of an image file (typically a transparent .png) or one of the special values "-" (dash) or "default" — both of which select a built-in cursor image. on platforms that don't support a hardware cursor, this default cursor is also used as a default if you don't use this option at all. if you specify an external file, you can also set the position of the hotspot — that's the pixel inside the cursor where the actual mouse position lives. for example: --cursor mycursor.png:2,4. 🖱️
  • --clock — when enabled, the current time is shown instead of the elapsed time, if time display is activated (with the T key in the default control configuration). compatible with the -M option. ⏰
  • --control-help — outputs a short help screen showing how the control configuration (keyboard and mouse bindings) works, along with a list of all recognized events and actions and a dump of the current bindings (which is the default configuration if no other -e/--bind or -E/--controls options precede this option).
after that, Impressive exits. no presentation will be started. it's just here to help, bestie. 🫶
  • -d <time> / --duration <time> — specifies the expected run time of the presentation. the time parameter can be either a number of seconds or a human-readable time like 1:23 (1 minute and 23 seconds), 4:56h (4 hours and 56 minutes), 3m45s (3 minutes and 45 seconds), 5m (5 minutes) or 1:23:45 (1 hour, 23 minutes and 45 seconds). if you give an expected duration, Impressive shows a semi-transparent green progress bar at the bottom edge of the screen, showing how much time has already passed. and when the time is up? the bar occupies the whole edge and fades to yellow (at 125% of the expected time) to red (at 150% or more). dramatic and honestly deserved. 😭
  • -D <ms> / --mousedelay <ms> — sets the time (in milliseconds) the mouse cursor stays visible if it isn't moved. there are two special values: 0 (zero) shows the mouse cursor permanently, and 1 (one) hides it completely. default is 3000 ms if Impressive starts in fullscreen mode, and 0 (i.e. don't hide) if it starts in windowed mode. 🙈
  • --darkness <percentage> — how much darker the screen gets when you use highlight boxes or spotlight mode. value is in percent, and 25 is the default. a value of zero means no darkening at all (the screen just gets blurred slightly, and desaturated if the graphics hardware supports it), and 100 makes everything except the highlighted parts of the screen black. 🖤
  • -e <bindings> / --bind <bindings> — configures keyboard or mouse bindings. for the syntax of the argument, go check the Control Configuration section of the manual. iykyk. 💅
  • -E <filename> / --controls <filename> — loads a configuration file for keyboard and mouse bindings. for the syntax of these files, again, refer to the Control Configuration section of the manual. 📄
  • --evtest — with this one, Impressive does not start a normal presentation. instead it enters the so-called "Event Test Mode" after the display has been initialized. in this mode, Impressive just captures all keyboard and mouse events and displays the name of the last event on the screen. plus, events get logged to standard output. this mode helps you figure out the event names for each key when you're building a custom control configuration (see the Control Configuration section). super useful fr fr. 🔍
  • -f — sets the window/fullscreen mode Impressive starts up with. this option can be specified multiple times; each time it's found, the next of the three options is selected, in this order:
    1. True fullscreen mode, including setting the video mode. this is the default mode.
    2. Windowed mode, where Impressive runs in a standard window.
    3. "Fake-fullscreen" mode, where fullscreen is emulated by using a window without a border that fills the whole screen. setting the display resolution is not possible in this mode. each of these modes has a corresponding long option that enables it directly: --fullscreen, --windowed and --fake-fullscreen. 🪟
  • --fullscreen — starts Impressive in fullscreen mode (the default). see the discussion of the -f option for details. 🖥️
  • --fake-fullscreen — starts Impressive in "fake fullscreen" mode. see the discussion of the -f option for details. 🦋
  • -F <file> / --font <file> — okay so Impressive uses some kind of text OSD to slap the current page number and title (if there is one) onto the overview page ✨, and this option is how you pick a TrueType font file (.ttf) for that OSD. If the path you give doesn't point straight at a useable font file, Impressive goes hunting through the system font directories. For that it assumes every font lives under /usr/share/fonts, /usr/local/share/fonts or /usr/X11R6/lib/X11/fonts/TTF (that last one is specifically handy for Mac OS X systems 🍎). Don't specify this option at all? Then it defaults to either DejaVuSans.ttf or Vera.ttf (that's the typical filename of Bitstream Vera Sans, iykyk 💅).
  • -g <width>x<height>[+<posX>+<posY>] / --geometry <width>x<height>[+<posX>+<posY>] — sets the screen size or resolution Impressive is gonna use, in pixels 🌈. If xrandr is installed, the default screen size for fullscreen mode is just the current screen resolution; on other platforms, Impressive grabs the highest resolution available to the graphics system. And if a standard resolution can't be figured out at all, the default is 1024x768 pixels. That's also the default for windowed mode, fr fr. ALSO — if you add the extra posX and posY params, they set the position of the window's upper-left corner (relative to the upper-left corner of the desktop), in pixels, for windowed and fake-fullscreen mode 🪟. Those values are ignored in "true" fullscreen mode though, so don't @ them.
  • -G <gamma>[:<blacklevel>] / --gamma <gamma>[:<blacklevel>] — sets up the startup gamma and the optional black level value 🌗. The black level is the original image's intensity level (0...254) that gets mapped to black in Impressive's output. Heads up bestie: gamma and black level adjustments may be unavailable or constrained on some systems, so it's giving "depends on your hardware" energy 😭.
  • -h / --help — if you throw this one in, Impressive writes a short command line help screen to standard output and does not start a presentation. Just vibes and instructions 🫶.
  • -H / --half-screen — this makes Impressive show the overview page and the OSD elements on the right half of the screen only. The overview page will only show the left half of the slides as previews, and the box-zoom boxes also get shown on the left half 👑. With a multi-monitor setup on a wide virtual screen and specially crafted slides (like the ones you can generate with LaTeX's beamer class), this makes it possible to have presenter's notes on the second screen — main character setup honestly 💅. Note that transitions and animations are still operating on the whole screen, which makes some of them (like PagePeel) look ugly 😭. Impressive also disables the overview zoom animation in half-screen mode; you can re-enable it by explicitly setting it to another value with a later command line option (--zoomtime). Another limitation: the allocation of the screen halves (slides left, overview right) is fixed.
  • -i <page> / --initialpage <page> — tells it which page number to start with 🎀. Default value is 1 (start with the first page). If you specify another value, the page shown by Impressive right after initialization is not the first one of the PDF or image list. And bonus: pre-rendering (if it's enabled) will also start at the page you specified ⭐.
  • -I <filename> / --script <filename> — overrides the automatic derivation of the info script filename and lets you specify a script file directly 🦋.
  • --invert — makes Impressive invert the colors of every page, turning black to white and vice-versa 🌈. But note it's a full RGB inversion, so it will, for example, turn dark green to light purple (and vice-versa) too. Chaotic and iconic.
  • -k / --auto-progress — makes Impressive show a progress bar visualizing the timeout on pages that have one (either specified as a page property or via the --auto command-line option) ⏳. Nothing happens on pages that don't have a timeout. And if the --duration or --page-progress bars are enabled too, the --auto-progress bar gets shown on the top of the screen; otherwise it's shown on the bottom.
  • -l / --listtrans — if specified, Impressive writes a list of all available transition classes to standard output and does not start a presentation 💜. Transitions that are enabled by default are marked with a star (*) to the left of the class name ⭐.
  • -L <spec> / --layout <spec> — specifies the OSD layout 🎀. Read below for an explanation of this option (yes, it's a whole thing).
  • --maxzoom <factor> — the maximum zoom factor up to which Impressive shall attempt to render a high-resolution image of the page when zoomed in 🔍. This can be any real number larger than or equal to 1.0; the default is 5.0. A setting of 1.0 causes Impressive to never render a high-resolution image for zooming; in that case, the zoom and box-zoom modes will upscale the image, but not enhance any details. Note that regardless of this setting, Impressive always checks the graphics hardware capabilities (in particular, the maximum supported texture size) and may reduce the effective value of --maxzoom if the hardware supports less than what you specified 💀.
  • --min-box-size <pixels> — sets the minimum size of a highlight box, in pixels 📏. Boxes that are not this many pixels wide and high are rejected, to prevent accidental creation of highlight boxes (we love a safety feature 🙈). The default value for this is 30 pixels.
  • -M / --minutes — if set, Impressive shows the on-screen timer (activated with the T key) only with 1 minute resolution ⏱️. By default, it shows a timer with 1 second resolution.
  • --noblur — by default, Impressive uses a fragment shader to blur and desaturate the image when in highlight box or spotlight mode ✨. This is usually the faster and nicer-looking method; however, some very old hardware implementations can't deal with that shader and fall back to an unusably slow software implementation 😭. Impressive tries to detect scenarios where this would happen and automatically falls back to a different implementation. There might be situations where this mechanism fails and Impressive tries to use the non-functional shader anyway. In these cases, --noblur can be used to enforce the fallback implementation 🫶.
  • -N / --nocursor — disables any display of a mouse cursor, i.e. neither the system ("hardware") nor bitmap ("software") cursor is shown at any time 🙈. It's equivalent to setting --mousedelay to 1. This is mainly useful for automated presentations, where no mouse interaction is needed.
  • --noclicks — if enabled, switching to the previous or next page with the left and right mouse buttons is deactivated 🖱️🚫. The keyboard shortcuts are unaffected by this. Note that this option only works as intended when the default controls are used. If the -e/--bind or -E/--controls options have been used, --noclicks might not have the intended effect 💀.
  • --nologo — disables the Impressive logo and version number display 🎀. Instead, the loading screen will be just black or, if background rendering is disabled, only the progress bar will be visible.
  • --nooverview — disables the overview page entirely 🚫. Overview thumbnails are not created, and the Tab that normally enters overview mode is ignored. (More precisely, the overview-enter action is ignored.)
  • --noquit — disables the keyboard shortcuts (Q and Esc) that could normally quit Impressive with a single keypress 🙅. If it's used, the only way to exit the program is the key combination Alt+F4, and accidental quitting is no longer possible. Note that this option only works properly if the default controls are used. If the -e/--bind or -E/--controls options have been used, --noquit might not have the intended effect 💀.
  • -o <directory> / --output <directory> — don't display the presentation at all, just render it into a series of PNG image files inside the specified directory 🖼️. The images will be generated in the current resolution as specified by the -g option. This is useful if the presentation is to be given on a foreign PC with an old, broken or otherwise problematic MuPDF/Xpdf/GhostScript installation: by generating images of the PDF pages, it's made sure that no rendering bugs will happen on the target system 🔥.
  • -O <mode> / --autooverview <mode> — enables or disables automatic derivation of whether a page shall or shall not be shown on the overview page 👀. This feature is based on the fact that some LaTeX presentation packages tag all pages with a title (that can be read by Impressive with the help of pdftk), except those that contain multiple reveal steps. The following modes are available:
    • off — disables automatic overview mode. All pages will be shown on the overview page by default. This is also the default setting.
    • first — all pages with a PDF title will be shown on the overview page. The purpose is to show the initial state of multi-step slides on the overview page.
    • last — all pages before a page with a PDF title will be shown on the overview page. The purpose is to show the final state of multi-step slides on the overview page.

Again, the mode may be abbreviated arbitrarily, down to one character, just like with the -c option above..

  • --overtime <ms> — sets the duration (in milliseconds) of the overview page zoom-in/zoom-out effects, without affecting the zoom or box-zoom animation time ⏱️✨. Default value: 250 ms.
  • -p <start>-<end>, --pages <start>-<end> — okay so bestie, you can narrow down which pages actually show up. The presentation kicks off at the first page of the range, and every page outside it is not on the overview page and not cached. That said, you can still manually land on them while cycling through. The catch? Since they're uncached, prepping the display takes considerably longer. 💀
  • -P <path>, --gspath <path> — this one lets you override the Xpdf / GhostScript path autodetection. You gotta give it the full path to the executable of either GhostScript (gs or gs.exe) or Xpdf's pdftoppm utility. No vibes-based guessing, the full path, periodt. 💅
  • -q, --page-progress — turn this on and Impressive blesses you with a light-blue semi-transparent progress bar chillin' at the bottom edge of the screen. It shows your position in the presentation, aka the relation between the current page number and the total number of pages. And if the -d/--duration progress bar is enabled too, the --page-progress bar gets stacked above it. Layered looks, we love. ✨
  • --progress-last <number> — sets the page number where the --page-progress progress bar should end. Super handy for ignoring backup slides (iykyk). 🫶 Heads up though: this option does nothing if -q/--page-progress isn't being used.
  • -Q, --autoquit — with this, Impressive dips out automatically when you try to navigate to the page after the last page, or the page before the first page. Main character exits only. 👑 But: no effect if --wrap is used.
  • -r <n>, --rotate <n> — rotates all pages by *n*x90 degrees clockwise. If you're having problems with PDFs generated by LaTeX on some Xpdf or GhostScript versions, try -r 1 or -r 3. 🌈
  • -s, --scale (image input only) — so if a directory of image files is your input, Impressive will scale down images that are too big for the screen. But by default it will not scale up smaller images to fit — it leaves a black border instead. This option overrides that and enables upscaling of smaller images. Glow-up mode, activated. ✨
  • -s, --supersample (PDF input only) — yes bestie, -s shows up twice with different meanings, that's just how it is 💀. This switch enables antialiasing by 4x supersampling instead of the normal multisampling method used by Xpdf or GhostScript. It usually degrades both visual quality and performance, ngl — but it may be necessary for circumventing white strips or moire-like patterns in gradients. Trade-offs, fr fr.
  • -S <pixels>, --fontsize <pixels> — sets the size, in pixels, of the OSD font. Default value is 14.
  • --spot-radius <pixels> — sets the initial radius of the spotlight, in pixels. Default value is 64. 🔦
  • --time-display — enables display of the elapsed presentation time, exactly as if the T key had been pressed immediately after startup. This implies time tracking mode (the --tracking option). Clocked in. ⏰
  • -t <trans1[,trans2...]>, --transition <trans1[,trans2...]> — here you specify the set of transitions Impressive will randomly draw at page changes. If you give it only one transition class, that class gets used for all pages that don't have another transition explicitly assigned in their page properties. Multiple transitions gotta be separated by commas; they'll be used in random order. And bestie, the -l option can get you a list of available transitions. 🎀
  • -T <ms>, --transtime <ms> — sets the duration (in milliseconds) of page transitions. 0 (zero) disables transitions altogether. Default value: 1000 ms.
  • --tracking — enables time tracking mode. In this mode, a report of all pages visited — with their display duration, enter and leave times — gets written to standard output. This is genuinely so useful when preparing presentations. 📊
  • -u <seconds>, --poll <seconds> — with this, the source file or directory gets checked for changes regularly. If a change in the input PDF file, or any of the image files in the input image directory, is detected, the page cache gets flushed and the current page as well as the info script get reloaded. The current page's transition will be shown between the old and the new version of the page. 🦋 Requirements though: the new PDF file must have at least as much pages as the old one, and it should have the same aspect ratio. If the input is a directory, image files must not have disappeared.
  • -v, --verbose — makes Impressive more verbose, i.e. it prints slightly more informational messages than usual. Chatty king. 💬
  • -V <pixels>, --overscan <pixels> — PDF files often come with tiny amounts of white borders around the edges, which look bad in screen presentations, ngl. To eliminate this, Impressive uses "overscan": PDF files won't be rendered to fit the screen size exactly, but a bit larger so that the (possibly broken) borders can be cropped off. You set the amount of overscan, in screen pixels, with this option. Default is 3 pixels, which should remove borders in most presentations at most common screen resolutions without cropping the pages too much. ✂️
  • -w, --wrap — with this set, Impressive will "wrap" over to the first page after the last page. In other words, advancing to the next page at the end of the presentation restarts the whole thing. Round and round we go. 🔁
  • -W, --nowheel — by default it's possible to change pages using the mouse wheel. This option disables that behavior, which is useful to prevent spurious page changes if the mouse wheel is likely to be moved by accident. Bonus: it also makes it possible to enter zoom mode with the mouse wheel. 🖱️
Heads up bestie: this option only works properly if the default controls are used. If the -e/--bind or -E/--controls options have been used, --nowheel might not have the intended effect.
  • --windowed — starts Impressive in windowed mode. See the discussion of the -f option for details.
  • -x, --fade — enables a smooth fade-in effect at the start of the presentation and a fade-out effect just before Impressive quits. Cinematic. 🎬
  • -X, --shuffle — if enabled, the input files get shuffled into random order before the presentation starts. The individual pages of PDF input files stay in their original order though, so this option is mainly useful for image presentations. Chaos, but organized chaos. 🔀
  • -y, --auto-auto — use this together with --duration to have Impressive compute a page timeout (as with the --auto option) automatically. The result? A presentation that runs automatically, displaying each slide for the same time, so that the desired total duration gets reached (almost) exactly. One exception: the runtime of videos, which is not taken into account. ⏱️
  • --zbox-edge <pixels> — sets the border size (in pixels when unzoomed) of the box-zoom boxes' smooth edges. Default is 1 pixel; you can set it to zero, in which case the box-zoom area will have a hard edge. Soft or sharp, your call. 🌸
  • -z <factor>, --zoom <factor> — sets the scaling factor used in zoom mode. It can be any real value above 1.0; the default value is 2.0. Note that it might not be possible to get high-quality zooming for large zoom factors due to hardware restrictions. Also, please be aware: after leaving zoom mode, the image quality of the normal page display may be slightly degraded until another page is displayed, if a zoom factor other than 2.0 is used. 🔍
  • --zoomdarkness <percentage> — specifies how much the non-selected parts of the screen shall become darker in box-zoom mode. The value is in percent, with 90 being the default. A value of zero means no darkening at all (parts outside of the zoom box would still be perfectly visible), and a value of 100 would make everything but the selected region black. 🌑
  • -Z <ms>, --zoomtime <ms> — sets the duration (in milliseconds) of the zoom, box-zoom and overview page zoom-in/zoom-out effects, all at once. Default value: 250 ms. If you want separate animation time settings for overview zoom and zoom/box-zoom, the -Z/--zoomtime option must be specified before the --overtime option. Order matters, bestie. 💅
  • --cachefile <filename> — activates persistent cache mode and specifies the name of the cache file to use. 💾

🌈 ARGUMENTS 🌈

Following the options, the input file name(s) must be specified. No input, no show. 🎤

Recognized file types are:

  • PDF
  • image files (JPEG, PNG, TIFF, BMP, PGM/PPM)
  • video files (AVI, MOV/MP4, MKV/WebM, OGV, MPEG, M2TS, FLV)

If the name of a directory is put on the command line, all recognized image files (no PDF files!) in this directory will be played in alphanumeric order (case-insensitive). So alphabetical besties only. 🔤

In addition, Impressive can use a text file containing a list of files or directories to show. This text file must contain at most one file name per line; every character after a hash sign (#) is treated as a comment and will be ignored. And plot twist: if such a comment is put on the same line as an image file name, it will be used as the page's title. ✨

List file names must be prefixed with an at sign (@) on the command line, like:

impressive @my_list_file

Impressive will also expand wild-card characters (* and ?) if this isn't already done by the shell, but apart from that, it will not reorder the arguments. So it shows the documents in the order specified at the command line. You control the lineup. 🎀

If video files are specified on the command line, Impressive generates presentation pages for them just like it does for image files. If FFmpeg or MPlayer are installed, the page will be shown as a screenshot of the first video frame. 🎥 When entering such a page, the video will be played back if a suitable player (MPlayer, or omxplayer on Raspberry Pi) is installed. 🍓

✨ LAYOUT OPTIONS ✨

okay bestie this is where it gets fun 💅 the OSD layout option (-L/--layout) takes a string made of comma-separated key=value pairs. Here's the whole menu of keywords it recognizes:

  • alpha — how see-through the OSD text is. You can give it as a floating-point value between 0 and 1, or as a percentage between 2 and 100. (yes, 1 but not 100%-equivalent 1%, the numbers are just Like That, don't @ me 🫶)
  • margin — the distance, in pixels, between the OSD text and the screen borders.
  • time — where the timer sits.
  • title — where the page title sits in overview mode.
  • page — where the page number sits in overview mode.
  • status — where the status line sits.

now the position specs, and this is the part that lowkey slaps once you get it ✨ each one is exactly two characters: the first tells you whether the text is displayed at the top (T) or bottom (B) edge of the screen, and the second tells you whether it appears on the left (L), on the right (R) or centered (C). Two letters. Top/bottom then left/right/center. That's the whole code, no cap 🔥

so like, for example, the default OSD layout equals this option string right here:

-L margin=16,alpha=1,time=TR,title=BL,page=BR,status=TL

timer top-right, title bottom-left, page bottom-right, status top-left. iconic arrangement honestly 👑

🌈 EXAMPLES 🌈

here are some typical command lines so you can see the vibes in action ✨ these all assume Impressive can be run by just typing impressive on the command line. Depending on how Impressive is installed, you have to swap that out for the actual way to run it — like python ~/impressive/impressive_dev.py if you're working from a fresh SVN checkout 🧚 and also, demo.pdf is standing in for the document to show here, so obviously replace that with the path to your actual PDF too. housekeeping, bestie, gotta do it 💖

the simplest case: just hand Impressive the name of the file and no further parameters. Boom. Full-screen presentation, every setting at its defaults:

impressive demo.pdf

just wanna peek at a deck real quick? then a small window instead of full-screen makes sense. Something like this:

impressive -f -g 800x600 demo.pdf

digital signage era 👑 like displays in shop windows running a permanent slideshow? You can do that by having Impressive auto-advance to the next page after a set time (say 10 seconds) and restart the presentation from the start once the last slide is done:

impressive -a 10 -w demo.pdf

💜 USAGE 💜

okay so on startup, Impressive shows you a black screen with the program logo chillin' at the center. If caching is enabled but background rendering is disabled, all pages of the presentation get rendered once, right then. A bar in the lower half of the screen shows you the progress of that operation, like a little loading moment but make it aesthetic 📊

Any key or mouse click skips this process — except for the ones that quit Impressive, typically Q and Esc (those will absolutely still quit, don't play yourself 😭). Skipping means Impressive will render the remaining pages on demand instead.

⚠️ heads up: the overview page will not be complete until every page has been rendered at least once. So if you skipped the precaching process, you'll get placeholders for all the pages that haven't been rendered yet. no thoughts, just gray boxes 🙈

By default though? Impressive builds up the cache in the background while the presentation runs. So the progress bar won't even appear, and the preparation only takes the amount of time required to render the first two pages of the presentation. Then, after this initialization process, Impressive switches to the first page directly and without any transition — no fade, no wipe, just there ✨ periodt.

okay bestie, so here's the tea ☕ — literally almost every keyboard and mouse control in Impressive is configurable (with like, a very few exceptions, iykyk). But out of the box, this is the default lineup, and it's lowkey iconic:

  • Esc key — bails you out of whatever special mode is currently vibing (zoom, box-zoom, overview, spotlight, highlight boxes). But if none of those modes is active? It just quits Impressive entirely. main character exit 💅
  • Q key or Alt+F4 — yeets you out of Impressive immediately. no transition, no goodbye, just gone 🫶
  • LMB (left mouse button), mouse wheel down, Page Down key, Cursor Down key, Cursor Right key or Spacebar — next page, bestie. With a transition and everything ✨
  • RMB (right mouse button), mouse wheel up, Page Up key, Cursor Up key, Cursor Left key or Backspace key — previous page. Again, with a transition, because we're classy 🌸
  • Home key / End key — teleports you straight to the very first or the very last page of the presentation. no stops, no small talk 🦋
  • Ctrl key (modifier) — okay so if you hold Ctrl while pressing any of the page navigation keys (Page Up/Page Down, Cursor keys, Space, Backspace, Home, End), the destination page gets entered immediately — no transition. straight in, no in-between 🎀
  • L key — takes you back to the last page (as in, the most recently displayed one). This is the toggle-back-and-forth-between-two-pages hack, and it's genuinely so useful 😭
  • F key — toggle fullscreen mode. yes queen, go big 🔥
  • Tab key — zooms back to the overview page. While you're in overview mode, you can pick a page with the mouse and activate it with the left mouse button. The right or middle mouse button, or the Tab key again, leaves overview mode without changing the current page. polite king behavior 👑
  • MMB (middle mouse button) — in normal display mode this acts exactly like the Tab key: zoom back to the overview page. And if the page is already zoomed in? It returns you to normal mode instead 🌈
  • LMB over a PDF hyperlink — jumps to the page the hyperlink points at. Two types of hyperlinks are supported: links that point to some other page of the same document, and URL hyperlinks like Web links and e-mail addresses. Heads up though — this whole feature only works if pdftk is installed. And on top of that, xdg-open from the freedesktop.org Portland project is required for URL links to actually work. Also please note: the hyperlink feature will not work properly when pages are rotated. so rude 💀
  • click&drag with LMB (left mouse button) — creates a new highlight box. And while at least one highlight box is defined on the current page, the page itself gets shown in a darker, blurry, and (if your graphics hardware supports it) desaturated rendition. Only the highlight boxes are displayed in their original lightness, sharpness and color saturation. And if you leave a page that has highlight boxes, the boxes get saved and restored the next time that page is shown again. obsessed ✨
  • click&drag with Ctrl+LMB (left mouse button) — draws a box to zoom into. This enters the so-called "box-zoom" mode, where the region you selected gets zoomed into full view and everything else is shown in much darker colors (but not blurred like in highlight box mode, okay?). The page contents get re-rendered in a higher resolution, if possible — limited to whatever you configured with the --maxzoom command-line option, and the graphics hardware's maximum supported texture size. To leave this mode again, use RMB, MMB or Esc.
Note that box-zoom mode is mutually exclusive with highlight boxes and the spotlight. If any of those is currently active, you literally cannot draw a zoom box. it's giving ✨exclusive✨
  • RMB (right mouse button) over a highlight box — if you right-click while the mouse cursor is above a highlight box, that box gets removed. And if the last box on a page is removed, the page turns bright and sharp again. clean slate energy 🧚
  • A key — toggles automatic slideshow mode.

If an automatic presentation was already started with the -a/--auto option, it gets temporarily disabled until you press this key again. It is not automatically re-enabled after changing the page. And if -a/--auto hasn't been used, then pressing this key for the first time starts an automatic presentation with a timeout of 30 seconds.

Note that if a page has a timeout PageProp, the specified timeout is always in effect when the page is entered, even if the automatic slideshow is otherwise disabled. yeah, always. periodt 💅
  • S key — saves the info script associated with the current presentation. The main purpose here is to permanently save highlight boxes or keyboard shortcuts, so they'll be restored the next time this presentation is started. save your work bestie 😭
  • T key — activates or deactivates the time display in the upper-right corner of the screen. And if the timer gets activated while the very first page of the presentation is shown, it activates time tracking mode — just as if you'd specified the --tracking command-line option 🕐
  • R key — resets the presentation timer. fresh start 🌸
  • C key — removes ("clears") all highlight boxes from the current page. bye bye boxes 👋
  • Return key or Enter key — toggles spotlight mode. In this mode the page gets darkened the same way as if highlight boxes were present, but instead of (or in addition to) the boxes, a circular "spotlight" shows up around your mouse cursor position and follows every single motion of the cursor. literal main character spotlight 👑
  • + / - key, 9 / 0 key or mouse wheel in spotlight mode — adjust the spotlight radius. make it big, make it small, live your truth 🎀
  • Ctrl+9 or Ctrl+0 keys — resets the spotlight radius to the default value, i.e. the value that's been set up by the radius page property, the --spot-radius command-line option, or Impressive's built-in default 🦋
  • 7 / 8 key — adjusts how much darkening gets applied to the page in spotlight, highlight box or box-zoom mode. mood lighting, but make it a presentation 💅
  • Ctrl+7 or Ctrl+8 keys — resets the amount of darkening in spotlight, highlight box and box-zoom mode back to the default values, i.e. the value that's been set up by the darkness and zoomdarkness page properties, the --darkness and --zoomdarkness command-line options, or Impressive's built-in defaults ✨
  • Z key — toggles zoom mode. When you first press it, the current page zooms in: it's displayed at double size, but in its original resolution (so yeah, it'll be blurry). Impressive will re-render the page at the new resolution if the graphics hardware supports it. During this time, Impressive will not accept any input — so don't even think about clicking the mouse or pressing keys before the image gets crisp again. wait for it bestie 🫶

In zoom mode, all the other functions work as normal. Any operations that leave the current page — like flipping the page or entering the overview screen — will leave zoom mode too.

  • [ / ] key — adjusts the gamma value of the display (might not be supported on every hardware, so don't come for me if it doesn't work) 🌈
  • { / } key — adjusts the black level of the display (again, might not be supported on every hardware) 🌈
  • \ key — reverts gamma and black level back to normal. factory reset vibes 🧚
  • O key — toggles the "visible on overview page" flag of the current page. The result won't be visible immediately, but it can be saved to the info script (using the S key) and will be in effect the next time the presentation is started. patience, bestie ⭐
  • I key — toggles the skip flag of the current page. A page marked as skipped won't be reachable with the normal forward/backward navigation keys. it's in time-out 💀
  • B / W key or . (dot) / , (comma) key — fade to black or white, respectively. This feature is here for when a whiteboard or blackboard in front of the projection area is gonna be used during the presentation — using these two keys, the screen fades into a solid color. On any keypress or mouse click, it fades back to normal. These keys are not available in overview mode 👑
  • click&drag with MMB (middle mouse button) or RMB (right mouse button) in zoom mode — moves the visible part of the page around while you're in zoom mode 🦋
  • mouse wheel up / down in zoom mode, U key — zooms a bit in or out. When zoomed out fully, zoom mode is left. Note that in the default configuration, this means that when you try to zoom out even more using the wheel, the page gets left instead. This is different if the -W/--nowheel option is used, where page navigation using the mouse wheel is disabled and the wheel is always used for zooming — and in that mode, the wheel can also be used to enter zoom mode in the first place.
Note that changing the zoom level on the fly with the wheel does not make Impressive automatically re-render the page at a higher resolution to increase the level of detail. To do that, the U key needs to be pressed manually once the desired zoom level has been set up. no shortcuts, literally 😭
  • Cursor keys in overview mode — navigate through pages. simple, clean, iconic ✨
  • Alt+Tab keys — if Impressive is in fullscreen mode, the window gets minimized so you can go use other applications. multitasking queen 💅
  • Any alphanumeric (A-z, 0-9) or function key (F1-F12) that is not bound to a specific action mentioned above or configured by the user (see below) — can be used to assign shortcuts to pages that require quick access. If one of those keys is pressed together with Shift, the currently displayed page gets associated with that key. To recall the page later, it's enough to just press the shortcut key again. And shortcuts can be stored permanently with the S key. personalized shortcuts? we love to see it 🎀

✨ CONTROL CONFIGURATION ✨

okay so remember how we said back in the last chapter that Impressive's keyboard and mouse bindings are super duper configurable? yeah. literally everything is up for grabs 💅 — with exactly two exceptions, and I need you to hear me on this:

  • Alt+F4 will always quit Impressive
  • Alt+Tab will always minimize Impressive

those two are hardcoded, no takebacks, no negotiation. everything else though? there's a whole versatile configuration system in place, and all those controls we talked about in the previous section are merely the defaults 🎀

the whole vibe of how it works 🧚

Impressive's control system works by associating events with actions. let's define our terms bestie:

  • an event is a key on the keyboard, a mouse button, or a mouse wheel movement 🖱️
  • an action is something Impressive actually does because of that event — going to the next page, switching to overview mode, quitting the program, that kinda thing
  • the association of an event to an action is called a binding 💖

now here's where it gets cute. multiple events can be bound to the same action (like the page down and space keys in the default setting — both of them just go to the next page, iconic). and ALSO, multiple actions can be bound to the same event. wild, right?

fr fr, bindings don't even associate events with single actions at all — they associate events with chains of actions. so when an event fires, only the first action in the chain that matches (i.e. that actually makes sense in the current context) gets executed. everything else in the chain? ignored. and if literally no action in the chain matches, then no action happens and the event just gets ignored. vibe check failed, moving on 💀

example time: the default binding for the left mouse button is a whole action chain. it draws a highlight box if the mouse cursor moved, or visits a hyperlink if the cursor hovers over one, or goes to the next page if none of the other conditions are met. one button, three possible outcomes. main character energy honestly 👑

names, case, and errors 🌸

both events and actions have mnemonic names that get used in the command-line options and config files when you're setting up bindings. these names are generally case-insensitive, though the canonical notation is lowercase (so like, lowercase is the aesthetic, but you do you boo).

if an event or action you specified on the command line or in a config file isn't recognized by Impressive, an error message gets written to the console and the offending event or action is simply ignored. errors in control configuration are always non-fatal. no crashes, no drama, we just move on 🫶

🌈 SUPPORTED EVENTS 🌈

keyboard events are generally named after the keys they refer to. easy enough. so:

  • the events a to z and 0 to 9 mean the respective letter and number keys on the main keyboard
  • f1 to f12 are the function keys
  • kp0 to kp9 are the number keys on the numerical keypad

but — and this is the important bit — all of these are raw scancodes, which has two implications:

  1. the key names are not internationalized and refer to the US keyboard layout. so for example, the Z key on a German or French keyboard will actually react to the event name y or w 😭
  2. modifiers are ignored as well. for example, the numerical keypad will always generate the kpX scancodes, even if Num Lock is off ✨

the mnemonic names for the other keyboard events are as follows, in alphabetic order:

ampersand, asterisk, at, backquote, backslash, backspace, break, capslock, caret, clear, comma, down, end, escape, euro, exclaim, greater, hash, help, home, insert, kp_divide, kp_enter, kp_equals, kp_minus, kp_multiply, kp_plus, lalt, last, lctrl, left, leftbracket, leftparen, less, lmeta, lshift, lsuper, menu, minus, mode, numlock, pagedown, pageup, pause, period, plus, power, print, question, quote, quotedbl, ralt, rctrl, return, right, rightbracket, rightparen, rmeta, rshift, rsuper, scrollock, semicolon, slash, space, sysreq, tab, underscore, up

the events prefixed with kp_ refer to keys on the numerical keypad, and other than that the names should be reasonably descriptive, so they won't be described further at this point. also note: not all keyboards and platforms support the full range of keys defined in this list. so if something doesn't work, it might just be your hardware, bestie, not you 🙈

mouse event names 🖱️💖

the mouse event names are mapped like this:

  • lmb — the left mouse button
  • mmb — the middle mouse button
  • rmb — the right mouse button
  • wheelup — scrolling the mouse wheel upwards
  • wheeldown — scrolling the mouse wheel downwards
  • btnX (i.e. btn6, btn7, ...) — additional mouse buttons, the mapping of which is device-specific; use --evtest to see which button is which 👀

modifiers, and the order that matters ⚠️

the event names can be prefixed with the three modifiers ctrl+, alt+ and shift+ to make the event valid only if the specified set of modifiers is pressed as well. this works for both keyboard and mouse events, so go off 💅

multiple modifiers can be combined — but the order must match the one mentioned in this paragraph. for example:

  • ctrl+shift+x is a valid event name ✅
  • shift+ctrl+x is not ❌
the order is ctrl+, then alt+, then shift+. memorize it. no cap.

how to find out what your event is called 🕵️‍♀️

a simple way to determine the name associated with an event is using Impressive's "Event Test Mode" by invoking:

impressive --evtest

in this mode, the name of each incoming event will be displayed on the screen (and logged to standard output), which makes it possible to determine event names by experimentation. it's giving science experiment but make it cute 🧪✨

✨ SUPPORTED ACTIONS ✨

Okay bestie, this is the master list of every action Impressive knows about, plus the exact conditions under which each one will actually fire. Important vibe check first: most of these actions will not match in overview mode or during video playback, unless the description specifically says otherwise. Read the fine print, it matters. 💅

  • auto-start — (Re-)enables automatic presentation mode. If the current page has no timeout PageProp and no -a/--auto option was given, an automatic presentation kicks off with a 30-second page interval.
  • auto-stop — Turns automatic presentation mode off. If the current page has a timeout PageProp or an -a/--auto option was specified, the timeout for the current page gets stopped. The automatic presentation stays disabled after you change pages, unless a timeout PageProp is specified for the target page — that takes precedence over the otherwise disabled automatic presentation mode.
  • auto-toggle — Disables or (re-)enables automatic presentations, depending on the current state. Iconic.
  • box-add — Draws a highlight box if the mouse has been moved since the button was pressed down. 🖱️ This action must only be bound to a mouse button event, otherwise it will not function properly.
  • box-clear — Removes all boxes from the current page.
  • box-remove — Removes the highlight box under the mouse cursor, if there is any.
  • box-zoom — Defines a region to zoom into by drawing a rectangle. This action must only be bound to a mouse button event, otherwise it will not function properly.
  • box-zoom-exit — If you're in box-zoom (but not normal zoom) mode, this leaves box-zoom mode.
  • fade-less, fade-more — Decrease or increase how much darkening gets applied to the background in spotlight or highlight box mode.
  • fade-reset — Resets the background darkness in spotlight or highlight box mode back to its default value.
  • fade-to-black, fade-to-white — Fades to a black or white screen. Once the screen is faded out, any event except those bound to the quit action will just leave fade mode and not perform its assigned action. periodt.
  • fullscreen — Toggles fullscreen mode on platforms that support it.
  • gamma-decrease, gamma-increase — Decrease or increase the gamma level (i.e. roughly the brightness) of the display, on platforms that support it.
  • gamma-bl-decrease, gamma-bl-increase — Decrease or increase the black level of the display, on platforms that support it.
  • gamma-reset — Resets the gamma and black level settings to their defaults. fresh start energy ✨
  • goto-end, goto-end-notrans — Go to the last page of the presentation, with or without a transition.
  • goto-last, goto-last-notrans — Go to the last (i.e. most recently) visited page, with or without a transition.
  • goto-next, goto-next-notrans — Go to the following page of the presentation, with or without a transition.
  • goto-prev, goto-prev-notrans — Go to the previous page of the presentation, with or without a transition.
  • goto-start, goto-start-notrans — Go to the first page of the presentation, with or without a transition.
  • hyperlink, hyperlink-notrans — Navigate to the hyperlink under the mouse cursor, if there is one. If that hyperlink points to another page of the presentation, that page gets activated with or without a transition. If the hyperlink refers to an external object (like an URL), it gets opened externally, if your system supports it.
  • overview-confirm — When you're in overview mode, this confirms the selection and leaves overview mode, navigating to the selected page.
  • overview-down, overview-up — When you're in overview mode, select the page above or below the currently selected one in the grid.
  • overview-enter — When you're not in overview mode, zoom out of the current page and enter overview mode.
  • overview-exit — When you're in overview mode, leave overview mode, zooming back to the page that was displayed before you entered overview mode.
  • overview-next, overview-prev — When you're in overview mode, select the following or previous page.
  • quit — Quits Impressive immediately. This action is available in all modes. (yes really, all of them 👑)
  • save — Save or update the Info Script for the current presentation.
  • spotlight-enter — If spotlight mode isn't active, enable spotlight mode.
  • spotlight-exit — If spotlight mode is active, deactivate spotlight mode.
  • spotlight-grow, spotlight-shrink — When you're in spotlight mode, increase or decrease the radius of the spotlight.
  • spotlight-reset — When you're in spotlight mode, reset the spotlight radius to the default value.
  • time-reset — Reset the presentation timer.
  • time-toggle — Toggle on-screen display of the current presentation time, or wall-clock time if the --clock option is used. If you do this at the start of the presentation, before the first page has been left, time tracking mode gets enabled, like the --tracking option would have done.
  • toggle-overview — This toggles the "page is visible on overview screen" flag for the current page. It won't have an immediate effect, but it can be saved to an Info Script.
  • toggle-skip — This toggles the "skip page when navigating with goto-prev and goto-next" flag for the current page.
  • video-pause — In video playback mode, this pauses or unpauses playback.
  • video-seek-backward-10, video-seek-backward-1, video-seek-forward-1, video-seek-forward-10 — In video playback mode, seek forward or backward by 1 or 10 seconds.
  • video-step — In video playback mode, if playback is paused, advance one frame in the video.
  • video-stop — In video playback mode, stop playback and return to normal page display mode.
  • zoom-enter — If you're not in zoom mode, enter zoom mode with the zoom level configured by the -z/--zoom option.
  • zoom-exit — If you're in zoom or box-zoom mode, leave that mode.
  • zoom-in, zoom-out — Slightly increase or decrease the current zoom level. This does not change the page's rendering resolution — it only zooms the visible part of the screen in or out, centered around the mouse cursor's position. Zoom mode is left automatically if the zoom level goes down to 1x; conversely, zoom mode gets entered when you call zoom-in while zoom mode isn't active.
  • zoom-pan — If you're in zoom mode, the visible area of the page can be moved around with the mouse while the key or mouse button of the associated event is held down.
  • zoom-update — If you're in zoom mode, re-render the current page in a resolution that best fits the current zoom level, up to the limits of the graphics hardware or the --maxzoom setting. You only need to do this explicitly when zooming with the zoom-in action; zoom-enter and box-zoom do this automatically.

🔧 BINDING SYNTAX 🔧

The arguments of the -e/--bind command-line option follow this basic syntax:

<event> [,<event2>...] <operator> <action> [,<action2>...]

So basically: a sequence of event names joined with commas, then an operator (see below), then a sequence of action names joined with commas. And yes, you can stack multiple binding statements into one argument by joining them with a semicolon (;). 💫

The operators (aka how your action list messes with those bindings)

  • = (equals sign), += (plus sign and equals sign) — The specified actions get added to the bindings of the specified events. In other words, event=action1,action2 does exactly the same as event=action1; event=action2.
  • := (colon and equals sign) — The specified actions replace the bindings of the specified events.
  • -= (minus sign and equals sign) — The specified actions get removed from the bindings of the specified events. For example, to make the Esc key in the default bindings not clear highlight boxes, but otherwise preserve its original functionality, you can use escape -= box-clear. chef's kiss 👨‍🍳💋

Special commands

Other than bindings, a statement can also contain one of these special commands:

  • clearall — Clears all current bindings.
  • defaults — Discards all current bindings and (re-)establishes the default bindings.
  • include <filename> — Loads and executes a control configuration file with the specified name.

Config files

The syntax for the configuration files used with the -E/--controls option or the include statement is exactly the same as for the ad-hoc configuration option, except that individual bindings can be written on individual lines instead of being joined together into one single long line with semicolons. Plus, everything following a hash sign (#) on a line gets ignored as a comment. 🙈

One practical example of such a config file: the author of this program uses a cheap presentation remote control device that has four cursor keys, one "enter" key, and a slider that switches between keyboard and mouse mode. Mouse mode works as expected, but what it does in keyboard mode is quite peculiar — the up and down keys act like Page-Up and Page-Down keys on a keyboard, the right arrow key sends the letter B to the computer, and the left key toggles between Esc and F5 each time it's pressed. This configuration file lets you do basic navigation and access overview mode with that device:

clearall  # don't use the default bindings
lmb = quit  # quit Impressive by clicking in mouse mode
# everything else uses keyboard mode:
return = overview-enter, overview-confirm  # toggle overview mode
escape, f5 = overview-prev, goto-prev
b = overview-next, goto-next
pageup = overview-up, goto-prev
pagedown = overview-down, goto-next

To get a better idea of how the control configuration system works in practice, it's recommended to study the output of impressive --control-help — this not only gives a concise overview of all events and actions, but also a full dump of Impressive's default bindings that you can use as a starting point for your own customizations. go off bestie 💖

✨ INFO SCRIPTS ✨

okay bestie, this is the fun part 🎀 Impressive has a genuinely powerful way to customize individual presentations, and it's called info scripts. lowkey iconic.

An info script is just a text file that has the same name as your presentation file and lives in the same directory as it, with one little extra suffix tacked on: .info. So if your presentation file is BrandNewProduct.pdf, its info script is named BrandNewProduct.pdf.info. cute, right? 💅

Now here's where it gets a lil ✨situational✨:

  • If you specified multiple arguments on the command line, the info script will just be called .info — yes, a dot file, so to speak 🙈
  • If a directory name was specified as the only argument, then either a file called DirectoryName.info or a file called .info inside the directory will be used — which one depends on whether a path separator was specified at the end of the directory name or not. Impressive literally just appends .info to whatever the input path name was. no cap.

In any case, the default file name can be overridden with the -I command line option. your file name, your rules 🫶

🐍 the tea on what these actually are

Info scripts are actually Python scripts with full access to Impressive's global data structures and functions. and when I say full access... I mean it. it is possible — though heavily discouraged — to write real interactive applications using info scripts 😭 like, entire apps. in an info script. bestie.

This has some good side effects and some bad side effects, so let's do the bad news first like the original does:

the bad news 💀 - The info scripts must be compatible with the Python version used by Impressive itself. it's best to write them in a way that's compatible with both Python 2.7 (with the __future__ imports print_function, unicode_literals and division) and Python 3.x. both. at the same time. yes really. - Furthermore, there's no built-in security. in other words: don't trust info scripts you received from somebody else. 🚨 like, at all. not even a little.
the good news 🌈 They can modify a broad range of settings concerning Impressive. that's a lot of power in a little .info file, ngl.

This manual will only cover the most basic ones, so consider this your starter pack ⭐ — the vibe is very much there's more where that came from.

✨ PAGE PROPERTIES ✨

okay bestie so the main character of any info script is literally the part that defines what each page is. here's every property you can set, no cap 💅

  • title — every page can have a title, and that title gets shown in the Impressive window's title bar 🎀 if you don't explicitly set one in the info script, Impressive will pull it from the PDF metadata (assuming pdftk is installed), or if your presentation is an image slideshow, it'll just use the image file name. iconic of it honestly.
  • transition — this is where you say which transition class to use for rendering the transition into this page (so: between the previous page and this one). pages that don't have this property get random transitions, which is lowkey chaotic but fun ✨ you can get the full list of available transition classes with impressive -l.
  • transtime — overrides the global transition time parameter (that's -T at the command line, iykyk). it's an integer, measured in milliseconds, for how long the transition to this page should take ⏱️
  • overview — boolean value (0/False or 1/True) that says whether this page should show up on the overview page. if you don't specify it, it's assumed to be True.
  • skip — another boolean. set it to 1/True and the page gets skipped during the presentation. here's the full vibe check on how overview and skip interact:
    • pages with overview:True, skip:False will be accessible both by cycling through the pages and using the overview page
    • pages with overview:True, skip:True will be silently skipped in the normal page cycle, but remain accessible from the overview page
    • pages with overview:False, skip:False will appear in the normal cycle, but not on the overview page
    • and pages with overview:False, skip:True will not be accessible at all 💀
  • next — set this to the number of the page that should be shown after this one. super handy for skipping a whole bunch of pages without slapping the skip property on every single one of them, or for creating a loop that you can only escape using the overview page or bookmarks 🌀
  • prev — set this to the number of the page that should be shown when you navigate from this page to the previous one (like with the right mouse button or the Page-Up key in the default mappings).
  • boxes — stores a list of highlight box coordinates. normally you do NOT need to edit this by hand bestie, because Impressive handles it automatically whenever you press the S key 🫶
  • timeout — if a timeout property is present and the page gets shown, Impressive will automatically switch to the next page after the specified number of milliseconds. normally the timeout only kicks in the first time the page is shown, unless wrap mode is active (that's the command-line option -w or --wrap). this restriction is what makes self-running presentations with individual per-page timeouts possible 🕐
  • radius — takes an integer value that, if defined, sets a new spotlight radius every single time the page is entered. this overrides whatever the current setting is from the --spot-radius command line option or any run-time adjustments. heads up though: the value is not reset to the default after you leave the page again.
  • darkness — takes an integer or floating-point percentage value that, if defined, sets the background darkness in spotlight or highlight box mode each time the page is entered. overrides the current setting from the --darkness command line option or run-time adjustments. and again — the value is not reset to the default after the page has been left.
  • zoomdarkness — same deal, takes an integer or floating-point percentage value that, if defined, sets the background darkness in box-zoom mode each time the page is entered. overrides the current setting from the --zoomdarkness command line option or run-time adjustments. and yes, the value is not reset to the default once the page is left. they all do this, it's a whole thing 🙈
  • comment — holds a string with a single line of text that gets displayed on screen while the page is shown. and no, you can't disable the display of this text. periodt.
  • sound — file name of a sound file to play (via MPlayer) when the page is first entered. once it starts, the sound plays until it reaches the end, until another sound or video is played, or until Impressive is exited 🎵
  • video — file name of a video file to play when the page is first entered. the video displays full-screen. any key or mouse click stops playback — except the cursor keys, which seek through the video file, and space, which pauses playback. also, please note this function is still somewhat experimental: it uses an external player application (MPlayer, or omxplayer on Raspberry Pi) to do the actual playback, and embeds it into Impressive's window. so like, she's serving but she's still in beta 💅
  • always — if present and set to 1 or True, the media file in the sound or video properties will be played every time the page is entered, not just the first time.
  • progress — set this to zero and the presentation progress bars (the ones set up with -d/--duration, -q/--page-progress or -k/--auto-progress) will not be shown on this page. in practice, it might be useful to hide the bar(s) from the first page so they aren't visible during the introduction 🌸
  • reset — set this to 1 or True and the timer resets each time this page is left, exactly as if R had been pressed. if you use the special value 2 or FirstTimeOnly, the reset only happens if the page was shown for the first time. again, this is particularly useful on the first page: a combination of progress:False, reset:FirstTimeOnly makes it possible to set up the presentation long before it actually begins — the first page can be shown for as long as you want, and actual timing starts at the second page. genius honestly 👑
  • rotate — per-page override of the global -r command line option. it specifies how the page should be rotated, in 90-degree steps clockwise 🔄
  • OnEnter, OnLeave, OnEnterOnce, OnLeaveOnce — these can contain a Python callable (so a function reference or a lambda expression) that gets executed when the page is entered or left. the ~Once variants only execute when the page is entered or left for the first time. the callable must not take any arguments. this feature lets you associate arbitrary Python code with specific pages — like executing external programs 🐍
Warning: lambda expressions cannot be properly processed by the Info Script save function (the S key). if Impressive encounters lambda expressions when saving, it will remove them. on top of that, it will not overwrite the original info script — it generates an extra file that you need to merge with the original script by hand. so watch out bestie 😭
  • keys — assign this a dictionary that maps alphanumerical keys to Python functions. for example, 'keys': { 'x': SomeFunction } will invoke SomeFunction() if the lowercase character 'x' is typed while the page is displayed. same restrictions as the OnEnter/OnLeave family apply to the functions: they must not take any parameters, and lambda functions can not be saved. also note you can't overwrite Impressive's pre-defined key bindings with this method, sorry 🥲
  • invert — specifies whether the colors of that page should be inverted the same way the --invert command-line switch does. it overrides --invert on a per-page basis: set to True and the page will always be inverted; set to False and the page will never be inverted even if --invert was specified on the command line 🌈
note that in Impressive versions prior to 0.11.0, the transition and transtime properties defined the transition from the current page to the next, not from the previous page to the current one. so if you're on an ancient version, that's why everything looks backwards 💀

the properties are all stored together in a Python dictionary called PageProps. the syntax looks like this:

PageProps = {
  1: {
       'title': "Title Page",
       'transition': PagePeel,
       'sound': "background_music.mp3"
     },
  2: {
       'title': "Another Page",
       'timeout': 5000
     }
}

the PageProps definition (and only the PageProps definition) will be rewritten by Impressive if you press the S key. user-defined PageProps entries will also be left untouched, except for some pretty-printing ✨

💖 GLOBAL PRESENTATION PROPERTIES 💖

the name of the presentation shows up in the title bar of the Impressive window (if you're not in fullscreen mode, that is). by default, the file name gets used for this — or the PDF metadata title, if that's available — but you can also explicitly set the presentation title by overwriting the DocumentTitle variable:

DocumentTitle = "My Presentation"

another useful variable is AvailableTransitions, which contains a list of all transition classes that may be used for randomly assigning transitions to pages lacking the transition property. so if a certain transition is just not it (either because you personally can't stand it, or because it should be used exclusively on pages where you manually assigned it via PageProps), you can do something like this:

AvailableTransitions.remove(WipeBlobs)

and on the flip side, you can activate transitions that aren't enabled by default:

AvailableTransitions += [SlideUp, SlideDown]

alternatively, you can completely overwrite AvailableTransitions to assign the same transition (or set of transitions) to every single page:

AvailableTransitions = [Crossfade]

🎀 OPTION OVERRIDES 🎀

okay so bestie, here's another little job that info scripts do and honestly it's kind of iconic: they can override your default settings or your command-line settings, but like, per file. Yes. One page can have its own whole vibe. ✨

The way you do it is so simple it's giving effortless: you just overwrite one of the variables that are defined at the beginning of impressive.py. That's it. That's the whole trick.

Each of those variables maps to either:

  • a command-line setting, or
  • some constant related to visual appearance or performance.

So like, say you want to force fullscreen mode for one specific presentation? No big deal, you literally just write:

Fullscreen = True

and boom 💅 that presentation is going fullscreen whether the command line likes it or not.

🦋 WORKING DIRECTORIES 🦋

okay this one matters, listen up, because paths are always the thing that ruins everyone's day 😭

While the info scripts themselves are executing, the working directory is always the directory in which the info script is stored in. Periodt. That's home base for the script.

But — and this is the plot twist 🫶 — the base directory for external actions that originate from Page Properties or PDF hyperlinks is always the directory of the PDF or image file that this page belongs to.

So in other words, if you write something like this in the info script for one page of presentation.pdf:

'sound': "music.mp3"

then the file music.mp3 is expected to be sitting in the same directory as presentation.pdf. Not the info script's directory. The PDF's directory. iykyk 🌸

two different base directories depending on what you're doing — don't mix them up, bestie, your music.mp3 will not be found and you will be sad 💀

👑 AUTHOR 👑

Impressive and its documentation has been written mainly by Martin J. Fiedler <martin.fiedler@gmx.net>, with small portions of the code written by external contributors. See the source code file for details. 🫶

🌈 REPORTING BUGS 🌈

Report bugs to <martin.fiedler@gmx.net>.

and that's the whole page, bestie!! 🎀 this fine piece of documentation is the IMPRESSIVE(1) manual page, dated 2023-11-04, brought to you by Martin J. Fiedler — go forth and make unreasonably beautiful presentations, you absolute icon 👑✨💖

📦 where this page comes from