How alexandrebarachant/muse-lsl works
Project type and purpose
• From the README and file tree, this is an open‑source Python package and CLI tool (“muse‑lsl”) for connecting to Muse EEG headsets over Bluetooth, publishing data streams via Lab Streaming Layer (LSL), visualizing them, and recording to CSV. It also exposes a Python API for integration into other projects.
File structure
• Top‑level: setup.py/cfg, README, LICENSE, examples/, CLI entrypoint.
• muselsl/
• __main__.py & cli.py – command‑line interface (list, stream, view, record).
• backends.py – pluggable Bluetooth adapters (bleak, pygatt, etc.).
• muse.py – low‑level Muse device connection and data decoding.
• stream.py – LSL outlet creation and data loop.
• record.py – subscriber that reads LSL streams and writes CSV.
• view.py + viewer_v1.py/viewer_v2.py – real‑time visualization UI modules.
• helper.py, constants.py – shared utilities and configuration.
• examples/ – sample scripts demonstrating library usage.
Key insights from README
• Supports Muse 2016, Muse 2, Muse S via multiple backends.
• Two visualization options (basic & VisPy/MNE).
• Two recording modes: via LSL subscriber or direct low‑level capture.
• Designed for synchronous streaming; encourages separate processes for stream + view/record.
• CLI Frontend (“muselsl” commands)
• Core Library Modules
– MuseConnector (muse.py)
– BluetoothBackend (backends.py)
– StreamManager (stream.py)
– RecordManager (record.py)
– Viewer(s) (view.py, viewer_v1.py, viewer_v2.py)
• Lab Streaming Layer (LSL) – middleware bus
• Consumers
– muselsl view process(es)
– muselsl record process(es)
– third‑party LSL subscribers
• Optional External Services/Tools
– BlueMuse GUI on Windows
– EEG Notebooks experiments (via LSL Markers stream)
• Examples folder (as client‑side usage samples)
1. User invokes “muselsl stream” → CLI parses args → invokes StreamManager
2. StreamManager loads a BluetoothBackend → MuseConnector connects → data frames received
3. StreamManager publishes EEG (and optional ACC, GYRO, PPG, Markers) via LSL outlets
4. One or more consumer processes subscribe to those LSL streams:
– Viewer process(es) render in real time
– RecordManager writes to CSV
– External experiments or tools read Marker streams
5. Direct‐record mode bypasses LSL: Data from MuseConnector → RecordManager → CSV
c. Architectural patterns and design principles
– Modular backend interface for Bluetooth adapters (allows plugging in bleak, pygatt, bgapi)
– Clear separation of concerns:
• Connection & decoding (muse.py)
• Streaming vs. recording vs. visualizing
– Use of LSL as asynchronous message bus
– CLI → library split for reusability
– Example scripts demonstrating the public API
d. Relevant technologies and libraries
– Python 2.7 / 3.x, setuptools packaging
– Bluetooth backends: bleak (default), pygatt, BlueMuse, bgapi
– Lab Streaming Layer (pylsl) for interprocess data transport
– VisPy, MNE for the advanced viewer
– click or argparse (in cli.py) for CLI parsing