LSL Monitor

LSL Monitor is a web-based viewer and monitor for Lab Streaming Layer (LSL, https://github.com/labstreaminglayer/) streams. It allows you to inspect live data streams, visualize time series, track text and marker streams, and detect when streams go offline so you can spot gaps or invalid data during collection. LSL monitor was designed specifically for monitoring wired and or wireless physiological sensor data across different modalities and vendors in a single application.

The project is split into a Python backend and a React frontend.

• Python and Flask backend discovers LSL streams, manages data collection, exposes a JSON and REST API, and runs real-time processing plugins.
• React frontend (built with MUI and Plotly) connects to the backend, renders live graphs and timelines, and lets you manage stream visibility and layout presets. A proxy redirects messages from the React frontend to the backend (for example, localhost:3000 -> localhost:5001).

Key Features

• Live discovery of LSL streams via pylsl.
• Visualization of numeric streams as scrolling or windowed time-series plots.
• Display of string and marker streams in a timeline-style view.
• Automatic "Notes" and "SystemTimeOfDay" LSL streams for time-stamped annotations and system time.
• Stream presence monitoring to highlight missing or offline data sources.
• UI configuration management, including saved layouts, per-stream settings (duration, mode, bounds, active channels, card visibility), and saved keyboard shortcuts for the Notes panel.
• Plugin architecture for real-time derived streams. Python plugins in api/plugins/Processors.py can consume one or more input streams, create new LSL outlets with processed data, and have their configuration and state surfaced in the UI.

Architecture

• Frontend: React 18 with Create React App, MUI for layout and components, and Plotly for interactive time-series plots. The frontend talks to the backend through a proxy so calls to /api/* are forwarded to Flask on localhost:5001.
• Backend: Flask and Flask-Caching with pylsl for stream discovery and data access, background threads for continuous LSL collection and plugin execution, and endpoints for live stream details, stream status, UI configuration load and save, and plugin discovery and control.

Usage Overview

• Install Python 3.11.9 and Node.js 20.x, plus the Windows VC redistributable if you are on Windows.
• Backend: create a virtual environment under api/, install requirements.txt, and run the Flask server (see "Installation" and "To Run").
• Frontend: from the repository root, run npm ci and then npm start to launch the React app.
• On Windows, start.bat and stop.bat provide a one-shot way to start and stop both backend and frontend.
• Open http://localhost:3000 to view the LSL Monitor UI.

Requirements

• Node and NPM, Node.js v20.12 or greater.
• Python 3.11.9.
• VC_redist.x64.exe (Windows only).

Installation

Typical install (with internet access)

1. Download this repostiory or clone
2. Install Node.js
3. Install VC_redist.x64.exe
4. Install python 3.11.9 (check box to add to path if using installer) a. Note, if you have other versions of python on your machine, its reccomended to install anaconda or miniconda and run the following steps: go to root of the respostitory in cmd window conda create -n "lsl-monitor"=3.11.9 conda activate lsl-monitor

Then proceed to creating a venv and installing the python libraries

cd api/
python -m venv venv 
venv\Scripts\activate
pip install -r requirements.txt
cd ..
npm ci

Offline install with installer script (Windows, advanced)

1. Put the following files in the api/assets folder:

• python-3.11.9-amd64.exe (or use conda per above)
• node-v20.15.1-x64.msi
• VC_redist.x64.exe

2. First run the installer somewhere with internet, and download windows whl packages and node_modules folder first from an online install and copy them to the project root
3. Run api/install.bat for quick install, should pull the whl files

To Run

Windows Only

1. Run start.bat in the main folder on Windows.
2. This should open two command-line windows to run the Python-based backend and Node-based frontend. If the installation was successful, these should run without error. Otherwise please take note of the errors shown.
3. The Node command-line window may show warnings in yellow. These should not affect functionality but should be noted.
4. To stop the application, run stop.bat and accept the administrator notice if it appears.
5. There may be a chance that not all services close properly if stop.bat fails to run as administrator. If this occurs, right click stop.bat and select "Run as administrator" if possible.

Other Platforms and Development Mode

From the repository root, run:

• npm run start-api.
• npm start. Open http://localhost:3000 to view it in your browser.

Other Notes

• If you run start.bat more than once you can run into port conflicts, as well as see multiple copies of notes and systemtime LSL streams, so this is not recommended. If you have an issue always try and run stop.bat first
• See plugin instructions for information how to develop custom computations based on raw stream data
• 0 Hz Sampling rate streams that are not marker streams will be resampled to 100 Hz (hardcoded, for display purposes only)
• The app creates a notes stream, so any notes you tytped get time stamps, it also creates a system time of day stream
• Some of the python librarires were reused from: https://github.com/labstreaminglayer/pylsl

Open http://localhost:3000 to view it in your browser.

Plugin Development Instructions

Plugins for the LSL monitor are designed to take as input one or more existing streams, do processing in real time, and create a new stream with processed outputs. While it is possible to develop standalone applications to do this type of processing in python or other programming languages, there are two potential advantages to developing within the LSL monitor code-base. The first is that any new plugins developed in the python file processors.py will automatically appear in the Load Plugin menu, for easy deployment. The second reason is that the LSL monitor code already processes all open streams in the python backend, so there is perhaps some memory and CPU sharing enabled by processing streams within this environment.

LSL Monitor is written in Python. For plugin development we recommend using the Visual Studio Code (VS Code) IDE because VS Code provides the required JSON functionality to launch the python flask server used in LSL monitor. The steps to run the plugin code are as follows.

• Launching LSL Monitor

• In the VSCode API, under the File tab, click on Open Folder, then go to [repository root]/api and click on “Select Folder”
• The python code that contains each plugin class, which needs to be run from VS Code is “api/plugins/Processors.py”
• When running Processors.py, you need to select “Debug using launch.json” in the upper right of the IDE under “Run or Debug”
• You then need to select the “Python Debugger:Flask” option
• In order to start LSL Monitor, you need to open a command window in the root folder of the LSL monitor app (in Windows File Explorer, go to LSL Monitor and right click and select “Open in Terminal”)
• Then enter: “npm start” and answer “yes” to prompt. This launches LSL Monitor in a Chrome tab

Distribution Statement

DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.

This material is based upon work supported by the Department of the Air Force under Air Force Contract No. FA8702-15-D-0001 or FA8702-25-D-B002. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Department of the Air Force.

© 2025 Massachusetts Institute of Technology.

The software/firmware is provided to you on an As-Is basis

Delivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work.