University of Sussex | Reality Bending Lab

How to send event triggers to Lab Streaming Layer from JsPsych

Sun, 11 Jan 2026 00:00:00 +0000

Hello there! 👋 Let’s learn how to send event triggers to Lab Streaming Layer (LSL) from JsPsych.

Lets start with some basics!

What does this mean and when is this useful?

Lab streaming layer (LSL) is a system used to receive, synchronise and stream signals from multiple inputs during experiments. LSL is designed to help researchers easily compare their data across multiple technologies, as time synchrony is integral for making meaningful analyses.

When collecting data on stimulus response during experiments, it’s important that the stimulus onset is recorded precisely, especially if this is mapped onto physiological responses as this has implications on how we interpret our data. One good example of a use case is that you have a Muse headband or any other device that can scream via LSL, and you want to precisely mark events in it.

Event triggers are coded into JsPsych online experiments to accurately mark events, such as when a stimulus appeared on the screen. We have found this method to yield the most precise timestamps of events, compared to alternative methods such as using the Bitalino LUX.

This tutorial will explain how to set this up for an experiment situated on GitHub, although you can adapt this for your hosting platform.

This blog will help you understand the set-up for event triggers. For an example of this in action, refer to https://github.com/OliverACollins/muse-athena-test/tree/main/blackwhite. This experiment recorded markers on a screen turning from white to black- you may want to follow along with lsl_bridge.py and blackwhite_jspsych.html¹ for the full implementation.

How to set up event triggers

Requirements

Your experiment is in-person: In order to use these event triggers, you will need to run your experiment on a local host server, which will need to be manually set up for each trial. Therefore, this setup is intended for in-person experiments that are led by a researcher to set up the participant’s screen.
You have two machines, one for the participant, and one for the researcher: The participant’s machine will display the experiment and send the markers to the researcher’s machine, which will record the LSL stream events.
All machines must be on the same network connection: To send the markers from the participant’s machine to the researcher’s recording machine, we must run the experiment on a web server which directs the markers to the recording machine via its ipv4 address.

The LSL bridge script

The LSL bridge Python script is responsible for actually sending the markers to LSL- it ’listens’ for messages from the browser that the participant is doing the experiment from, and converts them into ‘markers’ for your recording software (such as LabRecorder) to receive.

See an example of a full script

from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import urlparse, parse_qs
from mne_lsl.lsl import StreamInfo, StreamOutlet, local_clock
import threading

# ---------------------------------------------------------------------
# CONFIG
# ---------------------------------------------------------------------
LSL_STREAM_NAME = "jsPsychMarkers"
LSL_STREAM_TYPE = "Markers"
LSL_SOURCE_ID = "jspsych-lsl-bridge"
SERVER_HOST = "0.0.0.0"
SERVER_PORT = 5000
# ---------------------------------------------------------------------

# Create an LSL outlet for event markers
info = StreamInfo(
    name=LSL_STREAM_NAME,
    stype=LSL_STREAM_TYPE,
    n_channels=1,
    sfreq=0,
    dtype="string",
    source_id=LSL_SOURCE_ID,
)

desc = info.desc
desc.append_child_value("manufacturer", "jsPsych")
channels = desc.append_child("channels")
ch = channels.append_child("channel")
ch.append_child_value("label", "JsPsychMarker")
ch.append_child_value("unit", "string")
ch.append_child_value("type", "Marker")

outlet = StreamOutlet(info)

# ---------------------------------------------------------------------
# HTTP Request Handler
# ---------------------------------------------------------------------
class MarkerHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        parsed = urlparse(self.path)
        params = parse_qs(parsed.query)
        path = parsed.path

        if path == "/sync":
            # Return current LSL clock to JS
            ts = local_clock()
            self.send_response(200)
            self.end_headers()
            self.wfile.write(str(ts).encode())

        elif path == "/marker":
            value = params.get("value", ["1"])[0]
            ts_js = params.get("ts", [None])[0]

            if ts_js is not None:
                ts = float(ts_js)
            else:
                ts = local_clock()

            outlet.push_sample([value], ts)
            print(f"→ Marker {value} @ {ts:.6f}")

            self.send_response(200)
            self.end_headers()
            self.wfile.write(b"OK")

        else:
            self.send_response(404)
            self.end_headers()

# ---------------------------------------------------------------------
def run_server():
    server_address = (SERVER_HOST, SERVER_PORT)
    httpd = HTTPServer(server_address, MarkerHandler)
    print(f"\n[LSL Bridge] Serving on http://{SERVER_HOST}:{SERVER_PORT}")
    print(f"[LSL Bridge] Stream '{LSL_STREAM_NAME}' ready for LabRecorder.\n")
    httpd.serve_forever()

# ---------------------------------------------------------------------
if __name__ == "__main__":
    server_thread = threading.Thread(target=run_server)
    server_thread.start()

Configuration of the Python Script

Set-up
- Imports: Load in standard python libraries for creating a web server (http.server, urllib) and the mne_lsl library to handle the data streaming.
- Configure Variables: Name the event trigger stream so you can find it in LabRecorder, e.g. LSL_STREAM_NAME = "jsPsychMarkers".
- Add SERVER_HOST = "0.0.0.0" into the script to tell the server to listen to all available network interfaces, allowing the participant’s computer to communicate with the researcher’s.
- Specify the port for the html script to go to e.g. SERVER_PORT = 5000. You will add this port into the html script that holds the online experiment, in order to send the experiment to this python script.
Create the LSL outlet for event triggers
- Define the metadata for the stream: info = StreamInfo( name=LSL_STREAM_NAME...
- Create the outlet object that will push data out to the network: outlet = StreamOutlet(info).
Create the request handler to define what happens when the participant’s browser contacts the server.
- The sync route:
  - if path == "/sync":: Checks if the browser is asking to synchronize clocks.
  - ts = local_clock(): Grabs the current high-precision time from the LSL clock on the Recording Machine.
  - self.wfile.write(...): Sends this timestamp back to the browser. The browser needs this to calculate the time difference (offset) between the two computers.
- The marker route:
  - elif path == "/marker": Checks if the browser is trying to send an event marker.
  - It extracts value (the marker name, e.g., “1”) and ts (the timestamp calculated by the browser) from the URL parameters.
  - outlet.push_sample([value], ts): This is the most important line. It injects the marker into the LSL stream using the timestamp provided by the browser. This ensures that even if there is network lag, the timestamp recorded in the EEG data remains accurate to when the event actually happened on the participant’s screen.
Run the Server
- run_server(): Starts the HTTP server and prints a confirmation message that it is ready for LabRecorder.
- threading.Thread(...): Runs the server in a separate thread so it doesn’t block the main Python process.

Configuration of the JsPsych HTML script

See an example of a full script

<!DOCTYPE html\>

<html>

<head>

<title>Black/White Muse Synchronisation Test</title>

<script src="https://unpkg.com/jspsych\@7.3.4"\>\</script\>

<script src="https://unpkg.com/\@jspsych/plugin-html-keyboard-response\@1.1.3"\>\</script\>

<script src="https://unpkg.com/\@jspsych/plugin-image-keyboard-response\@1.1.3"\>\</script\>

<script src="https://unpkg.com/\@jspsych/plugin-preload\@1.1.3"\>\</script\>

<script src="https://unpkg.com/\@jspsych/plugin-fullscreen\@2.1.0"\>\</script\>

<link href="https://unpkg.com/jspsych@7.3.4/css/jspsych.css" rel="stylesheet" />

</head>

<body>

</body>

<script>
// -----------------------
// LSL bridge (promise-based)
// -----------------------
var lslBaseTime = null

function syncLSL() {
    return new Promise(async function (resolve, reject) {
        try {
            let offsets = []
            for (let i = 0; i < 3; i++) {
                var startPerf = performance.now()
                let resp = await fetch("http://139.184.128.202:5000/sync", { cache: "no-store" })
                let text = await resp.text()
                var lslTime = parseFloat(text)
                var endPerf = performance.now()
                var perfMid = (startPerf + endPerf) / 2
                offsets.push(lslTime - perfMid / 1000)
                await new Promise((r) => setTimeout(r, 100)) // Short delay between syncs
            }
            lslBaseTime = offsets.reduce((a, b) => a + b, 0) / offsets.length
            console.log("LSL sync done (averaged):", lslBaseTime)
            resolve(lslBaseTime)
        } catch (e) {
            console.error("LSL sync exception:", e)
            reject(e)
        }
    })
}

function sendMarker(value = "1") {
    // If not synced, still send marker (server will timestamp with local_clock())
    if (lslBaseTime === null) {
        console.warn("LSL not synced yet - sending without JS timestamp")
        fetch("http://139.184.128.202:5000/marker?value=" + encodeURIComponent(value))
            .then(function () {
                console.log("sent marker (no-ts)", value)
            })
            .catch(function (err) {
                console.error("Marker send error:", err)
            })
        return
    }

    var ts = lslBaseTime + performance.now() / 1000
    var url = "http://139.184.128.202:5000/marker?value=" + encodeURIComponent(value) + "&ts=" + encodeURIComponent(ts)
    fetch(url)
        .then(function () {
            console.log("sent marker", value, "ts", ts)
        })
        .catch(function (err) {
            console.error("Marker send error:", err)
        })
}

/* --------------------------
   Experiment Definition
--------------------------- */

function startExperiment() {

    var jsPsych = initJsPsych({
        override_safe_mode: true
    });

    var timeline = [];

    /* preload */
    timeline.push({
        type: jsPsychPreload,
        images: ["white.png", "black.png"]
    });

    /* stimuli */
    var test_stimuli = [
        { stimulus: "white.png", duration: 750, marker: 0 },
        { stimulus: "black.png", duration: 500, marker: 1 }
    ];

    /* trial */
    var test = {
        type: jsPsychImageKeyboardResponse,
        stimulus: jsPsych.timelineVariable("stimulus"),
        trial_duration: jsPsych.timelineVariable("duration"),
        choices: "NO_KEYS",

        data: {
            marker: jsPsych.timelineVariable("marker")
        },

        on_start: function(trial) {
            requestAnimationFrame(() => {
                sendMarker(trial.data.marker);
            });
        }
    };


  var loop_node = {
      timeline: [{
          timeline: [test],
          timeline_variables: test_stimuli,
          randomize_order: false
      }],
      loop_function: function() {
          return jsPsych.getTotalTime() < 2100000;
      }
  };

  timeline.push(loop_node);


    jsPsych.run(timeline);
}

// -----------------------
// Run: first sync then start experiment
// -----------------------
syncLSL()
    .then(function () {
        startExperiment()
    })
    .catch(function (err) {
        console.warn("Proceeding without LSL sync (sync failed):", err)
        startExperiment()
    })

</script>

</html>

The code sending triggers from the browser to the LSL bridge script is written in javascript. It is ‘promise-based’, meaning it is coded to wait until it receives a signal from the participant’s computer. This code is designed to track the exact time it is on the participant’s computer and send markers precisely aligned to that time.

Synchronisation
- var lslBaseTime = null: A variable to store the calculated time difference between the two computers.
- The function syncLSL() {...} can be looped three times to get an average reading.
- Get the time of the marker: fetch("http://.../sync")
- Record startPerf (when the request left) and endPerf (when the answer came back).
- You can assume the server received the message exactly halfway between start and end (perfMid).
- Calculate the difference between the browser’s clock and the LSL clock: offsets.push(lslTime - perfMid / 1000).
- Finally, average these offsets into lslBaseTime. Now the browser knows how to convert its own time to LSL time.
Sending markers
- Safety check in case sync fails: if (lslBaseTime === null) can be coded to send markers based on the timing from the participant’s computer without synchronisation, which is less accurate but better than nothing.
- Code the mathematical logic to account for the offset in time for the recording computer to receive the marker, so the generated timestamp aligns with the recording computer’s timestamp: var ts = lslBaseTime + performance.now() / 1000.
- Send the marker name and this calculated timestamp to the python bridge: fetch(url).

Usage

On the researcher’s machine:

Turn off the firewall in security settings for the researcher’s machine.
Open the lsl bridge script and go onto the terminal (we use VS code). Type ipconfig to retrieve the ipv4 address.
In the terminal, type pip install mne-lsl.
Select all text in the bridge script and run it (ctrl+a, shift+enter)

On the participant’s machine:

Open the html script. You will need to ensure the terminal working directory points towards your experiment folder- the best way to do this is to open your repository folder on VS code.
Copy the ipv4 address from the researcher’s machine into the html script- there should be three instances before the :5000 port address.
In a new terminal, run python -m http.server 8000
You are now ready to run the experiment. Go onto your browser and enter the link ‘http://localhost:8000/index.html’, adjusting for the name of your html script. Your experiment should now run on the participant’s machine. The researcher can view markers received in their python terminal.

Special shoutout to our placement student Oliver Collins for preparing these scripts! ↩︎

How to collect and save data with DataPipe in OSF

Wed, 02 Jul 2025 00:00:00 +0000

Hello there! 👋 Let’s learn how to set up DataPipe to collect and save data in OSF.

Lets start with some basics!

What is DataPipe?

DataPipe is a tool that allows you to collect and save data in OSF (Open Science Framework). It is designed to help researchers manage their data collection process efficiently, ensuring that data is stored securely and can be easily accessed for analysis.

How to set up DataPipe in OSF

Create an OSF Project: Start by creating a new project in OSF. This will be the container for your data and any related files. You can set up an account if you don’t have one already, quite easily!
- Go to the OSF homepage and log in or create an account. You can easily sign up through institutional access.
- Click on “Create New Project” and fill in the necessary details such as project title, description, and visibility settings. Choose “Germany - Frankfurt” as the server location; this is important for data privacy and compliance with regulations such as GDPR.DO NOT SET YOUR PROJECT AS PUBLIC as the data being saved will not be anonymized and may contain sensitive information.
Create OSF Token: You will need to create a token to grant DataPipe the necessary permissions to access your OSF project.
- Go to your OSF “Settings” tab and navigate to the “Personal Access Tokens” section.
- Click on “Create Token” and give it a name (e.g., “DataPipe Token”).
- Set the permissions for the token, ensuring it has access to read and write data in your project.
- Copy the generated token; you will need it later.
Link OSF to DataPipe: In DataPipe, you will need to link your OSF project using the token you created.
- Open DataPipe, click “Account” in the top-right corner and select “Settings”.
- Click on the “Set OSF Token” button and paste the token you copied earlier from OSF.
Create new experiment on DataPipe: Now that your OSF project is linked, you can create a new experiment in DataPipe.
- In the “My Experiments” DataPipe tab, click on the “Create New Experiment” button.
- Give the experiment a name - I recommend using the same name as your OSF project for consistency.
- Add the OSF project ID to the experiment settings. You can find the project ID in the URL of your OSF project (it is the alphanumeric string after osf.io/)
- Create a New OSF Data Component called “data”. This will create a folder - named “data” - in your OSF project where all the data collected will be saved.
- Again, choose “Germany - Frankfurt” as the server location for your DataPipe experiment.
Configure Data Collection: Once the experiment is set up on DataPipe, enable data collection on the “Status” section. You can optionally enable base64 data collection if you wish to encode any video, audio, or image files as strings. “Condition assignment” can also be enabled - this makes DataPipe loop through the conditions when it requests the data. When deciding whether these features are suitable, it’s best to consider how you will preprocess the data. It’s advised that you only enable the minimum needed as a security measure.
Save the data from the experiment hosted on GitHub: If you are using a GitHub repository to host your experiment, you can save the data collected by writing the following code within the experiment HTML file. Here is what that code might look like…
- Ensure you load the jsPsych DataPipe plugin, along with the rest of your plugins, within the head of the HTML script:
```
        <script src="https://unpkg.com/@jspsych-contrib/plugin-pipe"></script>
```
- After initializing your jsPsych timeline, to generate a random participant ID for your study, you can code the following:
```
// Initialize timeline
    var timeline = []
    participant_ID = jsPsych.randomization.randomID(10)
```
- This next bit of code should be called at the end of your experiment (albeit before running the timeline) to ensure that all data is saved to the OSF project, using the unique participant ID generated from the step above:
```
// Save data via DataPipe
    timeline.push({
        type: jsPsychPipe,
        action: "save",
        experiment_id: "xxxxxxxxxx", // This in generated in the DataPipe interface
        filename: `${participant_ID}.csv`,
        data_string: () => jsPsych.data.get().csv(),
    })
```
- On the experiment created in DataPipe, there is an ‘Experiment ID’ field. This is the ID you need to add to the experiment_id field in the code above.
- The filename field can be customized to include the participant ID or any other identifier you prefer.
- If publishing your experiment to GitHub, make sure the link is
  
  ‘https://[your username].github.io/[your repository name]’
  
  or ‘https://[your username].github.io/[your repository name]/[name of experiment’s html file]’ if the html file for your experiment is named anything other than 'index.html'
Run Your Experiment: With everything set up, you can now run your experiment. DataPipe will automatically collect and save the data to your OSF project as specified.

Give it a try! If you’d like further clarification, the DataPipe website includes a useful outline.

Sussex Psychological Methods MRes: Tips and Advice

Tue, 19 Mar 2024 00:00:00 +0000

Ola! I’m Ana. As I’m starting to approach the end of the year, it might be a good time to reflect and share my experience of doing a research masters in psychological methods at the University of Sussex, during the 2023/2024 academic year. First, I will talk a little bit about the modules I took; then I will mentioned all the reasons why you should choose to work with the Reality Bending Lab (ReBeL) and lastly, I will share some gems on how to survive the masters 💎. Hopefully this blog will help you decide whether this degree is for you! Shall we start?

Overview of the Modules

Since this is a research masters (MRes) aiming to prepare students for a future career as psychology researchers, the modules will have a significant focus on different research frameworks and practices, statistics and coding. During the Autumn semester you will have three main modules: 1) a (re)introduction to statistical models; 2) an introduction to Qualitative Methods; and 3) an introduction to better quality research practices. This term is super heavy on its content (no jokes) and will feel like a lot to do and learn (see below for tips on how to survive). However, there are plenty of materials to help you through this term, such as the R tutorials from our own in-house celebrity Professor Andy Field.

The Spring semester is less content heavy and more practical focus. There are again, three main modules: 1) a theoretical and practical module on how to use advanced statistical methods; 2) an introduction to the Bayesian framework; and 3) an introduction to Python programming and how to use it to implement experiments. This has been a delightful term, not because it is easy, but because the focus is less on memorising and more on learning how. Similarly, there are plenty of amazing materials to help you through this term such as optional zoom meetings to help you understand the materials and continuous communication on discord between lecturers and students.

Additionally, there will be a research module that runs both in Autumn and Spring, and a dissertation module that starts in January and ends in August (i.e., when the dissertation project is due).

The Internship

Critically, you will also do an “internship” as part of this masters (named the “research process” module 🤷‍♀️). This is by far the most exciting part of this masters as you will learn first-hand what is like to be a researcher. You can essentially chose any psychology researcher from Sussex to work with, providing you with a great network and experience. Now… you may be wondering what lab to choose? And oh boy, do I have the answer for you!

Introducing the Reality Bending Lab (ReBeL)

Rebel is led by Dr. Dominique Makowski. He will be your Mr. Miyagi during the Autumn and Spring term (and also your lecturer for the Bayesian Module). His patience, humour, straightforwardness and unmatched theoretical and pragmatic knowledge will be one of the big reasons why you will desire to be a researcher at the end of this masters (PS: no payment has been received in exchange for this testimony). The lab focus a lot on innovation hence you will learn new ways to collect neuroscientific data and use new statistical methods. There will also be a big focus on collaboration. Yes you will work independently, however more likely than not you will have the support of everyone in the lab, and you will be giving support yourself (getting a bit of experience on supervision and mentoring). Curiosity is welcome and encouraged. Ask your questions, get involved in all aspects of the process if possible, and take advantage of the fact you will have a ‘mentor’ for the whole academic year.

During my time at ReBeL, I have been involved in various projects, such as “Exploring the Correlation between Interoception and Primal World Beliefs” and a meta-analysis of a widely used questionnaire of Interoception. These projects have taught me a lot, from how to collect and analyse both physiological and behavioural data, access and collect data for a meta-analysis, and report the work I did in oral and written format. Throughout the year, with the guidance and expertise of everyone involved in the lab, I gained a lot of confidence in my abilities as a researcher. Which is why I found this internship the most influential aspect of my masters. Ultimately, at the ReBeL lab, you will not only investigate exciting concepts and topics but you will also have first hand experience on what it actually takes to be a researcher (including the need to have a twitter account, apparently).

Survival Tips

Now… You might be wondering.. “How in the world will I do all of this in one academic year?” Here are some tips that helped me gain the most of this masters without loosing my mind.

Unsurprising tip: DO THE WEEKLY WORKSHOPS/TUTORIALS. They will provide with the majority of code, steps and knowledge necessary to complete the assignments.
Life saving tip: do meal prep for the 48-hour assignments. If you are anything like me you will rather lose sleep then a delicious home-made meal. However, with the short time window to complete these assignments, meal prepping will help you feel less anxious about “not having enough time” to complete it all whilst still giving your mind everything it needs to function (i.e., sleep and nutrients).
Qualitative tip: as part of the January assignments, you will be asked to analyse 5 interviews using a qualitative method. If you come from a mostly quantitative background like me, you will be unfamiliar to how long it takes to code qualitative data. Do not make the same mistakes as I did and start that assignment as early as possible.
Student formatting tip: when lectures say “I want it in APA format” some will expect you to write a piece of work that equates a publication level piece of work. When in doubt, ask them!
Practical life skills tip: communication is key with your supervisors. Especially during your internship; be honest about what you can and can not do, your preferred ways of working, your goals and dreams, and mostly important when you need help.
Ultimate tip: do consider part-time , especially if you want/need to be working more than 20 hours a week on top of doing this masters. It is full on, and even as part-time all the lectures will be taught in the first year and hence there is still a lot of work to do. But it is possible, and can even be enjoyable.

Junior Research Assistant (JRA) at Sussex: is it worth it?

Thu, 02 Nov 2023 00:00:00 +0000

Hi all, I am Jing, and I thought I would share my experience as a Psychology Junior Research Assistant (JRA) at the University of Sussex, as many students might wonder how it is really like. Obviously, I cannot speak for all the labs, but I hope my experience can give you a general idea of what to expect.

I worked as a JRA during summer 2023 at the Reality Bending Lab (ReBeL). And to put it simply, I think it was the most valuable experience during my undergraduate journey (PS: I have not written this at gunpoint). During these three months, I was supervised by Dr Makowski to work on a piece of original research, that thought me a lot about programming, cognitive neuropsychology, physio recordings and how real research is done. Additionally, know that it is possible to stay in the same lab next academic year, to do your final year dissertation with a strong head start in terms of skills and knowledge.

I had the pleasure of joining the Reality Bending Lab (ReBeL) along with Auz, as the first two members since the lab moved to the UK. The title of my project was “Exploring the Correlation between Interoception and Primal World Beliefs”, which involved collecting physiological data (e.g., heart rate, respiration, …) in various tasks, analysing them, and investigating the relationship between various measures. The project started from scratch, where I learned how to use the JavaScript package JsPsych to build the entire paradigm via coding. I also received detailed training on how to run a lab-based experiment, something I used to be worried but am now extremely confident about. After collecting the data from 20 participants (summer time goes by veryyyy fast!), I learned how to make and visualize Bayesian correlations in R. The output of this project was made into an academic poster, where I had to be creative and selective, to be presented at the poster session (see below). Additionally, we created the “Sussex Psychophysiological Research Protocol”, a document aiming at providing guidelines for the best practices in psychophysiological research, to benefit future research done at Sussex. It might not seem like much, but it felt like doing real contributions to research, which was great!

Something important I learned is, beyond pure academic excellence, research is also about community and networking. It was a great occasion to informally meet many researchers, and make bonds with other students. What is cool is that the JRA journey doesn’t stop abruptly and continues into the next academic year, as all candidates are invited to present their work at the JRA conference held by the university in October. This was an amazing opportunity to get a glimpse of what a scientific conference might be, feel proud about your work, connecting with fellow students, learning how to talk about research with other staff members, and gaining public speaking skills. For those who are more ambitious, why not submit your work to the national level, and present it in the British Conference for Undergraduate Research (BCUR)?

In summary, I see the JRA as a golden key to open countless possibilities for your future career path. For those considering applying to postgraduate studies or research assistants, the strong research experience you gained will put you at the top of the list. Even for those who decided to not do research in the future, it will still be rewarding as it gives a clear idea of what career you do not want. Don’t miss on it!

- Jing