Getting Started with OpenSesame

[Sam]

OpenSesame is an open-source stimulus presentation package created by Sebastiaan Mathôt. Based on Python, OpenSesame can be easily expanded through plugins and extensions. To provide EyeLink integration, SR Research has created a set of EyeLink-specific components, referred to as the EyeLink Plugin.

While OpenSesame also includes the Pygaze library, our official EyeLink Plugin provides access to the full range of EyeLink features and is the only method for which we can provide technical support. This guide will focus exclusively on the plugin provided by SR Research.

Important Notice: The EyeLink Plugin is currently under active development. Please report any issues to support@sr-research.com.

---

OpenSesame 4.* Installation Instructions

This plugin has been tested on Windows 11, and macOS 14, but should work for all operating systems supported by OpenSesame:

1. Launch OpenSesame v4.0 (and above).
   
   
2. In the console type the following pip installation command and press Enter, wait for a success message.
   
   Code:

   pip install opensesame-plugin-eyelink
   
      
   
   
3. Close OpenSesame and then open it again, the EyeLink Plugins should now be visible in the Toolbar Items menu under the header EyeLink.
   
      
   

---

Testing your installation
Before you begin, we recommend configuring your OpenSesame environment for the best performance with EyeLink systems.

• Backend Engine: OpenSesame supports Pygame (legacy), PsychoPy, and Expyriment as its backend. We strongly recommend using the PsychoPy backend, as it is robust and supports advanced visual stimuli (e.g., gratings) common in psychophysics experiments.
  
• Sound Library (Windows): If you are on a Windows PC, we also recommend changing the Sound Library to PTB. You can find this setting under Experiment Properties > Back-end settings. PTB is a low-latency library that is ideal for precise experiment control.
  

To help you get started, we provide three example OpenSesame projects that demonstrate how the EyeLink Plugin is used.

  OpenSesame4_Examples.zip (Size: 6.12 MB / Downloads: 64)

After installing the plugin, download and extract the examples from the link below. Running one of these projects is a great way to verify that the plugin is installed correctly.

The download also includes the OpenSesame 4 EyeLink Plugin User Manual.pdf, which provides detailed descriptions of each plugin component and useful information on implementation.

---

Templates / Example Experiments

Please check the OpenSesame website for information about OpenSesame and general tutorials on programming in OpenSesame. Please see below for further information on the example OpenSesame experiments provided by us.

Template	Description
OpenSesame4_Picture	A basic example demonstrating how to use the EyeLink Plugin to manage the tracker (connect/disconnect), handle data files (open/close), control recording (start/stop), and send standard integration messages for EyeLink Data Viewer. The task presents four pictures one-by-one, with each trial ending on a keypress.
OpenSesame4_GazeTrigger	This example shows how to use a gaze-based trigger to begin a trial. The trial starts only after the participant fixates on a central dot for one second. It also demonstrates proper messaging for Data Viewer.
OpensSesame4_VW_Click	This project implements a Visual World experiment, a common paradigm in language studies involving synchronized audio and image stimuli. The included inline scripts are commented to explain the implementation.

EyeLink Data Viewer Messaging Commands and Syntax
Throughout your experiment, it is a best practice to send special messages to the EyeLink data file (EDF) that enable integration with EyeLink Data Viewer. All of our example projects demonstrate how to send these messages to log important information, such as:

• Trial starting and ending times
  
• Trial variable values
  
• Stimulus information
  

For more details on the specific formatting of these messages, please see the following resources:

• Webinar: EyeLink Data Viewer Integration Messaging Protocol
  
• User Manual: Full documentation is available in the Data Viewer User Manual (accessible via Help -> Contents in the software) under the section "Protocol for EyeLink Data to Viewer Integration".
  

---

Using PyLink via Inline Scripts
In addition to the graphical components, you can use inline scripts in OpenSesame to access the full functionality of the PyLink library.

The primary documentation for this is the PyLink API User Guide and the helpful Getting Started with Python and PyLink guide. Both are included with the EyeLink Developers Kit and can be found in the following directory after installation:

• Windows: C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\
  
• macOS: /Applications/Eyelink/SampleExperiments/Python/
  
• Linux: /usr/share/EyeLink/SampleExperiments/Python/
  

For advanced users, the EyeLink Programmer's Guide provides complete documentation for the underlying C API. While the function syntax will differ from the PyLink wrapper, the core functionality is analogous and can provide deeper insight.

Plugin Updates
If you encounter issues, ensure you are using the latest version of the EyeLink plugin. Copy the command below, paste it into the OpenSesame console, and press Enter. Restart OpenSesame to complete the update.

Code:

pip install sr-research-pylink opensesame-eyelink-coregraphics opensesame-plugin-eyelink --upgrade

---

Legacy Installation for OpenSesame 3.x
Note: This section is only for users of older OpenSesame 3 releases.

An older version of the EyeLink Plugin, example projects, and installation instructions are available in the zip file below.

  OpenSesame_3.zip (Size: 4.81 MB / Downloads: 19)

Please refer to the OpenSesame_EyeLink_Plugin_User_Manual.pdf inside the zip file for detailed instructions. The necessary plugin and pylink files for this legacy version have been included in the download, as they may no longer be available in recent releases of the EyeLink Developers Kit.