TittaLSL

The TittaLSL tool is an extension to Titta (and its TittaMex and TittaPy wrappers). It allows to stream data from Tobii eye trackers in Titta's format using Lab Streaming Layer and to receive such data and access it through an API that is identical to that of Titta. That allows handling local and remote eye tracker data sources in a uniform manner, making it possible to design interesting experiments using multiple eye trackers.

TittaLSL is a C++ library that can be compiled and used as a static library without Matlab/Octave or Python. However, MATLAB and Python wrappers are also provided in the form of TittaLSLMex and TittaLSLPy, respectively.

In comparison to the the Lab Streaming Layer TobiiPro Connector, Titta LSL provides access to all gaze data fields instead of only gaze position on the screen, as well as the external signal, time synchronization and positioning streams. Samples are furthermore properly timestamped using the timestamps from the eye tracker, where possible (all streams except for the positioning stream, which doesn't have timestamps).

When using TittaLSL, please cite the following paper: Niehorster, D.C., Nyström, M. (2025). TittaLSL: A toolbox for creating networked eye-tracking experiments in Python and MATLAB with Tobii eye trackers. Behavior Research Methods. doi: 10.3758/s13428-025-02714-2

The TittaLSL, TittaLSLMex and TittaLSLPy classes

The functionality of TittaLSL is divided over two classes, Sender for making eye tracker data available on the network (AKA an outlet in Lab Streaming Layer terminology) and Receiver for recording from TittaLSL data streams available on the network (AKA an inlet). The below documents the available methods of these classes. The functionality below is exposed under the same names in MATLAB as TittaLSL.Sender and TittaLSL.Receiver, respectively. The same functionality is also available from TittaLSLPy.Sender and TittaLSLPy.Receiver instances, but in that case all function and property names as well as stream names use snake_case names instead of camelCase. In C++ all below functions and classes are in the TittaLSL namespace. See here for example C++ code using the library, and here for example Python code.

Free functions

Construction and initialization

Methods

The following method calls are available on a TittaLSL.Sender instance:

The following static calls are available for TittaLSL.Receiver:

The following method calls are available on a TittaLSL.Receiver instance. Note that samples provided by the consume*() and peek*() functions are almost identical to those provided by their namesakes in Titta for a local eye tracker. The only difference is that the samples provided by TittaLSL have two extra fields, remoteSystemTimeStamp and localSystemTimeStamp. remoteSystemTimeStamp is the timestamp as provided by the Tobii SDK on the system where the eye tracker is connected. localSystemTimeStamp is the same timestamp, but expressed in the clock of the receiving machine. This local time is computed by using the offset provided by Lab Streaming Layer's time_correction function for the stream that the receiver is connected to. See the Tobii SDK documentation for a description of the other fields.

Working on the source

The enclosed Visual Studio project files can be opened using the Titta.sln file in the SDK_wrapper directory. It is to be opened and built with Visual Studio 2022 (last tested with version 17.8.4).

Building the mex files

Run makeTittaLSLMex.m to build the mex file. You have to do this first if you want to use Titta from Octave, mex files for Octave are no longer bundled with Titta. However, it should be as simple as running that function once, since everything needed is contained in this repository. Mex files for MATLAB (Windows and Linux) are provided in this repository.

For building the Linux mex file the default gcc version 11.2.0 included with Ubuntu 22.04 was used. For compatibility with an earlier version of Ubuntu, either install the right GLIBCXX version or recompile following the instructions here. See this issue for more information.

Required environment variables

Some environment variables must be set when working on the code or building it from Visual Studio. Here are the values i used (at the time of writing):

• MATLAB_ROOT: C:\Program Files\MATLAB\R2023b
• PYTHON_ROOT: C:\Program Files\PsychoPy

Dependencies

Lab Streaming Layer library

To update the Lab Streaming Layer library used to build TittaLSL against, you need to manually put the some files in the right place:

1. The *.h include files are placed in \LSL_streamer\deps\include
2. The Windows lsl.lib link library is placed in \LSL_streamer\deps\lib.
3. The *.dll, *.so and *.dylib files are placed in the output directory, \LSL_streamer\TittaLSLMex\+TittaLSL\+detail. Note that if you want to update the Tobii SDK, you should perform that update first for the SDK_Wrapper. Only for step 3 do you need to place the updated tobii_research_v2.dll in the \LSL_streamer\TittaLSLMex\+TittaLSL\+detail folder.

Titta

TittaLSL also requires Titta and its dependencies to build. The build scripts are set up such that Titta is automatically built. However, ensure to check Titta's dependencies and make sure they are available, or the build will fail.

Acknowledgements

This project was made possible by funding from the LMK foundation, Sweden.