@neurodevs/node-lsl 8.0.6 → 8.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -1
- package/package.json +17 -17
package/README.md
CHANGED
|
@@ -1,2 +1,131 @@
|
|
|
1
1
|
# node-lsl
|
|
2
|
-
Lab Streaming Layer (LSL) for synchronized streaming of multi-modal, time-series data over a network
|
|
2
|
+
Lab Streaming Layer (LSL) for synchronized streaming of multi-modal, time-series data over a network.
|
|
3
|
+
|
|
4
|
+
## Table of Contents
|
|
5
|
+
- [Overview](#overview)
|
|
6
|
+
- [Installation](#installation)
|
|
7
|
+
- [Usage](#usage)
|
|
8
|
+
- [LslOutlet](#lsloutlet)
|
|
9
|
+
- [TimeMarkerOutlet](#timemarkeroutlet)
|
|
10
|
+
- [Test Doubles](#test-doubles)
|
|
11
|
+
|
|
12
|
+
## Overview
|
|
13
|
+
|
|
14
|
+
This package is a Node wrapper around the C++ [liblsl](https://github.com/sccn/liblsl) library. It was developed and tested on a MacOS system with an M2 chip. It should work with any M-series chip: M1, M2, M3. There are known issues for this package with x86 MacOS architectures. It's untested for Windows or Linux.
|
|
15
|
+
|
|
16
|
+
Please note that this package currently only supports LSL outlets (sending data over a network). It does not yet support LSL inlets (receiving data from a network).
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
First, you need to install the C++ [liblsl](https://github.com/sccn/liblsl) library. On MacOS, you can use Homebrew to install it, as specified in its [documentation](https://github.com/sccn/liblsl?tab=readme-ov-file#getting-and-using-liblsl):
|
|
21
|
+
|
|
22
|
+
`brew install labstreaminglayer/tap/lsl`
|
|
23
|
+
|
|
24
|
+
Then, install the package with your preferred package manager (make sure to be in the right directory for your Node project):
|
|
25
|
+
|
|
26
|
+
`npm install @neurodevs/node-lsl`
|
|
27
|
+
|
|
28
|
+
or
|
|
29
|
+
|
|
30
|
+
`yarn add @neurodevs/node-lsl`
|
|
31
|
+
|
|
32
|
+
Finally, add the following to your .env file or otherwise set it as an environmental variable. Update the path to match your system:
|
|
33
|
+
|
|
34
|
+
```.env
|
|
35
|
+
LIBLSL_PATH=/opt/homebrew/Cellar/lsl/1.16.2/lib/liblsl.1.16.2.dylib
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Usage
|
|
39
|
+
|
|
40
|
+
### LslOutlet
|
|
41
|
+
|
|
42
|
+
LSL is often used to stream EEG data over a network. For example, to instantiate an LSL outlet for the [Muse S 2nd generation](https://choosemuse.com/products/muse-s-gen-2) headband:
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
import { LslOutletImpl } from '@neurodevs/node-lsl'
|
|
46
|
+
|
|
47
|
+
const outlet = LslOutletImpl.Outlet({
|
|
48
|
+
name: 'Muse S (2nd gen)',
|
|
49
|
+
type: 'EEG',
|
|
50
|
+
channelNames: ['TP9', 'AF7', 'AF8', 'TP10', 'AUX'],
|
|
51
|
+
sampleRate: 256,
|
|
52
|
+
channelFormat: 'float32',
|
|
53
|
+
sourceId: 'muse-s-eeg',
|
|
54
|
+
manufacturer: 'Interaxon Inc.',
|
|
55
|
+
unit: 'microvolt',
|
|
56
|
+
chunkSize: 12,
|
|
57
|
+
maxBuffered: 360,
|
|
58
|
+
})
|
|
59
|
+
|
|
60
|
+
// Must be in async function
|
|
61
|
+
await outlet.pushSample(...)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### TimeMarkerOutlet
|
|
65
|
+
|
|
66
|
+
LSL is also often used to push time markers that mark different phases of an experiment or session:
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import { TimeMarkerOutletImpl } from '@neurodevs/node-lsl'
|
|
70
|
+
|
|
71
|
+
const outlet = TimeMarkerOutletImpl.Outlet()
|
|
72
|
+
|
|
73
|
+
// Must be in async function
|
|
74
|
+
await outlet.pushSample('phase-1-begin')
|
|
75
|
+
|
|
76
|
+
// Wait for phase to end
|
|
77
|
+
|
|
78
|
+
await outlet.pushSample('phase-1-end')
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
There is also a `pushMarkers` method that pushes a time marker, waits for a specified duration, then pushes the next marker. I recommend that each time marker has a duration of at least 100 ms so that LSL receives the markers in the right order.
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
const markers = [
|
|
85
|
+
{ name: 'phase-1-begin', durationMs: 30 * 1000 },
|
|
86
|
+
{ name: 'phase-1-end', durationMs: 0.1 * 1000 },
|
|
87
|
+
{ name: 'phase-2-begin', durationMs: 60 * 1000 },
|
|
88
|
+
...
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
// Must be in async function, hangs until complete
|
|
92
|
+
await outlet.pushMarkers(markers)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
If you then want to stop the time marker outlet early, you simply do:
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
outlet.stop()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
You can optionally pass any LslOutlet options to the time marker outlet during instantiation. For example, if you want to override the type:
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
import { TimeMarkerOutletImpl } from '@neurodevs/node-lsl'
|
|
105
|
+
|
|
106
|
+
const outlet = TimeMarkerOutletImpl.Outlet({
|
|
107
|
+
type: 'custom-type'
|
|
108
|
+
})
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Test Doubles
|
|
112
|
+
|
|
113
|
+
This package was developed using test-driven development (TDD). If you also follow TDD, you'll likely want test doubles to fake or mock certain behaviors for these classes.
|
|
114
|
+
|
|
115
|
+
For example, the `MockTimeMarkerOutlet` class lets you test whether your application appropriately calls its methods without actually doing anything. Set this mock in your test code like this:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
import { TimeMarkerOutletImpl, MockTimeMarkerOutlet } from '@neurodevs/node-lsl'
|
|
119
|
+
|
|
120
|
+
// In your tests / beforeEach
|
|
121
|
+
TimeMarkerOutletImpl.Class = MockTimeMarkerOutlet
|
|
122
|
+
|
|
123
|
+
const mock = TimeMarkerOutletImpl.Outlet()
|
|
124
|
+
|
|
125
|
+
// Do something in your application that should start the outlet
|
|
126
|
+
|
|
127
|
+
const expectedMarkers = ['phase-1-begin', ...]
|
|
128
|
+
mock.assertDidPushSamples(expectedMarkers)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Now, you'll have a failing test. There will be a helpful error message to guide you towards the solution. Basically, you just need to call the `pushSample` method in your application with the expected markers. See examples above for how to do so.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@neurodevs/node-lsl",
|
|
3
|
-
"version": "8.0.
|
|
3
|
+
"version": "8.0.8",
|
|
4
4
|
"main": "build/index.js",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -31,22 +31,22 @@
|
|
|
31
31
|
"test.rs": "node build/test.js"
|
|
32
32
|
},
|
|
33
33
|
"devDependencies": {
|
|
34
|
-
"@sprucelabs/jest-json-reporter": "^8.0.
|
|
35
|
-
"@sprucelabs/resolve-path-aliases": "^2.0.
|
|
36
|
-
"@sprucelabs/test": "^9.0.
|
|
37
|
-
"@sprucelabs/test-utils": "^5.1.
|
|
34
|
+
"@sprucelabs/jest-json-reporter": "^8.0.346",
|
|
35
|
+
"@sprucelabs/resolve-path-aliases": "^2.0.324",
|
|
36
|
+
"@sprucelabs/test": "^9.0.45",
|
|
37
|
+
"@sprucelabs/test-utils": "^5.1.291",
|
|
38
38
|
"@types/ffi-napi": "^4.0.10",
|
|
39
|
-
"@types/node": "^
|
|
39
|
+
"@types/node": "^22.5.4",
|
|
40
40
|
"chokidar-cli": "^3.0.0",
|
|
41
|
-
"concurrently": "^
|
|
42
|
-
"eslint": "^9.
|
|
43
|
-
"eslint-config-spruce": "^11.2.
|
|
41
|
+
"concurrently": "^9.0.1",
|
|
42
|
+
"eslint": "^9.10.0",
|
|
43
|
+
"eslint-config-spruce": "^11.2.26",
|
|
44
44
|
"jest": "^29.7.0",
|
|
45
45
|
"jest-circus": "^29.7.0",
|
|
46
|
-
"prettier": "^3.3.
|
|
46
|
+
"prettier": "^3.3.3",
|
|
47
47
|
"ts-node": "^10.9.2",
|
|
48
48
|
"tsc-watch": "^6.2.0",
|
|
49
|
-
"typescript": "^5.
|
|
49
|
+
"typescript": "^5.6.2"
|
|
50
50
|
},
|
|
51
51
|
"description": "Lab Streaming Layer (LSL) bindings for Node",
|
|
52
52
|
"skill": {
|
|
@@ -74,12 +74,12 @@
|
|
|
74
74
|
}
|
|
75
75
|
},
|
|
76
76
|
"dependencies": {
|
|
77
|
-
"@sprucelabs/error": "^6.0.
|
|
78
|
-
"@sprucelabs/schema": "^30.0.
|
|
79
|
-
"@sprucelabs/spruce-core-schemas": "^40.1.
|
|
80
|
-
"@sprucelabs/spruce-skill-utils": "^31.0.
|
|
81
|
-
"ffi-rs": "^1.0.
|
|
82
|
-
"node-gyp": "^10.
|
|
77
|
+
"@sprucelabs/error": "^6.0.345",
|
|
78
|
+
"@sprucelabs/schema": "^30.0.393",
|
|
79
|
+
"@sprucelabs/spruce-core-schemas": "^40.1.338",
|
|
80
|
+
"@sprucelabs/spruce-skill-utils": "^31.0.412",
|
|
81
|
+
"ffi-rs": "^1.0.94",
|
|
82
|
+
"node-gyp": "^10.2.0",
|
|
83
83
|
"ref-array-napi": "^1.2.2",
|
|
84
84
|
"ref-napi": "^3.0.3"
|
|
85
85
|
}
|