Metadata-Version: 2.3
Name: opensesame-plugin-screenshot
Version: 0.8.3
Summary: OpenSesame plugin for saving screenshots of the stimulus display and of all displays during an experiment
License: GPL-3.0-or-later
Author: Bob Rosbag
Author-email: mail@bobrosbag.nl
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pillow
Requires-Dist: screeninfo (>=0.8)
Project-URL: Homepage, https://github.com/dev-jam/opensesame-plugin-screenshot
Project-URL: Repository, https://github.com/dev-jam/opensesame-plugin-screenshot
Description-Content-Type: text/markdown

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.

| System | Stimulus display (PsychoPy) | Stimulus display and composite (PIL) |
| --- | --- | --- |
| Linux, X11 | works (see below for the first screenshot) | works |
| Linux, Wayland | black images | works |
| Windows | works | shows the desktop behind a fullscreen experiment, not the stimulus |

- *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/>

