# pylsl
[](https://badge.fury.io/py/pylsl)
This is the Python interface to the [Lab Streaming Layer (LSL)](https://github.com/sccn/labstreaminglayer).
LSL is an overlay network for real-time exchange of time series between applications,
most often used in research environments. LSL has clients for many other languages
and platforms that are compatible with each other.
Let us know if you encounter any bugs (ideally using the issue tracker on
the GitHub project).
# Installation
## Prerequisites
On all non-Windows platforms and for some Windows-Python combinations, you must first obtain a liblsl shared library. See the [liblsl repo documentation](https://github.com/sccn/liblsl) for further details.
## Get pylsl from PyPI
* `pip install pylsl`
## Get pylsl from source
This should only be necessary if you need to modify or debug pylsl.
* Download the pylsl source: `git clone https://github.com/labstreaminglayer/pylsl.git && cd pylsl`
* From the `pylsl` working directory, run `pip install .`.
* Note: You can use `pip install -e .` to install while keeping the files in-place. This is convenient for developing pylsl.
# Usage
See the examples in pylsl/examples. Note that these can be run directly from the commandline with (e.g.) `python -m pylsl.examples.{name-of-example}`.
You can get a list of the examples with `python -c "import pylsl.examples; help(pylsl.examples)"`
## liblsl loading
`pylsl` will search for `liblsl` first at the filepath specified by an environment variable named `PYLSL_LIB`, then in the package directory (default location for Windows), then finally in normal system library folders.
If the shared object is not installed onto a standard search path (or it is but can't be found for some [other bug](https://github.com/labstreaminglayer/pylsl/issues/48)), then we recommend that you copy it to the pylsl installed module path's `lib` subfolder. i.e. `{path/to/env/}site-packages/pylsl/lib`.
* The `site-packages/pylsl` path will only exist _after_ you install `pylsl` in your Python environment.
* You may have to create the `lib` subfolder.
* Use `python -m site` to find the "site-packages" path.
* Use `cp -L` on platforms that use symlinks.
Alternatively, you can use an environment variable. Set the `PYLSL_LIB` environment variable to the location of the library or set `LD_LIBRARY_PATH` to the folder containing the library. For example,
1. `PYLSL_LIB=/usr/local/lib/liblsl.so python -m pylsl.examples.{name-of-example}`, or
2. `LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib python -m pylsl.examples.{name-of-example}`
# For maintainers
## Continuous Integration
pylsl uses continuous integration and distribution. GitHub Actions will upload a new release to pypi whenever a Release is created in GitHub.
Before creating the GitHub release, be sure to bump the version number in `pylsl/version.py` and consider updating the liblsl dependency
in `.github/workflows/publish-to-pypi.yml`.
### Linux Binaries Deprecated
We recently stopped building binary wheels for Linux. In practice, the `manylinux` dependencies were often incompatible with real systems.
## Manual Distribution
1. Manual way:
1. `rm -Rf build dist *.egg-info`
1. `python setup.py sdist bdist_wheel`
1. Additional steps on Linux:
* `auditwheel repair dist/*.whl -w dist`
* `rm dist/*-linux_x86_64.whl`
1. `twine upload dist/*`
1. For conda
1. build liblsl: `conda build ../liblsl/`
1. `conda build .`
# Known Issues with Multithreading on Linux
* At least for some versions of pylsl, it has been reported that running on Linux one cannot call ``pylsl`` functions from a thread that is not the main thread. This has been reported to cause access violations, and can occur during pulling from an inlet, and also from accessing an inlets info structure in a thread.
* Recent tests with multithreading (especially when safeguarding library calls with locks) using Python 3.7.6. with pylsl 1.14 on Linux Mint 20 suggest that this issue is solved, or at least depends on your machine. See https://github.com/labstreaminglayer/pylsl/issues/29
# Acknowledgments
Pylsl was primarily written by Christian Kothe while at Swartz Center for Computational Neuroscience, UCSD. The LSL project was funded by the Army Research Laboratory under Cooperative Agreement Number W911NF-10-2-0022 as well as through NINDS grant 3R01NS047293-06S1. pylsl is maintained primarily by Chadwick Boulay. Thanks for contributions, bug reports, and suggestions go to Bastian Venthur, David Medine, Clemens Brunner, and Matthew Grivich.
Raw data
{
"_id": null,
"home_page": null,
"name": "pylsl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "networking, LSL, Lab Streaming Layer, labstreaminglayer, data, acquisition, stream",
"author": null,
"author_email": "Christian Kothe <christian.kothe@intheon.io>, Chadwick Boulay <chadwick.boulay@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/fd/2cb39e07d09f3aa40bc39d880adcc8bfa08fc9b8de993340e6a7555899f8/pylsl-1.17.6.tar.gz",
"platform": null,
"description": "# pylsl\n\n\n[](https://badge.fury.io/py/pylsl)\n\nThis is the Python interface to the [Lab Streaming Layer (LSL)](https://github.com/sccn/labstreaminglayer).\nLSL is an overlay network for real-time exchange of time series between applications,\nmost often used in research environments. LSL has clients for many other languages\nand platforms that are compatible with each other.\n\nLet us know if you encounter any bugs (ideally using the issue tracker on\nthe GitHub project).\n\n# Installation\n\n## Prerequisites\n\nOn all non-Windows platforms and for some Windows-Python combinations, you must first obtain a liblsl shared library. See the [liblsl repo documentation](https://github.com/sccn/liblsl) for further details.\n\n## Get pylsl from PyPI\n\n* `pip install pylsl`\n\n## Get pylsl from source\n\nThis should only be necessary if you need to modify or debug pylsl.\n\n* Download the pylsl source: `git clone https://github.com/labstreaminglayer/pylsl.git && cd pylsl`\n* From the `pylsl` working directory, run `pip install .`.\n * Note: You can use `pip install -e .` to install while keeping the files in-place. This is convenient for developing pylsl.\n\n# Usage\n\nSee the examples in pylsl/examples. Note that these can be run directly from the commandline with (e.g.) `python -m pylsl.examples.{name-of-example}`.\n\nYou can get a list of the examples with `python -c \"import pylsl.examples; help(pylsl.examples)\"`\n\n## liblsl loading\n\n`pylsl` will search for `liblsl` first at the filepath specified by an environment variable named `PYLSL_LIB`, then in the package directory (default location for Windows), then finally in normal system library folders.\n\nIf the shared object is not installed onto a standard search path (or it is but can't be found for some [other bug](https://github.com/labstreaminglayer/pylsl/issues/48)), then we recommend that you copy it to the pylsl installed module path's `lib` subfolder. i.e. `{path/to/env/}site-packages/pylsl/lib`.\n\n* The `site-packages/pylsl` path will only exist _after_ you install `pylsl` in your Python environment.\n* You may have to create the `lib` subfolder.\n* Use `python -m site` to find the \"site-packages\" path.\n* Use `cp -L` on platforms that use symlinks.\n\nAlternatively, you can use an environment variable. Set the `PYLSL_LIB` environment variable to the location of the library or set `LD_LIBRARY_PATH` to the folder containing the library. For example,\n\n1. `PYLSL_LIB=/usr/local/lib/liblsl.so python -m pylsl.examples.{name-of-example}`, or\n2. `LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib python -m pylsl.examples.{name-of-example}`\n\n# For maintainers\n\n## Continuous Integration\n\npylsl uses continuous integration and distribution. GitHub Actions will upload a new release to pypi whenever a Release is created in GitHub.\nBefore creating the GitHub release, be sure to bump the version number in `pylsl/version.py` and consider updating the liblsl dependency\nin `.github/workflows/publish-to-pypi.yml`.\n\n### Linux Binaries Deprecated\n\nWe recently stopped building binary wheels for Linux. In practice, the `manylinux` dependencies were often incompatible with real systems.\n\n## Manual Distribution\n\n1. Manual way:\n 1. `rm -Rf build dist *.egg-info`\n 1. `python setup.py sdist bdist_wheel`\n 1. Additional steps on Linux:\n * `auditwheel repair dist/*.whl -w dist`\n * `rm dist/*-linux_x86_64.whl`\n 1. `twine upload dist/*`\n1. For conda\n 1. build liblsl: `conda build ../liblsl/`\n 1. `conda build .`\n\n# Known Issues with Multithreading on Linux\n\n* At least for some versions of pylsl, it has been reported that running on Linux one cannot call ``pylsl`` functions from a thread that is not the main thread. This has been reported to cause access violations, and can occur during pulling from an inlet, and also from accessing an inlets info structure in a thread.\n* Recent tests with multithreading (especially when safeguarding library calls with locks) using Python 3.7.6. with pylsl 1.14 on Linux Mint 20 suggest that this issue is solved, or at least depends on your machine. See https://github.com/labstreaminglayer/pylsl/issues/29\n\n# Acknowledgments\n\nPylsl was primarily written by Christian Kothe while at Swartz Center for Computational Neuroscience, UCSD. The LSL project was funded by the Army Research Laboratory under Cooperative Agreement Number W911NF-10-2-0022 as well as through NINDS grant 3R01NS047293-06S1. pylsl is maintained primarily by Chadwick Boulay. Thanks for contributions, bug reports, and suggestions go to Bastian Venthur, David Medine, Clemens Brunner, and Matthew Grivich.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for importing XDF (Extensible Data Format)",
"version": "1.17.6",
"project_urls": {
"Issues": "https://github.com/labstreaminglayer/pylsl/issues",
"Repository": "https://github.com/labstreaminglayer/pylsl"
},
"split_keywords": [
"networking",
" lsl",
" lab streaming layer",
" labstreaminglayer",
" data",
" acquisition",
" stream"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9afa38f3ec8ac9073e53c65d850d8d6f51cbb87dbfcb59db5215fe7c7584e6e5",
"md5": "dbe94d72717aa632ca5a6c653d943938",
"sha256": "78d935d3d944cd572464f6200fcdf3958866b2e3180dea3da83e43a19517acf5"
},
"downloads": -1,
"filename": "pylsl-1.17.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbe94d72717aa632ca5a6c653d943938",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 41775,
"upload_time": "2024-12-13T20:14:10",
"upload_time_iso_8601": "2024-12-13T20:14:10.525729Z",
"url": "https://files.pythonhosted.org/packages/9a/fa/38f3ec8ac9073e53c65d850d8d6f51cbb87dbfcb59db5215fe7c7584e6e5/pylsl-1.17.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5a8d0c8818c1a8aecc2a09d9f5df92b0bd321bd73f780c4928ccf0d5952951ad",
"md5": "45cddebd1ee7248acca87e60487fcf9d",
"sha256": "d9a68e86a073b59582b697c2baf1757b067da155e5fb017e30cefb7aa6d22f6d"
},
"downloads": -1,
"filename": "pylsl-1.17.6-py2.py3-none-win32.whl",
"has_sig": false,
"md5_digest": "45cddebd1ee7248acca87e60487fcf9d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 293781,
"upload_time": "2024-12-13T20:14:29",
"upload_time_iso_8601": "2024-12-13T20:14:29.628985Z",
"url": "https://files.pythonhosted.org/packages/5a/8d/0c8818c1a8aecc2a09d9f5df92b0bd321bd73f780c4928ccf0d5952951ad/pylsl-1.17.6-py2.py3-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "92a9b24df99c2dcb128a404dff05a592aa457763d45274c793395919b9b120a6",
"md5": "744472c06c782a006cec97f030f39738",
"sha256": "a5ead3e28ccdd7a08a6523adc797d6f737a1e446f684a8bd4818d784b50d89ba"
},
"downloads": -1,
"filename": "pylsl-1.17.6-py2.py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "744472c06c782a006cec97f030f39738",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 364212,
"upload_time": "2024-12-13T20:14:24",
"upload_time_iso_8601": "2024-12-13T20:14:24.111511Z",
"url": "https://files.pythonhosted.org/packages/92/a9/b24df99c2dcb128a404dff05a592aa457763d45274c793395919b9b120a6/pylsl-1.17.6-py2.py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3ffd2cb39e07d09f3aa40bc39d880adcc8bfa08fc9b8de993340e6a7555899f8",
"md5": "6af10b78e88f4af15a11e1dccd121b14",
"sha256": "8f3cea0c54a27785a43a27e9524f1dee885fe149f4703eed060168923b1695a3"
},
"downloads": -1,
"filename": "pylsl-1.17.6.tar.gz",
"has_sig": false,
"md5_digest": "6af10b78e88f4af15a11e1dccd121b14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 39856,
"upload_time": "2024-12-13T20:14:12",
"upload_time_iso_8601": "2024-12-13T20:14:12.725196Z",
"url": "https://files.pythonhosted.org/packages/3f/fd/2cb39e07d09f3aa40bc39d880adcc8bfa08fc9b8de993340e6a7555899f8/pylsl-1.17.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 20:14:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "labstreaminglayer",
"github_project": "pylsl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pylsl"
}
JSON
