muse-lsl

To use muselsl within your own Python projects, install it into a virtual environment using pip.

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install muselsl

For most users, installing muselsl via pipx is recommended as it manages an isolated environment and adds the command to your PATH automatically.

macOS

brew install pipx
pipx ensurepath
# Close and reopen terminal after ensurepath
pipx install muselsl

Linux (Debian/Ubuntu)

sudo apt install pipx
pipx ensurepath
# Close and reopen terminal after ensurepath
pipx install muselsl

Windows (PowerShell)

py -m pip install --user pipx
py -m pipx ensurepath
# Close and reopen terminal after ensurepath
pipx install muselsl

Common issues on Linux:

• Permission denied during scan: Run sudo setcap 'cap_net_raw,cap_net_admin+eip' which hcitool`` (requires libcap).
• Characteristic not found: Downgrade pygatt to version 3.1.1: pip install pygatt==3.1.1.
• No BLE adapter found: Ensure Bluetooth is turned on.
• Connection timed out: This may be an OS-level Bluetooth crash; try toggling Bluetooth off and on.
• RuntimeError: could not create stream outlet: Ensure pylsl version 1.10.5 is installed.

Muse 2 devices provide additional data types: PPG (photoplethysmography), ACC (accelerometer), and GYRO (gyroscope). These are streamed in separate LSL streams named "PPG", "ACC", and "GYRO".

Via Command Line: To stream all sensors simultaneously:

muselsl stream --ppg --acc --gyro

To record a specific data type (only one type per record command):

muselsl record --type ACC

Via Python Library:

from muselsl import stream, list_muses

muses = list_muses()
stream(muses[0]['address'], ppg_enabled=True, acc_enabled=True, gyro_enabled=True)

You can import stream and list_muses to integrate Muse streaming into your Python code.

Important: The stream() function is synchronous. This means any code following the stream() call will not execute until the stream has been closed.

from muselsl import stream, list_muses

muses = list_muses()
# Start streaming from the first device's address
stream(muses[0]['address'])

# This only runs after the stream is stopped
print('Stream has ended')

Once a stream is running (via muselsl stream), you can use these commands in a separate terminal or process to interact with the data.

Visualize data:

muselsl view

Visualize using version 2 (requires vispy and mne):

muselsl view --version 2

Record EEG data to CSV (includes 'Markers' data):

muselsl record --duration 60

Record data directly (bypasses LSL, does NOT include 'Markers'):

muselsl record_direct --duration 60

Use the list command to find the names or MAC addresses of connected Muse devices.

muselsl list

To begin streaming EEG data via LSL, use the stream command. You can target a specific device by name or MAC address.

Stream the first available device:

muselsl stream

Stream by device name:

muselsl stream --name YOUR_DEVICE_NAME

Stream by MAC address (more reliable):

muselsl stream --address YOUR_DEVICE_ADDRESS

muselsl stream --name Muse-41D2

Detailed flags for the view command:

• -w, --window: Window length to display in seconds (default: 5.0).
• -s, --scale: Scale in uV (default: 100).
• -r, --refresh: Refresh rate in seconds (default: 0.2).
• -f, --figure: Window size (default: 15x6).
• -v, --version: Viewer version (1 or 2). 1 is the default stable version, 2 is in development.
• -b, --backend: Matplotlib backend to use (default: TkAgg).
• -l, --log: Set the logging level.

muselsl view --help

Detailed flags for the record command:

• -d, --duration: Duration of the recording in seconds (default: 60).
• -f, --filename: Name of the recording file.
• -dj, --dejitter: Whether to apply dejitter correction to timestamps.
• -t, --type: Data type to record from. Options: EEG, PPG, ACC, or GYRO (default: EEG).
• -l, --log: Set the logging level.

muselsl record --help

Use the stream command to start streaming data from a Muse headset via Lab Streaming Layer (LSL). This command allows you to select specific data channels (EEG, PPG, ACC, GYRO, or fNIRS), choose a connection preset, and configure connection parameters like MAC address or backend.

muselsl stream [-a ADDRESS] [-n NAME] [-b BACKEND] [-i INTERFACE] [-P PRESET] [-p] [-c] [-g] [-o] [-d] [-dl] [-lslt] [-r RETRIES] [-m MODEL] [-l LOG_LEVEL]