pyelink 1.0.0

Python wrapper for SR Research EyeLink eye trackers

PyeLink

Python wrapper for SR Research EyeLink eye trackers.

Installation

You must specify a backend when installing pyelink. A simple pip install pyelink will NOT work because pyelink requires one of three mutually exclusive display backends (pygame, psychopy, or pyglet).

Choose ONE backend:

# For Pygame users
pip install pyelink[pygame]

# For PsychoPy users (Python < 3.12 only)
pip install pyelink[psychopy]

# For Pyglet users (pyglet 2.0+)
pip install pyelink[pyglet]

You'll also need to install pylink separately from SR Research:

pip install --index-url=https://pypi.sr-support.com sr-research-pylink

Note: This codebase has been tested on macOS ARM (Apple Silicon) only.

⚠️ Backend Compatibility Warning

You CANNOT install both psychopy and pyglet backends together.

Why? PsychoPy pins pyglet==1.4.11 (from 2017) as a dependency, while the modern pyglet backend requires pyglet>=2.0.0. These versions are incompatible.

Solution: Choose ONE backend:

• Pygame (recommended): Works everywhere, no conflicts
• PsychoPy: Use if you need PsychoPy features, but cannot use pyglet 2.0+
• Pyglet: Use if you want modern pyglet (2.0+) but don't need PsychoPy

Platform-Specific Notes

macOS:

• PyAudio requires PortAudio. Install it first:

brew install portaudio

Quick Start

import pyelink as el

# Configure tracker with backend
settings = el.Settings(
    backend='pygame',  # or 'psychopy', 'pyglet'
    fullscreen=True,
    screen_width=1920,
    screen_height=1080,
    filename="mydata",
    filepath="./data/",
)

# Tracker creates and owns the window
tracker = el.EyeLink(settings)

# Calibrate (optionally record samples during calibration)
tracker.calibrate(record_samples=True)

# Option A: Direct window access for custom drawing
tracker.window.fill((128, 128, 128))  # pygame example
# ... backend-specific drawing ...
tracker.flip()

# Option B: Helper methods for common patterns
tracker.show_message("Press SPACE to begin")
tracker.wait_for_key('space')

# Run your experiment
tracker.start_recording()
# ... show stimuli, collect data ...
tracker.stop_recording()

# Clean up (closes window and saves EDF automatically)
tracker.end_experiment()

Development

For development with different backends:

# PsychoPy backend
uv pip uninstall pyelink && uv pip install -e ".[psychopy]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink

# Pygame backend
uv pip uninstall pyelink && uv pip install -e ".[pygame]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink

# Pyglet backend
uv pip uninstall pyelink && uv pip install -e ".[pyglet]" && uv pip install --index-url=https://pypi.sr-support.com sr-research-pylink

Attribution

This package is based on code originally developed by:

• Marcus Nyström (Lund University Humanities Lab, Lund, Sweden)

  • Email: [e-mail]

• pylinkwrapper by Nick DiQuattro

  • Repository: https://github.com/ndiquattro/pylinkwrapper
  • Core EyeLink functionality and wrapper architecture

Acknowledgments

This project has received funding from the European Union's Horizon Europe research and innovation funding program under grant agreement No 101072410, Eyes4ICU project.