OpenSesame Plugin: Screenshot

An OpenSesame plugin for saving screenshots of stimuli and other screens within an experiment.

Copyright (C) 2024-2026 Bob Rosbag

About

This plugin saves screenshots of stimuli and other screens within an experiment.

The screenshots are saved in the folder of the log file, in a subfolder per capture method and subject, for example screenshots_stim_psycho/subject-1/filename.png.

This plugin has the following options:

• Verbose mode: print the path of each saved screenshot.
• Stimulus display (PsychoPy): capture the PsychoPy window, saved in screenshots_stim_psycho. Only available with the PsychoPy backend.
• Stimulus display (PIL): capture the first monitor with PIL, saved in screenshots_stim_pil.
• Composite of all displays (PIL): capture all monitors with PIL, saved in screenshots_full_pil.
• Filename: the filename with extension; the extension determines the picture format (.png, .jpg, etc.). Variables can be used, e.g. trial_[count_trial_sequence].png. The filename can't contain a folder.

Known issues

Which capture method works depends on the operating system and the display server. Check the screenshots of a test run before you rely on them.

• Linux, X11, PsychoPy: the first screenshot of the experiment can be corrupt (dark, with a diagonal line). The plugin prevents this by reading the screen once when the first screenshot item is prepared, before the stimulus is shown. This doesn't help when the first screenshot item is prepared after its stimulus was shown, e.g. a screenshot item in a loop that directly follows the stimulus. Workaround: put a screenshot item with its own filename (e.g. dummy.png) at the start of the experiment, outside the trials, and ignore its screenshot.
• Linux, Wayland, PsychoPy: all screenshots are black. Workaround: use the PIL options, or log in to an X11 session (e.g. "Ubuntu on Xorg").
• Windows, PIL: the screenshots show the desktop behind the fullscreen experiment window. Workaround: use the PsychoPy option.
• Without a graphics card (e.g. a virtual X server such as Xvfb, which uses Mesa's software renderer), PsychoPy screenshots are black too.

Installation

Install the plugin with pip, in the Python environment of OpenSesame:

pip install opensesame-plugin-screenshot

License

This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (GPL-3.0-or-later).

The full license text is in the file COPYING, and is also available at https://www.gnu.org/licenses/gpl-3.0.html.

This plugin contains works of others. Icons are derivatives of the Faenza icon theme.

Documentation

Installation instructions and documentation on OpenSesame are available on the documentation website:

• https://osdoc.cogsci.nl/