@neurodevs/node-lsl 17.1.0 → 18.0.0

package/src/impl/LslStreamInlet.ts

@@ -1,275 +1,172 @@
-import { createPointer, DataType, JsExternal, unwrapPointer } from 'ffi-rs'
-
-import handleError from '../handleError.js'
-import { BoundInlet } from './LiblslAdapter.js'
-import LiblslAdapter from './LiblslAdapter.js'
-import { StreamInfo } from './LslStreamInfo.js'
+import { Worker } from 'node:worker_threads'
 
 export default class LslStreamInlet implements StreamInlet {
     public static Class?: StreamInletConstructor
+    public static Worker = Worker
+    public static waitAfterOpenStreamMs = 100
 
-    public isRunning = false
-
-    protected info: StreamInfo
-    private channelCount: number
+    private sourceId: string
     private chunkSize: number
     private maxBufferedMs: number
-    private timeoutMs: number
+    private pullTimeoutMs: number
+    private openStreamTimeoutMs: number
+    private waitAfterOpenStreamMs: number
+    private waitBetweenPullsMs: number
+    private flushInletOnStop: boolean
     private onData: OnDataCallback
 
-    protected inlet!: BoundInlet
-
-    private pullDataMethod!: () => {
-        samples: Float32Array | undefined
-        timestamps: Float64Array | undefined
-    }
-
-    private dataBuffer!: Buffer<ArrayBuffer>
-    private dataBufferPtr!: JsExternal
-
-    private timestampBuffer!: Buffer<ArrayBuffer>
-    private timestampBufferPtr!: JsExternal
-
-    private errorCodeBuffer!: Buffer<ArrayBuffer>
-    private errorCodeBufferPtr!: JsExternal
+    private worker!: Worker
+    private workerReady = false
 
     private readonly sixMinutesInMs = 360 * 1000
+    private readonly aboutOneYearInMs = 32000000 * 1000
 
-    private lsl = LiblslAdapter.getInstance()
-
-    protected constructor(
-        info: StreamInfo,
-        options: StreamInletConstructorOptions,
-        onData: OnDataCallback
-    ) {
-        const { chunkSize, maxBufferedMs, timeoutMs } = options ?? {}
+    public isRunning = false
 
-        this.info = info
-        this.channelCount = this.info.channelCount
+    protected constructor(options: StreamInletOptions, onData: OnDataCallback) {
+        const {
+            sourceId,
+            chunkSize,
+            maxBufferedMs,
+            pullTimeoutMs,
+            openStreamTimeoutMs,
+            waitAfterOpenStreamMs,
+            waitBetweenPullsMs,
+            flushInletOnStop,
+        } = options ?? {}
+
+        this.sourceId = sourceId
         this.chunkSize = chunkSize
         this.maxBufferedMs = maxBufferedMs ?? this.sixMinutesInMs
-        this.timeoutMs = timeoutMs ?? 0
+        this.pullTimeoutMs = pullTimeoutMs ?? 0
+        this.openStreamTimeoutMs = openStreamTimeoutMs ?? this.aboutOneYearInMs
+        this.waitAfterOpenStreamMs = waitAfterOpenStreamMs ?? this.defaultWaitMs
+        this.waitBetweenPullsMs = waitBetweenPullsMs ?? 1
+        this.flushInletOnStop = flushInletOnStop ?? true
         this.onData = onData
 
-        this.setPullDataMethod()
-        this.createBoundInlet()
+        this.createWorkerThread()
     }
 
     public static async Create(
         options: StreamInletOptions,
         onData: OnDataCallback
     ) {
-        const { info } = options
-        return new (this.Class ?? this)(info, options, onData)
-    }
-
-    private setPullDataMethod() {
-        if (this.chunkSize === 1) {
-            this.pullDataMethod = this.pullSample
-        } else {
-            this.pullDataMethod = this.pullChunk
-        }
+        return new (this.Class ?? this)(options, onData)
     }
 
-    private createBoundInlet() {
-        this.inlet = this.lsl.createInlet({
-            info: this.info.boundInfo,
-            maxBufferedMs: this.maxBufferedMs,
-        })
-    }
-
-    public startPulling() {
-        this.isRunning = true
-
-        this.createWriteableBuffers()
-        this.createPointersToBuffers()
-
-        void this.pullOnLoop()
-    }
-
-    private createWriteableBuffers() {
-        this.createDataBuffer()
-        this.createTimestampBuffer()
-        this.createErrorCodeBuffer()
-    }
-
-    private createDataBuffer() {
-        this.dataBuffer = Buffer.alloc(
-            this.bytesPerFloat * this.chunkSize * this.channelCount
+    private createWorkerThread() {
+        this.worker = new this.Worker(
+            new URL('./workers/inlet/LslStreamInlet.worker.js', import.meta.url)
         )
-    }
-
-    private readonly bytesPerFloat = 4
-
-    private createTimestampBuffer() {
-        this.timestampBuffer = Buffer.alloc(
-            this.bytesPerDouble * this.chunkSize
-        )
-    }
-
-    private readonly bytesPerDouble = 8
-
-    private createErrorCodeBuffer() {
-        this.errorCodeBuffer = Buffer.alloc(this.bytesPerInt)
-    }
 
-    private readonly bytesPerInt = 4
-
-    private createPointersToBuffers() {
-        this.createDataBufferPtr()
-        this.createTimestampBufferPtr()
-        this.createErrorCodeBufferPtr()
-    }
-
-    private createDataBufferPtr() {
-        this.dataBufferPtr = unwrapPointer(
-            createPointer({
-                paramsType: [DataType.U8Array],
-                paramsValue: [this.dataBuffer],
-            })
-        )[0]
-    }
-
-    private createTimestampBufferPtr() {
-        this.timestampBufferPtr = unwrapPointer(
-            createPointer({
-                paramsType: [DataType.U8Array],
-                paramsValue: [this.timestampBuffer],
-            })
-        )[0]
-    }
-
-    private createErrorCodeBufferPtr() {
-        this.errorCodeBufferPtr = unwrapPointer(
-            createPointer({
-                paramsType: [DataType.U8Array],
-                paramsValue: [this.errorCodeBuffer],
-            })
-        )[0]
-    }
-
-    private async pullOnLoop() {
-        if (this.isRunning) {
-            const { samples, timestamps } = this.pullDataMethod()
-            this.handleErrorCodeIfPresent()
-
-            if (samples && timestamps) {
-                this.onData(samples, timestamps)
-            }
-
-            setImmediate(() => {
-                void this.pullOnLoop()
-            })
-        }
-    }
-
-    private pullSample() {
-        const timestamp = this.callPullSampleBinding()
-
-        if (timestamp) {
-            return {
-                samples: this.createFloatArrayFromDataBuffer(),
-                timestamps: new Float64Array([timestamp]),
+        this.worker.on('message', (msg) => {
+            const { type } = msg
+
+            switch (type) {
+                case 'ready': {
+                    this.workerReady = true
+                    break
+                }
+                case 'data': {
+                    const { payload } = msg
+                    const { samples, timestamps } = payload
+
+                    this.onData(samples, timestamps)
+                    break
+                }
+                case 'error': {
+                    const { error } = msg
+                    throw new Error(error)
+                }
+                default:
+                    throw new Error(`Unknown message type: ${type}`)
             }
-        }
-        return { samples: undefined, timestamps: undefined }
-    }
-
-    private callPullSampleBinding() {
-        return this.lsl.pullSample({
-            inlet: this.inlet,
-            dataBufferPtr: this.dataBufferPtr,
-            dataBufferElements: this.channelCount,
-            timeout: this.timeoutMs / 1000,
-            errcodePtr: this.errorCodeBufferPtr,
         })
     }
 
-    private createFloatArrayFromDataBuffer() {
-        return new Float32Array(
-            this.dataBuffer.buffer,
-            this.dataBuffer.byteOffset,
-            this.chunkSize * this.channelCount
-        )
-    }
-
-    private pullChunk() {
-        const firstTimestamp = this.callPullChunkBinding()
+    public async startPulling() {
+        if (!this.isRunning) {
+            this.isRunning = true
+            this.postCreate()
 
-        if (firstTimestamp) {
-            return {
-                samples: this.createFloatArrayFromDataBuffer(),
-                timestamps: this.createDoubleArrayFromTimestampBuffer(),
+            while (!this.workerReady) {
+                await new Promise((resolve) => setTimeout(resolve, 10))
             }
+
+            this.postStartPulling()
+        } else {
+            console.warn('Skipping startPulling: inlet is already running!')
         }
-        return { samples: undefined, timestamps: undefined }
     }
 
-    private callPullChunkBinding() {
-        return this.lsl.pullChunk({
-            inlet: this.inlet,
-            dataBufferPtr: this.dataBufferPtr,
-            timestampBufferPtr: this.timestampBufferPtr,
-            dataBufferElements: this.chunkSize * this.channelCount,
-            timestampBufferElements: this.chunkSize,
-            timeout: this.timeoutMs / 1000,
-            errcodePtr: this.errorCodeBufferPtr,
+    private postCreate() {
+        this.worker.postMessage({
+            type: 'createInlet',
+            payload: {
+                sourceId: this.sourceId,
+                chunkSize: this.chunkSize,
+                maxBufferedMs: this.maxBufferedMs,
+                openStreamTimeoutMs: this.openStreamTimeoutMs,
+                waitAfterOpenStreamMs: this.waitAfterOpenStreamMs,
+                pullTimeoutMs: this.pullTimeoutMs,
+                waitBetweenPullsMs: this.waitBetweenPullsMs,
+                flushInletOnStop: this.flushInletOnStop,
+            },
         })
     }
 
-    private createDoubleArrayFromTimestampBuffer() {
-        return new Float64Array(
-            this.timestampBuffer.buffer,
-            this.timestampBuffer.byteOffset,
-            this.chunkSize
-        )
-    }
-
-    private handleErrorCodeIfPresent() {
-        handleError(this.errorCodeBuffer.readInt32LE())
+    private postStartPulling() {
+        this.worker.postMessage({ type: 'startPulling' })
     }
 
     public stopPulling() {
         this.isRunning = false
+        this.worker.postMessage({ type: 'stopPulling' })
     }
 
-    public flushQueue() {
-        this.lsl.flushInlet({ inlet: this.inlet })
+    public flushInlet() {
+        this.worker.postMessage({ type: 'flushInlet' })
     }
 
     public destroy() {
-        this.destroyBoundInlet()
+        if (this.isRunning) {
+            this.stopPulling()
+        }
+        this.worker.postMessage({ type: 'destroyInlet' })
+    }
+
+    private get defaultWaitMs() {
+        return LslStreamInlet.waitAfterOpenStreamMs
     }
 
-    private destroyBoundInlet() {
-        this.lsl.destroyInlet({ inlet: this.inlet })
+    private get Worker() {
+        return LslStreamInlet.Worker
     }
 }
 
 export interface StreamInlet {
-    startPulling(): void
+    startPulling(): Promise<void>
     stopPulling(): void
-    flushQueue(): void
+    flushInlet(): void
     destroy(): void
     readonly isRunning: boolean
 }
 
 export type StreamInletConstructor = new (
-    info: StreamInfo,
-    options: StreamInletConstructorOptions,
+    options: StreamInletOptions,
     onData: OnDataCallback
 ) => StreamInlet
 
 export interface StreamInletOptions {
-    info: StreamInfo
+    sourceId: string
     chunkSize: number
     maxBufferedMs?: number
-    timeoutMs?: number
+    openStreamTimeoutMs?: number
+    waitAfterOpenStreamMs?: number
+    pullTimeoutMs?: number
+    waitBetweenPullsMs?: number
+    flushInletOnStop?: boolean
 }
 
-export type StreamInletConstructorOptions = Omit<StreamInletOptions, 'info'>
-
-export type OnDataCallback = (
-    samples: Float32Array,
-    timestamps: Float64Array
-) => void
+export type OnDataCallback = (samples: number[], timestamps: number[]) => void

package/src/impl/LslStreamOutlet.ts

@@ -1,3 +1,7 @@
+import { Worker } from 'node:worker_threads'
+
+import { ChannelFormat, Liblsl, LslSample } from '@neurodevs/ndx-native'
+
 import {
     assertValidChannelCount,
     assertValidChannelFormat,
@@ -5,23 +9,11 @@ import {
     assertValidMaxBufferedMs,
     assertValidSampleRateHz,
 } from '../assertions.js'
-import handleError, { LslErrorCode } from '../handleError.js'
-import {
-    ChannelFormat,
-    BoundOutlet,
-    Liblsl,
-    LslSample,
-} from './LiblslAdapter.js'
-import LiblslAdapter from './LiblslAdapter.js'
-import LslStreamInfo, {
-    StreamInfo,
-    StreamInfoOptions,
-} from './LslStreamInfo.js'
 
 export default class LslStreamOutlet implements StreamOutlet {
     public static Class?: StreamOutletConstructor
+    public static Worker = Worker
 
-    public readonly info: StreamInfo
     public readonly name: string
     public readonly type: string
     public readonly sourceId: string
@@ -34,12 +26,9 @@ export default class LslStreamOutlet implements StreamOutlet {
     public readonly manufacturer: string = 'N/A'
     public readonly units: string = 'N/A'
 
-    private boundOutlet!: BoundOutlet
-    private pushSampleMethod!: (options: unknown) => LslErrorCode
+    private worker!: Worker
 
-    private lsl = LiblslAdapter.getInstance()
-
-    protected constructor(info: StreamInfo, options: StreamOutletOptions) {
+    protected constructor(options: StreamOutletOptions) {
         const {
             name,
             type,
@@ -53,7 +42,6 @@ export default class LslStreamOutlet implements StreamOutlet {
             units,
         } = options
 
-        this.info = info
         this.name = name
         this.type = type
         this.sourceId = sourceId
@@ -67,17 +55,15 @@ export default class LslStreamOutlet implements StreamOutlet {
         this.units = units ?? this.units
 
         this.validateOptions()
+        this.createWorkerThread()
         this.createStreamOutlet()
-        this.setPushSampleMethod()
     }
 
     public static async Create(options: StreamOutletOptions) {
         const { waitAfterConstructionMs = 10 } = options ?? {}
 
-        const info = this.LslStreamInfo(options)
-        const instance = new (this.Class ?? this)(info, options)
-
-        await this.waitToAllowSetup(waitAfterConstructionMs)
+        const instance = new (this.Class ?? this)(options)
+        await this.waitForSetup(waitAfterConstructionMs)
 
         return instance
     }
@@ -107,18 +93,33 @@ export default class LslStreamOutlet implements StreamOutlet {
         )
     }
 
-    private createStreamOutlet() {
-        this.boundOutlet = this.lsl.createOutlet({
-            info: this.info.boundInfo,
-            chunkSize: this.chunkSize,
-            maxBufferedMs: this.maxBufferedMs,
-        })
+    private createWorkerThread() {
+        this.worker = new this.Worker(
+            new URL(
+                './workers/outlet/LslStreamOutlet.worker.js',
+                import.meta.url
+            )
+        )
     }
 
-    private setPushSampleMethod() {
-        this.pushSampleMethod = (
-            this.lsl[this.pushMethod] as (options: unknown) => LslErrorCode
-        ).bind(this.lsl)
+    private createStreamOutlet() {
+        this.worker.postMessage({
+            type: 'createOutlet',
+            payload: {
+                infoOptions: {
+                    name: this.name,
+                    type: this.type,
+                    sourceId: this.sourceId,
+                    channelNames: this.channelNames,
+                    channelFormat: this.channelFormat,
+                    sampleRateHz: this.sampleRateHz,
+                    units: this.units,
+                },
+                chunkSize: this.chunkSize,
+                maxBufferedMs: this.maxBufferedMs,
+                pushMethod: this.pushMethod,
+            },
+        })
     }
 
     private get pushMethod() {
@@ -130,63 +131,36 @@ export default class LslStreamOutlet implements StreamOutlet {
         string: 'pushSampleStringTimestamp',
     }
 
-    public pushSample(sample: LslSample) {
-        const timestamp = this.lsl.localClock()
-
-        const err = this.pushSampleMethod({
-            outlet: this.boundOutlet,
-            sample,
-            timestamp,
+    public pushSample(sample: LslSample, timestamp?: number) {
+        this.worker.postMessage({
+            type: 'pushSample',
+            payload: {
+                sample,
+                timestamp,
+            },
         })
-        handleError(err)
     }
 
     public destroy() {
-        this.destroyBoundInfo()
-        this.destroyBoundOutlet()
-    }
-
-    private destroyBoundInfo() {
-        this.lsl.destroyStreamInfo({ info: this.info.boundInfo })
+        this.worker.postMessage({
+            type: 'destroyOutlet',
+        })
     }
 
-    private destroyBoundOutlet() {
-        this.lsl.destroyOutlet({ outlet: this.boundOutlet })
+    private get Worker() {
+        return LslStreamOutlet.Worker
     }
 
-    private static async waitToAllowSetup(waitAfterConstructionMs: number) {
+    private static async waitForSetup(waitAfterConstructionMs: number) {
         await new Promise((resolve) =>
             setTimeout(resolve, waitAfterConstructionMs)
         )
     }
-
-    private static LslStreamInfo(options: StreamInfoOptions) {
-        const {
-            channelNames,
-            channelFormat,
-            sampleRateHz,
-            name,
-            type,
-            sourceId,
-            units,
-        } = options
-
-        return LslStreamInfo.Create({
-            name,
-            type,
-            sourceId,
-            channelNames,
-            channelFormat,
-            sampleRateHz,
-            units,
-        })
-    }
 }
 
 export interface StreamOutlet {
-    pushSample(sample: LslSample): void
+    pushSample(sample: LslSample, timestamp?: number): void
     destroy(): void
-    readonly info: StreamInfo
     readonly name: string
     readonly type: string
     readonly sourceId: string
@@ -201,11 +175,14 @@ export interface StreamOutlet {
 }
 
 export type StreamOutletConstructor = new (
-    info: StreamInfo,
     options: StreamOutletOptions
 ) => StreamOutlet
 
-export interface StreamOutletOptions {
+export interface StreamOutletOptions extends StreamOutletConstructorOptions {
+    waitAfterConstructionMs?: number
+}
+
+export interface StreamOutletConstructorOptions {
     name: string
     type: string
     sourceId: string
@@ -216,5 +193,4 @@ export interface StreamOutletOptions {
     maxBufferedMs?: number
     manufacturer?: string
     units?: string
-    waitAfterConstructionMs?: number
 }

package/src/impl/LslWebSocketBridge.ts

@@ -1,5 +1,5 @@
 import WebSocket, { WebSocketServer } from 'ws'
-import { StreamInfo } from './LslStreamInfo.js'
+
 import LslStreamInlet, {
     StreamInlet,
     StreamInletOptions,
@@ -55,9 +55,9 @@ export default class LslWebSocketBridge implements WebSocketBridge {
 
     private readonly insufficientOptionsError = `At least one of listenPort or connectUrls must be provided!`
 
-    public activate() {
+    public async activate() {
         this.throwIfBridgeIsDestroyed(this.cannotActivateMessage)
-        this.startPullingData()
+        await this.startPullingData()
     }
 
     private throwIfBridgeIsDestroyed(err: string) {
@@ -68,8 +68,8 @@ export default class LslWebSocketBridge implements WebSocketBridge {
 
     private readonly cannotActivateMessage = `\n\n Cannot activate bridge after destroying it! \n\n Please create and activate a new instance. \n`
 
-    private startPullingData() {
-        this.inlet.startPulling()
+    private async startPullingData() {
+        await this.inlet.startPulling()
     }
 
     public deactivate() {
@@ -84,13 +84,13 @@ export default class LslWebSocketBridge implements WebSocketBridge {
     }
 
     public destroy() {
-        this.destroyBoundInlet()
         this.closeLocalServerIfExists()
         this.closeRemoteSocketsIfExists()
+        this.destroyInlet()
         this.isDestroyed = true
     }
 
-    private destroyBoundInlet() {
+    private destroyInlet() {
         this.inlet.destroy()
     }
 
@@ -106,14 +106,14 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         localServer?: WebSocketServer,
         remoteSockets?: WebSocket[]
     ) {
-        return (samples: Float32Array, timestamps: Float64Array) => {
+        return (samples: number[], timestamps: number[]) => {
             const payload = JSON.stringify({ samples, timestamps })
 
-            if (localServer) {
+            if (localServer && localServer.clients.size > 0) {
                 this.broadcastToClients(localServer, payload)
             }
 
-            if (remoteSockets) {
+            if (remoteSockets && remoteSockets.length > 0) {
                 this.sendToSockets(remoteSockets, payload)
             }
         }
@@ -165,7 +165,7 @@ export default class LslWebSocketBridge implements WebSocketBridge {
 }
 
 export interface WebSocketBridge {
-    activate(): void
+    activate(): Promise<void>
     deactivate(): void
     destroy(): void
 }
@@ -175,7 +175,7 @@ export type WebSocketBridgeConstructor = new (
 ) => WebSocketBridge
 
 export interface WebSocketBridgeOptions {
-    info: StreamInfo
+    sourceId: string
     chunkSize: number
     listenPort?: number
     connectUrls?: string | string[]