[](https://zenodo.org/badge/latestdoi/80209610)
# Muse LSL
A Python package for streaming, visualizing, and recording EEG data from the Muse devices developed by InteraXon.
## Requirements
The code relies on a number of different bluetooth backends for connecting to the muse. We recommend using the `bleak` backend (enabled by default), but you may be interested in [BlueMuse](https://github.com/kowalej/BlueMuse/tree/master/Dist) for a GUI to discover and connect to Muse devices on Windows or [bgapi] if you are on a Mac with a BLED112 dongle.
**Compatible with Python 2.7 and Python 3.x**
**Compatible with Muse 2, Muse S, and the classic Muse (2016)**
_Note: if you run into any issues, first check out out [Common Issues](#common-issues) and then the [Issues](https://github.com/alexandrebarachant/muse-lsl/issues) section of this repository_
## Getting Started
### Installation
Install Muse LSL with pip
pip install muselsl
### Setting Up a Stream
On Windows 10, we recommend using the [BlueMuse](https://github.com/kowalej/BlueMuse/tree/master/Dist) GUI to set up an LSL stream. On Mac and Linux, the easiest way to get Muse data is to use Muse LSL directly from the command line. Use the `-h` flag to get a comprehensive list of all commands and options.
To print a list of available muses:
$ muselsl list
To begin an LSL stream from the first available Muse:
$ muselsl stream
To connect to a specific Muse you can pass the name of the device as an argument. Device names can be found on the inside of the left earpiece (e.g. Muse-41D2):
$ muselsl stream --name YOUR_DEVICE_NAME
You can also directly pass the MAC address of your Muse. This provides the benefit of bypassing the device discovery step and can make connecting to devices quicker and more reliable:
$ muselsl stream --address YOUR_DEVICE_ADDRESS
### Working with Streaming Data
Once an LSL stream is created, you have access to the following commands.
*Note: the process running the `stream` command must be kept alive in order to maintain the LSL stream. These following commands should be run in another terminal or second process*
To view data:
$ muselsl view
If the visualization freezes or is laggy, you can also try the alternate version 2 of the viewer. *Note: this will require the additional [vispy](https://github.com/vispy/vispy) and [mne](https://github.com/mne-tools/mne-python) dependencies*
$ muselsl view --version 2
To record EEG data into a CSV:
$ muselsl record --duration 60
*Note: this command will also save data from any LSL stream containing 'Markers' data, such as from the stimulus presentation scripts in [EEG Notebooks](https://github.com/neurotechx/eeg-notebooks)*
Alternatively, you can record data directly without using LSL through the following command:
$ muselsl record_direct --duration 60
_Note: direct recording does not allow 'Markers' data to be recorded_
## Running Experiments
Muse LSL was designed so that the Muse could be used to run a number of classic EEG experiments, including the [P300 event-related potential](http://alexandre.barachant.org/blog/2017/02/05/P300-with-muse.html) and the SSVEP and SSAEP evoked potentials.
The code to perform these experiments is still available, but is now maintained in the [EEG Notebooks](https://github.com/neurotechx/eeg-notebooks) repository by the [NeuroTechX](https://neurotechx.com) community.
## Usage as a Library
If you want to integrate Muse LSL into your own Python project, you can import and use its functions as you would any Python library. Examples are available in the `examples` folder:
```Python
from muselsl import stream, list_muses
muses = list_muses()
stream(muses[0]['address'])
# Note: Streaming is synchronous, so code here will not execute until after the stream has been closed
print('Stream has ended')
```
## Alternate Data Types
In addition to EEG, the Muse also provides data from an accelerometer, gyroscope, and, in the case of the Muse 2, a photoplethysmography (PPG) sensor. These data types can be enabled via command line arguments or by passing the correct parameters to the `stream` function. Once enabled, PPG, accelerometer, and gyroscope data will streamed in their own separate LSL streams named "PPG", "ACC", and "GYRO", respectively.
To stream data from all sensors in a Muse 2 from the command line:
muselsl stream --ppg --acc --gyro
As a library function:
```Python
from muselsl import stream, list_muses
muses = list_muses()
stream(muses[0]['address'], ppg_enabled=True, acc_enabled=True, gyro_enabled=True)
```
To record data from an alternate data source:
muselsl record --type ACC
*Note: The record process will only record from one data type at a time. However, multiple terminals or processes can be used to record from multiple data types simultaneously*
## What is LSL?
Lab Streaming Layer or LSL is a system designed to unify the collection of time series data for research experiments. It has become standard in the field of EEG-based brain-computer interfaces for its ability to make seperate streams of data available on a network with time synchronization and near real-time access. For more information, check out this [lecture from Modern Brain-Computer Interface Design](https://www.youtube.com/watch?v=Y1at7yrcFW0) or the [LSL repository](https://github.com/sccn/labstreaminglayer)
## Common Issues
### Mac and Windows
1. Connection issues with BLED112 dongle:
- You may need to use the `--interface` argument to provide the appropriate COM port value for the BLED112 device. The default value is COM9. To setup or view the device's COM port go to your OS's system settings
### Linux
1. `pygatt.exceptions.BLEError: Unexpected error when scanning: Set scan parameters failed: Operation not permitted` (Linux)
- This is an issue with pygatt requiring root privileges to run a scan. Make sure you [have `libcap` installed](https://askubuntu.com/questions/347788/how-can-i-install-libpcap-header-files-on-ubuntu-12-04) and run `` sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hcitool` ``
2. `pygatt.exceptions.BLEError: No characteristic found matching 273e0003-4c4d-454d-96be-f03bac821358` (Linux)
- There is a problem with the most recent version of pygatt. Work around this by downgrading to 3.1.1: `pip install pygatt==3.1.1`
3. `pygatt.exceptions.BLEError: No BLE adapter found` (Linux)
- Make sure your computer's Bluetooth is turned on.
4. `pygatt.exceptions.BLEError: Unexpected error when scanning: Set scan parameters failed: Connection timed out` (Linux)
- This seems to be due to a OS-level Bluetooth crash. Try turning your computer's bluetooth off and on again
5. `'RuntimeError: could not create stream outlet'` (Linux)
- This appears to be due to Linux-specific issues with the newest version of pylsl. Ensure that you have pylsl 1.10.5 installed in the environment in which you are trying to run Muse LSL
- If this is preceded by `Could not instantiate IPv4 stack: getrandom`, it could be [this issue](https://github.com/boostorg/uuid/issues/91) which can be resolved by building `liblsl` with `-DBOOST_UUID_RANDOM_PROVIDER_FORCE_POSIX` (e.g. by editing `standalone_compilation_linux.sh`)
## Citing muse-lsl
```
@misc{muse-lsl,
author = {Alexandre Barachant and
Dano Morrison and
Hubert Banville and
Jason Kowaleski and
Uri Shaked and
Sylvain Chevallier and
Juan Jesús Torre Tresols},
title = {muse-lsl},
month = may,
year = 2019,
doi = {10.5281/zenodo.3228861},
url = {https://doi.org/10.5281/zenodo.3228861}
}
```
> Alexandre Barachant, Dano Morrison, Hubert Banville, Jason Kowaleski, Uri Shaked, Sylvain Chevallier, & Juan Jesús Torre Tresols. (2019, May 25). muse-lsl (Version v2.0.2). Zenodo. http://doi.org/10.5281/zenodo.3228861
Raw data
{
"_id": null,
"home_page": "https://github.com/alexandrebarachant/muse-lsl/",
"name": "muselsl",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "muse lsl eeg ble neuroscience",
"author": "Alexandre Barachant",
"author_email": "alexandre.barachant@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e0/90/840224238683022b5b7613195ce5b176e01a0e14fae5c9ec2b8331c9217d/muselsl-2.3.1.tar.gz",
"platform": null,
"description": "\n[](https://zenodo.org/badge/latestdoi/80209610)\n\n# Muse LSL\n\nA Python package for streaming, visualizing, and recording EEG data from the Muse devices developed by InteraXon.\n\n\n\n## Requirements\n\nThe code relies on a number of different bluetooth backends for connecting to the muse. We recommend using the `bleak` backend (enabled by default), but you may be interested in [BlueMuse](https://github.com/kowalej/BlueMuse/tree/master/Dist) for a GUI to discover and connect to Muse devices on Windows or [bgapi] if you are on a Mac with a BLED112 dongle. \n\n**Compatible with Python 2.7 and Python 3.x**\n\n**Compatible with Muse 2, Muse S, and the classic Muse (2016)**\n\n_Note: if you run into any issues, first check out out [Common Issues](#common-issues) and then the [Issues](https://github.com/alexandrebarachant/muse-lsl/issues) section of this repository_\n\n## Getting Started\n\n### Installation\n\nInstall Muse LSL with pip\n\n pip install muselsl\n\n### Setting Up a Stream\n\nOn Windows 10, we recommend using the [BlueMuse](https://github.com/kowalej/BlueMuse/tree/master/Dist) GUI to set up an LSL stream. On Mac and Linux, the easiest way to get Muse data is to use Muse LSL directly from the command line. Use the `-h` flag to get a comprehensive list of all commands and options.\n\nTo print a list of available muses:\n\n $ muselsl list\n\nTo begin an LSL stream from the first available Muse:\n\n $ muselsl stream \n\nTo connect to a specific Muse you can pass the name of the device as an argument. Device names can be found on the inside of the left earpiece (e.g. Muse-41D2):\n\n $ muselsl stream --name YOUR_DEVICE_NAME\n\nYou can also directly pass the MAC address of your Muse. This provides the benefit of bypassing the device discovery step and can make connecting to devices quicker and more reliable:\n\n $ muselsl stream --address YOUR_DEVICE_ADDRESS\n\n### Working with Streaming Data\n\nOnce an LSL stream is created, you have access to the following commands.\n\n*Note: the process running the `stream` command must be kept alive in order to maintain the LSL stream. These following commands should be run in another terminal or second process*\n\nTo view data:\n\n $ muselsl view\n\nIf the visualization freezes or is laggy, you can also try the alternate version 2 of the viewer. *Note: this will require the additional [vispy](https://github.com/vispy/vispy) and [mne](https://github.com/mne-tools/mne-python) dependencies*\n\n $ muselsl view --version 2\n\nTo record EEG data into a CSV:\n\n $ muselsl record --duration 60 \n\n*Note: this command will also save data from any LSL stream containing 'Markers' data, such as from the stimulus presentation scripts in [EEG Notebooks](https://github.com/neurotechx/eeg-notebooks)*\n\nAlternatively, you can record data directly without using LSL through the following command:\n\n $ muselsl record_direct --duration 60\n\n_Note: direct recording does not allow 'Markers' data to be recorded_\n\n## Running Experiments\n\nMuse LSL was designed so that the Muse could be used to run a number of classic EEG experiments, including the [P300 event-related potential](http://alexandre.barachant.org/blog/2017/02/05/P300-with-muse.html) and the SSVEP and SSAEP evoked potentials.\n\nThe code to perform these experiments is still available, but is now maintained in the [EEG Notebooks](https://github.com/neurotechx/eeg-notebooks) repository by the [NeuroTechX](https://neurotechx.com) community.\n\n## Usage as a Library\n\nIf you want to integrate Muse LSL into your own Python project, you can import and use its functions as you would any Python library. Examples are available in the `examples` folder:\n\n```Python\nfrom muselsl import stream, list_muses\n\nmuses = list_muses()\nstream(muses[0]['address'])\n\n# Note: Streaming is synchronous, so code here will not execute until after the stream has been closed\nprint('Stream has ended')\n```\n\n## Alternate Data Types\n\nIn addition to EEG, the Muse also provides data from an accelerometer, gyroscope, and, in the case of the Muse 2, a photoplethysmography (PPG) sensor. These data types can be enabled via command line arguments or by passing the correct parameters to the `stream` function. Once enabled, PPG, accelerometer, and gyroscope data will streamed in their own separate LSL streams named \"PPG\", \"ACC\", and \"GYRO\", respectively.\n\nTo stream data from all sensors in a Muse 2 from the command line:\n\n muselsl stream --ppg --acc --gyro\n\nAs a library function:\n\n```Python\nfrom muselsl import stream, list_muses\n\nmuses = list_muses()\nstream(muses[0]['address'], ppg_enabled=True, acc_enabled=True, gyro_enabled=True)\n```\n\nTo record data from an alternate data source:\n\n muselsl record --type ACC\n\n*Note: The record process will only record from one data type at a time. However, multiple terminals or processes can be used to record from multiple data types simultaneously*\n\n## What is LSL?\n\nLab Streaming Layer or LSL is a system designed to unify the collection of time series data for research experiments. It has become standard in the field of EEG-based brain-computer interfaces for its ability to make seperate streams of data available on a network with time synchronization and near real-time access. For more information, check out this [lecture from Modern Brain-Computer Interface Design](https://www.youtube.com/watch?v=Y1at7yrcFW0) or the [LSL repository](https://github.com/sccn/labstreaminglayer)\n\n## Common Issues\n\n### Mac and Windows\n\n1. Connection issues with BLED112 dongle:\n\n- You may need to use the `--interface` argument to provide the appropriate COM port value for the BLED112 device. The default value is COM9. To setup or view the device's COM port go to your OS's system settings\n\n### Linux\n\n1. `pygatt.exceptions.BLEError: Unexpected error when scanning: Set scan parameters failed: Operation not permitted` (Linux)\n\n- This is an issue with pygatt requiring root privileges to run a scan. Make sure you [have `libcap` installed](https://askubuntu.com/questions/347788/how-can-i-install-libpcap-header-files-on-ubuntu-12-04) and run `` sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hcitool` ``\n\n2. `pygatt.exceptions.BLEError: No characteristic found matching 273e0003-4c4d-454d-96be-f03bac821358` (Linux)\n\n- There is a problem with the most recent version of pygatt. Work around this by downgrading to 3.1.1: `pip install pygatt==3.1.1`\n\n3. `pygatt.exceptions.BLEError: No BLE adapter found` (Linux)\n\n- Make sure your computer's Bluetooth is turned on.\n\n4. `pygatt.exceptions.BLEError: Unexpected error when scanning: Set scan parameters failed: Connection timed out` (Linux)\n\n- This seems to be due to a OS-level Bluetooth crash. Try turning your computer's bluetooth off and on again\n\n5. `'RuntimeError: could not create stream outlet'` (Linux)\n\n- This appears to be due to Linux-specific issues with the newest version of pylsl. Ensure that you have pylsl 1.10.5 installed in the environment in which you are trying to run Muse LSL\n- If this is preceded by `Could not instantiate IPv4 stack: getrandom`, it could be [this issue](https://github.com/boostorg/uuid/issues/91) which can be resolved by building `liblsl` with `-DBOOST_UUID_RANDOM_PROVIDER_FORCE_POSIX` (e.g. by editing `standalone_compilation_linux.sh`)\n\n## Citing muse-lsl\n\n```\n@misc{muse-lsl,\n author = {Alexandre Barachant and\n Dano Morrison and\n Hubert Banville and\n Jason Kowaleski and\n Uri Shaked and\n Sylvain Chevallier and\n Juan Jes\u00fas Torre Tresols},\n title = {muse-lsl},\n month = may,\n year = 2019,\n doi = {10.5281/zenodo.3228861},\n url = {https://doi.org/10.5281/zenodo.3228861}\n}\n```\n\n> Alexandre Barachant, Dano Morrison, Hubert Banville, Jason Kowaleski, Uri Shaked, Sylvain Chevallier, & Juan Jes\u00fas Torre Tresols. (2019, May 25). muse-lsl (Version v2.0.2). Zenodo. http://doi.org/10.5281/zenodo.3228861\n",
"bugtrack_url": null,
"license": "BSD (3-clause)",
"summary": "Stream and visualize EEG data from the Muse headset.",
"version": "2.3.1",
"project_urls": {
"Homepage": "https://github.com/alexandrebarachant/muse-lsl/"
},
"split_keywords": [
"muse",
"lsl",
"eeg",
"ble",
"neuroscience"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e05aeb1610697dcf87366a37a15a635821ec9ab4993535b46ff134a9f31e2a2",
"md5": "7c9a38390a02f1c486616d79ff750bad",
"sha256": "a0f9349fb2e5ed107e551c7fa7cd7a537d6f2161dee6bc82a5c8e5744bcf09e7"
},
"downloads": -1,
"filename": "muselsl-2.3.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c9a38390a02f1c486616d79ff750bad",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 32960,
"upload_time": "2024-06-02T18:42:26",
"upload_time_iso_8601": "2024-06-02T18:42:26.001699Z",
"url": "https://files.pythonhosted.org/packages/3e/05/aeb1610697dcf87366a37a15a635821ec9ab4993535b46ff134a9f31e2a2/muselsl-2.3.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e090840224238683022b5b7613195ce5b176e01a0e14fae5c9ec2b8331c9217d",
"md5": "03a2c56e44f8efb9d65ae9144ff2d3cf",
"sha256": "359e23c8e16b1fa42d64776f67ea9f4863916de9952df99ed5b3eb7ba5a1ed89"
},
"downloads": -1,
"filename": "muselsl-2.3.1.tar.gz",
"has_sig": false,
"md5_digest": "03a2c56e44f8efb9d65ae9144ff2d3cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 129170,
"upload_time": "2024-06-02T18:42:27",
"upload_time_iso_8601": "2024-06-02T18:42:27.771202Z",
"url": "https://files.pythonhosted.org/packages/e0/90/840224238683022b5b7613195ce5b176e01a0e14fae5c9ec2b8331c9217d/muselsl-2.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-02 18:42:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexandrebarachant",
"github_project": "muse-lsl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "muselsl"
}
JSON
