@neurodevs/node-lsl 19.0.0 → 22.0.0

package/src/impl/LslStreamInfo.ts

@@ -6,8 +6,8 @@ import {
     CHANNEL_FORMATS_MAP,
 } from '@neurodevs/ndx-native'
 
-export default class LslStreamInfo implements StreamInfo {
-    public static Class?: StreamInfoConstructor
+export default class LslStreamInfo implements LslInfo {
+    public static Class?: LslInfoConstructor
 
     public readonly name: string
     public readonly type: string
@@ -22,7 +22,7 @@ export default class LslStreamInfo implements StreamInfo {
 
     private lsl = LiblslAdapter.getInstance()
 
-    protected constructor(options: StreamInfoOptions) {
+    protected constructor(options: LslInfoOptions) {
         const {
             name = `lsl-stream-info-${generateId()}`,
             type = generateId(),
@@ -46,7 +46,7 @@ export default class LslStreamInfo implements StreamInfo {
         this.appendChannelsToStreamInfo()
     }
 
-    public static Create(options: StreamInfoOptions) {
+    public static Create(options: LslInfoOptions) {
         return new (this.Class ?? this)(options)
     }
 
@@ -81,7 +81,7 @@ export default class LslStreamInfo implements StreamInfo {
     }
 }
 
-export interface StreamInfo {
+export interface LslInfo {
     destroy(): void
     readonly name: string
     readonly type: string
@@ -94,11 +94,9 @@ export interface StreamInfo {
     readonly infoHandle: InfoHandle
 }
 
-export type StreamInfoConstructor = new (
-    options: StreamInfoOptions
-) => StreamInfo
+export type LslInfoConstructor = new (options: LslInfoOptions) => LslInfo
 
-export interface StreamInfoOptions {
+export interface LslInfoOptions {
     channelNames: string[]
     channelFormat: ChannelFormat
     sampleRateHz: number

package/src/impl/LslStreamInlet.ts

@@ -1,37 +1,75 @@
-import { Worker } from 'node:worker_threads'
+import {
+    handleLslError,
+    InfoHandle,
+    InletHandle,
+    LiblslAdapter,
+} from '@neurodevs/ndx-native'
+import {
+    JsExternal,
+    unwrapPointer,
+    createPointer,
+    DataType,
+    freePointer,
+    PointerType,
+} from 'ffi-rs'
 
-export default class LslStreamInlet implements StreamInlet {
-    public static Class?: StreamInletConstructor
-    public static Worker = Worker
+export default class LslStreamInlet implements LslInlet {
+    public static Class?: LslInletConstructor
     public static waitAfterOpenStreamMs = 100
-    public static setTimeout = setTimeout
+    public static lsl = LiblslAdapter.getInstance()
+    public static handleLslError = handleLslError
+    public static freePointer = freePointer
+
+    public isRunning = false
 
     private sourceId: string
     private chunkSize: number
     private maxBufferedMs: number
     private pullTimeoutMs: number
     private openStreamTimeoutMs: number
-    private waitAfterOpenStreamMs: number
     private waitBetweenPullsMs: number
     private flushInletOnStop: boolean
     private onData: OnDataCallback
 
-    private worker!: Worker
-    private workerReady = false
+    private infoHandle!: InfoHandle
+    private inletHandle!: InletHandle
+    private channelCount!: number
+
+    private pullMethod!: () => {
+        samples: number[] | undefined
+        timestamps: number[] | undefined
+    }
+
+    private sampleBuffer!: Buffer<ArrayBuffer>
+    private sampleBufferRef!: JsExternal[]
+    private sampleBufferPtr!: JsExternal
+
+    private timestampBuffer!: Buffer<ArrayBuffer>
+    private timestampBufferRef!: JsExternal[]
+    private timestampBufferPtr!: JsExternal
+
+    private pullErrorBuffer!: Buffer<ArrayBuffer>
+    private pullErrorBufferRef!: JsExternal[]
+    private pullErrorBufferPtr!: JsExternal
+
+    private openStreamErrorBuffer!: Buffer<ArrayBuffer>
+    private openStreamErrorBufferRef!: JsExternal[]
+    private openStreamErrorBufferPtr!: JsExternal
 
     private readonly sixMinutesInMs = 360 * 1000
     private readonly aboutOneYearInMs = 32000000 * 1000
 
-    public isRunning = false
+    private readonly bytesPerFloat = 4
+    private readonly bytesPerDouble = 8
+    private readonly bytesPerI32 = 4
 
-    protected constructor(options: StreamInletOptions, onData: OnDataCallback) {
+    protected constructor(options: LslInletOptions, onData: OnDataCallback) {
         const {
             sourceId,
             chunkSize,
             maxBufferedMs,
             pullTimeoutMs,
             openStreamTimeoutMs,
-            waitAfterOpenStreamMs,
             waitBetweenPullsMs,
             flushInletOnStop,
         } = options ?? {}
@@ -41,114 +79,301 @@ export default class LslStreamInlet implements StreamInlet {
         this.maxBufferedMs = maxBufferedMs ?? this.sixMinutesInMs
         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.createWorkerThread()
     }
 
     public static async Create(
-        options: StreamInletOptions,
+        options: LslInletOptions,
         onData: OnDataCallback
     ) {
         return new (this.Class ?? this)(options, onData)
     }
 
-    private createWorkerThread() {
-        this.worker = new this.Worker(
-            new URL('./workers/inlet/LslStreamInlet.worker.js', import.meta.url)
+    public async startPulling() {
+        if (this.isRunning) {
+            console.warn('Skipping startPulling: inlet is already running!')
+            return
+        }
+
+        this.isRunning = true
+
+        await this.createInlet()
+        void this.pullLoop()
+    }
+
+    private async createInlet() {
+        this.infoHandle = this.resolveInfoHandle()
+        this.inletHandle = this.doCreateInlet()
+        this.channelCount = this.getChannelCount()
+
+        this.allocateWritableBuffers()
+        this.setPullMethod()
+
+        this.openStream()
+    }
+
+    private resolveInfoHandle() {
+        const handles = this.resolveByProp()
+
+        if (handles.length === 0) {
+            this.throwNoStreamFound()
+        } else if (handles.length > 1) {
+            this.warnMultipleStreamsFound()
+        }
+        return handles[0]
+    }
+
+    private resolveByProp() {
+        return this.lsl.resolveByProp({
+            prop: 'source_id',
+            value: this.sourceId,
+        })
+    }
+
+    private throwNoStreamFound() {
+        throw new Error(`No stream info for sourceId "${this.sourceId}"`)
+    }
+
+    private warnMultipleStreamsFound() {
+        console.warn(
+            `Multiple stream infos for sourceId "${this.sourceId}", using the first one.`
         )
+    }
 
-        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}`)
-            }
+    private doCreateInlet() {
+        return this.lsl.createInlet({
+            infoHandle: this.infoHandle,
+            maxBufferedMs: this.maxBufferedMs,
         })
     }
 
-    public async startPulling() {
-        if (!this.isRunning) {
-            this.isRunning = true
-            this.postCreate()
-
-            while (!this.workerReady) {
-                await new Promise((resolve) =>
-                    LslStreamInlet.setTimeout(resolve, 10)
-                )
+    private getChannelCount() {
+        return this.lsl.getChannelCount({ infoHandle: this.infoHandle })
+    }
+
+    private allocateWritableBuffers() {
+        this.allocateDataBuffer()
+        this.allocateTimestampBuffer()
+        this.allocatePullErrorBuffer()
+        this.allocateOpenStreamErrorBuffer()
+    }
+
+    private allocateDataBuffer() {
+        this.sampleBuffer = Buffer.alloc(
+            this.channelCount * this.chunkSize * this.bytesPerFloat
+        )
+
+        this.sampleBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.sampleBuffer],
+        })
+
+        this.sampleBufferPtr = unwrapPointer(this.sampleBufferRef)[0]
+    }
+
+    private allocateTimestampBuffer() {
+        this.timestampBuffer = Buffer.alloc(
+            this.chunkSize * this.bytesPerDouble
+        )
+
+        this.timestampBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.timestampBuffer],
+        })
+
+        this.timestampBufferPtr = unwrapPointer(this.timestampBufferRef)[0]
+    }
+
+    private allocatePullErrorBuffer() {
+        this.pullErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.pullErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.pullErrorBuffer],
+        })
+
+        this.pullErrorBufferPtr = unwrapPointer(this.pullErrorBufferRef)[0]
+    }
+
+    private allocateOpenStreamErrorBuffer() {
+        this.openStreamErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.openStreamErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.openStreamErrorBuffer],
+        })
+
+        this.openStreamErrorBufferPtr = unwrapPointer(
+            this.openStreamErrorBufferRef
+        )[0]
+    }
+
+    private setPullMethod() {
+        this.pullMethod =
+            this.chunkSize === 1 ? this.pullSample : this.pullChunk
+    }
+
+    private pullSample = () => {
+        const timestampSec = this.doPullsample()
+
+        if (timestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: [timestampSec],
             }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
 
-            this.postStartPulling()
-        } else {
-            console.warn('Skipping startPulling: inlet is already running!')
+    private doPullsample() {
+        return this.lsl.pullSample({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.channelCount,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
+        })
+    }
+
+    private readSamplesFromBuffer() {
+        const floats = new Float32Array(
+            this.sampleBuffer.buffer,
+            this.sampleBuffer.byteOffset,
+            this.chunkSize * this.channelCount
+        )
+        return Array.from(floats)
+    }
+
+    private pullChunk = () => {
+        const firstTimestampSec = this.doPullChunk()
+
+        if (firstTimestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: this.readTimestampsFromBuffer(),
+            }
         }
+        return { samples: undefined, timestamps: undefined }
     }
 
-    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 doPullChunk() {
+        return this.lsl.pullChunk({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.chunkSize * this.channelCount,
+            timestampBufferPtr: this.timestampBufferPtr,
+            timestampBufferElements: this.chunkSize,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
         })
     }
 
-    private postStartPulling() {
-        this.worker.postMessage({ type: 'startPulling' })
+    private readTimestampsFromBuffer() {
+        const doubles = new Float64Array(
+            this.timestampBuffer.buffer,
+            this.timestampBuffer.byteOffset,
+            this.chunkSize
+        )
+        return Array.from(doubles)
+    }
+
+    private openStream() {
+        this.lsl.openStream({
+            inletHandle: this.inletHandle,
+            timeoutMs: this.openStreamTimeoutMs,
+            errorCodePtr: this.openStreamErrorBufferPtr,
+        })
+    }
+
+    private async pullLoop() {
+        while (this.isRunning) {
+            await this.pullDataOnce()
+            await this.waitBetweenPulls()
+        }
+    }
+
+    private async pullDataOnce() {
+        const { samples, timestamps } = this.pullMethod()
+        this.handleLslErrorIfPresent()
+
+        if (samples && timestamps) {
+            this.onData(samples, timestamps)
+        }
+    }
+
+    private handleLslErrorIfPresent() {
+        const errorCode = this.pullErrorBuffer.readInt32LE()
+        this.handleLslError(errorCode)
+    }
+
+    private async waitBetweenPulls() {
+        await new Promise((r) => setTimeout(r, this.waitBetweenPullsMs))
+    }
+
+    public flushInlet() {
+        this.lsl.flushInlet({ inletHandle: this.inletHandle })
     }
 
     public stopPulling() {
         this.isRunning = false
-        this.worker.postMessage({ type: 'stopPulling' })
+        this.closeStream()
+
+        if (this.flushInletOnStop) {
+            this.flushInlet()
+        }
     }
 
-    public flushInlet() {
-        this.worker.postMessage({ type: 'flushInlet' })
+    private closeStream() {
+        this.lsl.closeStream({ inletHandle: this.inletHandle })
     }
 
     public destroy() {
         if (this.isRunning) {
             this.stopPulling()
         }
-        this.worker.postMessage({ type: 'destroyInlet' })
+
+        this.doDestroyInlet()
+        this.freeNativePointers()
+    }
+
+    private doDestroyInlet() {
+        this.lsl.destroyInlet({ inletHandle: this.inletHandle })
+    }
+
+    private freeNativePointers() {
+        this.freePointer({
+            paramsType: [
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+            ],
+            paramsValue: [
+                this.openStreamErrorBufferPtr,
+                this.sampleBufferPtr,
+                this.timestampBufferPtr,
+                this.pullErrorBufferPtr,
+            ],
+            pointerType: PointerType.CPointer,
+        })
+    }
+
+    private get lsl() {
+        return LslStreamInlet.lsl
     }
 
-    private get defaultWaitMs() {
-        return LslStreamInlet.waitAfterOpenStreamMs
+    private get handleLslError() {
+        return LslStreamInlet.handleLslError
     }
 
-    private get Worker() {
-        return LslStreamInlet.Worker
+    private get freePointer() {
+        return LslStreamInlet.freePointer
     }
 }
 
-export interface StreamInlet {
+export interface LslInlet {
     startPulling(): Promise<void>
     stopPulling(): void
     flushInlet(): void
@@ -156,17 +381,16 @@ export interface StreamInlet {
     readonly isRunning: boolean
 }
 
-export type StreamInletConstructor = new (
-    options: StreamInletOptions,
+export type LslInletConstructor = new (
+    options: LslInletOptions,
     onData: OnDataCallback
-) => StreamInlet
+) => LslInlet
 
-export interface StreamInletOptions {
+export interface LslInletOptions {
     sourceId: string
     chunkSize: number
     maxBufferedMs?: number
     openStreamTimeoutMs?: number
-    waitAfterOpenStreamMs?: number
     pullTimeoutMs?: number
     waitBetweenPullsMs?: number
     flushInletOnStop?: boolean