# alexandrebarachant/muse-lsl architecture

> Architecture diagram of the GitHub repository alexandrebarachant/muse-lsl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexandrebarachant/muse-lsl
- Repository: https://github.com/alexandrebarachant/muse-lsl

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend" 
        direction TB
        CLI_Main["__main__.py"]:::cli
        CLI_Cmd["cli.py"]:::cli
    end

    %% Core Library Modules
    subgraph "Core Library" 
        direction TB
        subgraph "Connection Layer"
            direction TB
            MuseConnector["MuseConnector\n(muse.py)"]:::core
            BluetoothBackend["BluetoothBackend\n(backends.py)"]:::core
        end
        subgraph "Streaming & Recording"
            direction TB
            StreamManager["StreamManager\n(stream.py)"]:::core
            RecordManager["RecordManager\n(record.py)"]:::core
        end
        subgraph "Visualization"
            direction TB
            Viewer["Viewer\n(view.py)"]:::core
            ViewerV1["ViewerV1\n(viewer_v1.py)"]:::core
            ViewerV2["ViewerV2\n(viewer_v2.py)"]:::core
        end
        subgraph "Utilities"
            direction TB
            Helper["helper.py"]:::core
            Constants["constants.py"]:::core
        end
    end

    %% Middleware
    LSL["Lab Streaming Layer\n(LSL)"]:::middleware

    %% Consumers
    subgraph "Consumers"
        direction TB
        ViewProc["View Process"]:::consumer
        RecordProc["Record Process"]:::consumer
        ExtSubs["3rd-Party LSL Subscribers"]:::consumer
    end

    %% Examples and Packaging
    subgraph "Examples & Packaging"
        direction TB
        Examples["examples/"]:::examples
        Setup["setup.py / setup.cfg"]:::pack
        Readme["README.md"]:::pack
        License["LICENSE.txt"]:::pack
    end

    %% Data Stores
    CSV["CSV File"]:::storage

    %% Connections
    CLI_Main -->|"invokes commands"| StreamManager
    CLI_Cmd -->|routes CLI| StreamManager
    StreamManager -->|"loads"| BluetoothBackend
    BluetoothBackend -->|"connects via BLE"| MuseConnector
    MuseConnector -->|"raw data frames"| StreamManager
    StreamManager -->|"publish LSL stream"| LSL
    LSL -->|subscribe| ViewProc
    LSL -->|subscribe| RecordProc
    LSL -->|subscribe| ExtSubs
    RecordManager -->|"direct data"| CSV
    CLI_Main -->|"invokes record"| RecordManager
    RecordManager -->|subscribe LSL| LSL

    %% Examples usage
    Examples -->|use public API| StreamManager
    Examples -->|use public API| RecordManager
    Examples -->|use public API| MuseConnector

    %% Click Events
    click CLI_Main "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/__main__.py"
    click CLI_Cmd "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/cli.py"
    click MuseConnector "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/muse.py"
    click BluetoothBackend "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/backends.py"
    click StreamManager "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/stream.py"
    click RecordManager "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/record.py"
    click Viewer "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/view.py"
    click ViewerV1 "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/viewer_v1.py"
    click ViewerV2 "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/viewer_v2.py"
    click Helper "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/helper.py"
    click Constants "https://github.com/alexandrebarachant/muse-lsl/blob/master/muselsl/constants.py"
    click Examples "https://github.com/alexandrebarachant/muse-lsl/tree/master/examples/"
    click Setup "https://github.com/alexandrebarachant/muse-lsl/blob/master/setup.py"
    click Readme "https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md"
    click License "https://github.com/alexandrebarachant/muse-lsl/blob/master/LICENSE.txt"

    %% Styles
    classDef cli fill:#a2d5c6,stroke:#333,stroke-width:1px
    classDef core fill:#87ceeb,stroke:#333,stroke-width:1px
    classDef middleware fill:#ffa500,stroke:#333,stroke-width:1px
    classDef consumer fill:#f9d56e,stroke:#333,stroke-width:1px
    classDef examples fill:#9fd8cb,stroke:#333,stroke-width:1px
    classDef pack fill:#b0c4de,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
```
