Róisín Sharma | 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! ↩︎

Róisín Sharma

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

Let’s treat each other well to mutually adjust our idiosyncratic perceptual constructions to be of a kinder reality!🪼

What is the Best Interoception Questionnaire?

Sat, 20 Dec 2025 00:00:00 +0000

Hello👋! We are Róisín and Oliver, two Research Assistants at the lab, and today we are going to be discussing the tricky topic of self-report interoception questionnaires.

Interoception, essentially referring to one’s sensation of their internal body, is a fundamental phenomenon that we rely on in everyday life, and recent research highlights it as a trans-diagnostic underpinning of a variety of somatic and psychological difficulties.

While we know interoception is very important, the specifics are still being worked out. Debates continue on what exactly interoception is, is not, and what it encompasses in terms of modalities or processes. Is it limited to visceral sensations (i.e., from internal organs)? Does it include proprioception (i.e., body position sense)? Pain? What about tactile sensations (i.e., touch and skin)? Does it include the interaction with higher-order processes like attention and beliefs?

This chaotic and moving landscape has been accompanied by the development and repurposing of different interoception (and interoception-adjacent) questionnaires, each with their own philosophies and approach. Carefully choosing a good measure of interoception is crucial to avoid adding to the jingle-jangle fallacy plaguing the field, in which discrepancies and contradictions of results “related to interoception” are driven by differences in what aspect of it is actually being measured.

Moreover, unlike exteroception (vision, audition, etc.), where researchers can easily manipulate external stimuli to validate a participant’s response, interoception presents a unique challenge: the stimuli originate from within the body. Because internal states are difficult to manipulate or observe directly, objective validation is complex. Nonetheless, especially as “objective” tasks like the Heart Beat Counting Task (HCT; Schandry, 1981) have their own methodological drawbacks, self-report questionnaires remain a scalable, practical, and widely-used tools for assessing interoception. Let’s explore the most popular and established questionnaires.

Questionnaires Overview

😨 Body Perception Questionnaire (BPQ)

The BPQ is one of the earliest interoception scales, originally built by Porges in 1993. This questionnaire focuses on the autonomic nervous system, involved in stress responses, and thus is mainly concerned with internal sensing when there are problems (e.g., ’tremor in my lips’, ‘general jitteriness’ being two items for body awareness). This makes the scale beneficial in clinical contexts to investigate maladaptive interoception, particularly in patients who have a dysregulated autonomic nervous system. However, if you are interested in interoception in a wider context, other questionnaires may be more appropriate.

The Autonomic Nervous System (ANS)

🧘‍♀️ Multidimensional Assessment of Interoceptive Awareness (MAIA)

The Multidimensional Assessment of Interoceptive Awareness (MAIA) (the MAIA-2 being the most recent version) is another widely used questionnaire that accounts for body awareness in positive states - deriving from research on emotional regulation and pain. This questionnaire was created because Mehling et al. (2012) believed western medicine focused too much on bodily awareness as a maladaptive trait, even though research was increasingly finding health benefits from a sense of embodiment. It was specifically designed to assess mind-body therapies and was finalised based on data from individuals with various therapeutic backgrounds including yoga, tai chi and breath-work. The MAIA reconceptualises bodily awareness not only as an anxiety-related process but also an integral part of mindfulness. This translates to many of the questions focusing on metacognitive beliefs about one’s body and emotions, as well as some targetting more directly other mindfulness-related processes, such as attention regulation and non-reactivity. The MAIA includes subscales encompassing self-regulation abilities which - while important - might be conceptualized as distinct from core interoception.

🤧 Interoceptive Accuracy Scale (IAS)

More recently, the Interoceptive Accuracy Scale (IAS) (Murphy et al., 2019) took the opposite route, trying to remove contamination by meta-cognitive processes to focus on interoceptive accuracy (distinct from interoceptive attention). It includes 21 questions (“I can always accurately perceive when…”) pertaining discrete, clear, and “objectifiable” interoceptive events, hopefully being meaningful and consistently interpreted across participants (including those who have difficulty perceiving internal sensations).

🍃 Multimodal Interoception Questionnaire (Mint)

The Multimodal Interoception Questionnaire (Mint; Makowski et al., 2025) is the most recent interoception questionnaire, designed with the intention of addressing the caveats and limitations by building on established measures and synthesising the previous research and advances. Fundamentally, the Mint takes a “context-by-modality” approach to item development, encompassing a wide range of (seven) modalities of interoceptive experience (cardiac, respiratory, gastric, etc.) and also controlling for the contexts in which these may appear (covering negative (anxious) and positive (sexual) arousal states). The Mint also incorporates both adaptive and maladaptive aspects of interoception (interoceptive confusion), as well as items targeting different levels of processing.

Importantly, this questionnaire was developed with the aim of addressing some of the methodological shortcomings of previous interoception questionnaires, such as limiting interpretation Variance, state Dependency (the fact that respondents “anchor” their answers to their current physiological state rather than their general trait), and recency effects (recent, salient physical experiences disproportionately influencing scores), in particular by providing a clear contextual reference for each item. The validation study displayed shows strong correlations with the above questionnaires (suggesting that it can be used as a comprehensive replacement), while also demonstrating a superior predictive power for a variety of clinical conditions.

Items of the Multimodal Interoception Questionnaire (Mint)

Others

The Interoceptive Attention Scale (IATS; Gabriele et al., 2021): Attention to bodily signals. Designed as the orthogonal counterpart of the Interoceptive Accuracy Scale, also using consistent phrasing of all statements (‘Most of the time my attention is focused on…’).
The Interoceptive Sensations Questionnaire (THISQ; Vlemincx et al., 2021): Neutral internal sensations (not emotionally valenced), including cardiorespiratory activation, deactivation, and gastroesophageal sensations.
The Interoception Sensory Questionnaire (ISQ; Fiene, 2018): Designed to assess confusion about interoceptive bodily states unless these states are extreme (Alexisomia).
The Interoceptive Confusion Questionnaire (ICQ; Brewer, 2016): Assesses confusion and misinterpretation of bodily signals.
The Body Consciousness scale (BCS; Miller et al., 1981): Awareness of the “private body” (internal sensations) and “public body” (observable aspects of body)

In summary - which interoception questionnaire should I pick?

Interoceptive questionnaires are a product of their time, often molded by specific contextual demands and underlying theoretical frameworks. As our understanding of interoception evolves, so too do the tools we use to measure it. It might seem like the best option is to pick a questionnaire based on the interoception facet you are interested in (e.g., confusion, attention, accuracy, …), but as the field is still developing, and the theorethical models are in flux, it might be more useful to consider using a broader, more comprehensive, theory-agnostic questionnaire that captures multiple facets and modalities of interoception, such as the Mint.

References

Bergomi, C., Tschacher, W., & Kupper, Z. (2012). The Assessment of Mindfulness with Self-Report Measures: Existing Scales and Open Issues. Mindfulness, 4(3), 191–202. https://doi.org/10.1007/s12671-012-0110-9

Gabriele, E., Spooner, R., Brewer, R., & Murphy, J. (2021). Dissociations between self-reported interoceptive accuracy and attention: Evidence from the interoceptive attention scale. Biological Psychology, 168, 108243. https://doi.org/10.1016/j.biopsycho.2021.108243

Kolacz, J., & Bjorum, E. (2023). Measuring Autonomic Symptoms with the Body Perception Questionnaire. The Traumatic Stress Research Consortium . https://www.traumascience.org/s/TSRCMarch2023Newsletter.pdf

Kolacz, J., Holmes, L., & Porges, S. W. (2018). Body perception questionnaire (BPQ) manual. Traumatic Stress Research Consortium.

Makowski, D., Neves, A., Benn, E., Bennett, M., & Poerio, G. (2025). The Mint Scale: A Fresh Validation of the Multimodal Interoception Questionnaire and Comparison to the MAIA, BPQ and IAS. https://doi.org/10.31234/osf.io/8qrht_v1

Mehling, Price, Daubenmier, Acree, Bartmess, & Stewart. (2012). The Multidimensional Assessment of Interoceptive Awareness (MAIA). Plos One, 7(11). https://doi.org/10.1371/journal.pone.0048230.g001

Mehling, W. E., Acree, M., Stewart, A., Silas, J., & Jones, A. (2018). The Multidimensional Assessment of Interoceptive Awareness, Version 2 (MAIA-2). PLOS ONE, 13(12), e0208034. https://doi.org/10.1371/journal.pone.0208034

Miller, L. C., Murphy, R., & Buss, A. H. (1981). Consciousness of body: Private and public. Journal of Personality and Social Psychology, 41(2), 397–406. https://doi.org/10.1037/0022-3514.41.2.397

Murphy, J., Brewer, R., Plans, D., Khalsa, S. S., Catmur, C., & Bird, G. (2019). Testing the independence of self-reported interoceptive accuracy and attention. Quarterly Journal of Experimental Psychology, 73(1), 115–133. https://doi.org/10.1177/1747021819879826

Paola Solano Durán, Morales, J.-P., & Huepe, D. (2024). Interoceptive awareness in a clinical setting: the need to bring interoceptive perspectives into clinical evaluation. Frontiers in Psychology, 15(1244701). https://doi.org/10.3389/fpsyg.2024.1244701

Porges. (1993). Body Perception Questionnaire. Umd.edu. https://terpconnect.umd.edu/~sporges/body/body.txt

Schandry, R. (1981). Heart Beat Perception and Emotional Experience. Psychophysiology, 18(4), 483–488. https://doi.org/10.1111/j.1469-8986.1981.tb02486.x

Sherrington C. S. (1906). The integrative action of the nervous system. Yale University Press.

Vlemincx, E., Walentynowicz, M., Zamariola, G., Van Oudenhove, L., & Luminet, O. (2021). A novel self-report scale of interoception: the three-domain interoceptive sensations questionnaire (THISQ). Psychology & Health, 38(9), 1–20. https://doi.org/10.1080/08870446.2021.2009479