@neurodevs/node-lsl 12.0.5 → 13.0.0

package/src/impl/LslStreamInlet.ts

@@ -1,6 +1,8 @@
 import generateId from '@neurodevs/generate-id'
+import { createPointer, DataType, JsExternal, unwrapPointer } from 'ffi-rs'
 
-import { BoundInlet, ChannelFormat } from '../types.js'
+import handleError from '../handleError.js'
+import { BoundInlet, ChannelFormat, Liblsl } from './LiblslAdapter.js'
 import LiblslAdapter from './LiblslAdapter.js'
 import LslStreamInfo, {
     StreamInfo,
@@ -10,79 +12,285 @@ import LslStreamInfo, {
 export default class LslStreamInlet implements StreamInlet {
     public static Class?: StreamInletConstructor
 
-    protected name: string
+    public isRunning = false
+
     protected info: StreamInfo
-    protected inlet!: BoundInlet
+    protected name: string
+    private channelNames: string[]
+    private channelCount: number
     private chunkSize: number
-    private maxBuffered: number
+    private maxBufferedMs: number
+    private timeoutMs: number
+
+    private onData: OnDataCallback
 
-    protected constructor(info: StreamInfo, options: StreamInletOptions) {
+    private pullDataMethod: () => {
+        samples: Float32Array | undefined
+        timestamps: Float64Array | undefined
+    }
+
+    private lsl: Liblsl
+
+    protected inlet!: BoundInlet
+
+    private dataBuffer!: Buffer<ArrayBuffer>
+    private dataBufferPtr!: JsExternal
+
+    private timestampBuffer!: Buffer<ArrayBuffer>
+    private timestampBufferPtr!: JsExternal
+
+    private errorCodeBuffer!: Buffer<ArrayBuffer>
+    private errorCodeBufferPtr!: JsExternal
+
+    private readonly defaultName = `lsl-inlet-${generateId()}`
+    private readonly sixMinutesInMs = 360 * 1000
+
+    protected constructor(
+        info: StreamInfo,
+        options: StreamInletOptions,
+        onData: OnDataCallback
+    ) {
         const {
             name = this.defaultName,
+            channelNames,
             chunkSize,
-            maxBuffered,
+            maxBufferedMs,
+            timeoutMs,
         } = options ?? {}
 
         this.info = info
-        this.chunkSize = chunkSize
-        this.maxBuffered = maxBuffered
         this.name = name
+        this.channelNames = channelNames
+        this.channelCount = this.channelNames.length
+        this.chunkSize = chunkSize
+        this.maxBufferedMs = maxBufferedMs ?? this.sixMinutesInMs
+        this.timeoutMs = timeoutMs ?? 0
 
-        this.createStreamInlet()
+        this.onData = onData
+
+        if (this.chunkSize === 1) {
+            this.pullDataMethod = this.pullSample
+        } else {
+            this.pullDataMethod = this.pullChunk
+        }
+
+        this.lsl = this.getLiblslSingleton()
+
+        this.createBoundInlet()
     }
 
-    public static Create(options: StreamInletOptions) {
+    public static Create(options: StreamInletOptions, onData: OnDataCallback) {
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { maxBuffered, chunkSize, ...infoOptions } = options
+        const { maxBufferedMs, chunkSize, ...infoOptions } = options
         const info = this.LslStreamInfo(infoOptions)
-        return new (this.Class ?? this)(info, options)
+        return new (this.Class ?? this)(info, options, onData)
     }
 
-    private createStreamInlet() {
+    private createBoundInlet() {
         this.inlet = this.lsl.createInlet({
-            info: this.boundStreamInfo,
+            info: this.info.boundStreamInfo,
             chunkSize: this.chunkSize,
-            maxBuffered: this.maxBuffered,
+            maxBufferedMs: this.maxBufferedMs / 1000,
         })
     }
 
-    private get boundStreamInfo() {
-        return this.info.boundStreamInfo
+    public startPulling() {
+        this.isRunning = true
+
+        this.createWriteableBuffers()
+        this.createPointersToBuffers()
+
+        void this.pullOnLoop()
     }
 
-    private get lsl() {
-        return LiblslAdapter.getInstance()
+    private createWriteableBuffers() {
+        this.createDataBuffer()
+        this.createTimestampBuffer()
+        this.createErrorCodeBuffer()
     }
 
-    private readonly defaultName = `lsl-inlet-${generateId()}`
+    private createDataBuffer() {
+        const bytesPerFloat = 4
+
+        this.dataBuffer = Buffer.alloc(
+            bytesPerFloat * this.chunkSize * this.channelCount
+        )
+    }
+
+    private createTimestampBuffer() {
+        const bytesPerDouble = 8
+        this.timestampBuffer = Buffer.alloc(bytesPerDouble * this.chunkSize)
+    }
+
+    private createErrorCodeBuffer() {
+        const bytesPerInt = 4
+        this.errorCodeBuffer = Buffer.alloc(bytesPerInt)
+    }
+
+    private createPointersToBuffers() {
+        this.createDataBufferPtr()
+        this.createTimestampBufferPtr()
+        this.createErrorCodeBufferPtr()
+    }
+
+    private createDataBufferPtr() {
+        this.dataBufferPtr = unwrapPointer(
+            createPointer({
+                paramsType: [DataType.U8Array],
+                paramsValue: [this.dataBuffer],
+            })
+        )[0]
+    }
 
-    public flushSamples() {
+    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]),
+            }
+        }
+        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()
+
+        if (firstTimestamp) {
+            return {
+                samples: this.createFloatArrayFromDataBuffer(),
+                timestamps: this.createDoubleArrayFromTimestampBuffer(),
+            }
+        }
+        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 createDoubleArrayFromTimestampBuffer() {
+        return new Float64Array(
+            this.timestampBuffer.buffer,
+            this.timestampBuffer.byteOffset,
+            this.chunkSize
+        )
+    }
+
+    private handleErrorCodeIfPresent() {
+        handleError(this.errorCodeBuffer.readInt32LE())
+    }
+
+    public stopPulling() {
+        this.isRunning = false
+    }
+
+    public flushQueue() {
         this.lsl.flushInlet({ inlet: this.inlet })
     }
 
+    public destroy() {
+        this.lsl.destroyInlet({ inlet: this.inlet })
+    }
+
+    private getLiblslSingleton() {
+        return LiblslAdapter.getInstance()
+    }
+
     private static LslStreamInfo(options: StreamInfoOptions) {
         return LslStreamInfo.Create(options)
     }
 }
 
 export interface StreamInlet {
-    flushSamples(): void
+    startPulling(): void
+    stopPulling(): void
+    flushQueue(): void
+    destroy(): void
+    isRunning: boolean
 }
 
 export type StreamInletConstructor = new (
     info: StreamInfo,
-    options: StreamInletOptions
+    options: StreamInletOptions,
+    onData: OnDataCallback
 ) => StreamInlet
 
 export interface StreamInletOptions {
-    sampleRate: number
     channelNames: string[]
     channelFormat: ChannelFormat
+    sampleRateHz: number
     chunkSize: number
-    maxBuffered: number
+    maxBufferedMs?: number
+    timeoutMs?: number
     name?: string
     type?: string
     sourceId?: string
     manufacturer?: string
     units?: string
 }
+
+export type OnDataCallback = (
+    samples: Float32Array,
+    timestamps: Float64Array
+) => void

package/src/impl/LslStreamOutlet.ts

@@ -2,10 +2,16 @@ import {
     assertValidChannelCount,
     assertValidChannelFormat,
     assertValidChunkSize,
-    assertValidMaxBuffered,
-    assertValidSampleRate,
+    assertValidMaxBufferedMs,
+    assertValidSampleRateHz,
 } from '../assertions.js'
-import { ChannelFormat, BoundOutlet, Liblsl, LslSample } from '../types.js'
+import handleError, { LslErrorCode } from '../handleError.js'
+import {
+    ChannelFormat,
+    BoundOutlet,
+    Liblsl,
+    LslSample,
+} from './LiblslAdapter.js'
 import LiblslAdapter from './LiblslAdapter.js'
 import LslStreamInfo, {
     StreamInfo,
@@ -18,7 +24,7 @@ export default class LslStreamOutlet implements StreamOutlet {
     private info: StreamInfo
     private options: StreamOutletOptions
     private outlet!: BoundOutlet
-    private pushSampleByType!: (options: any) => void
+    private pushSampleMethod!: (options: unknown) => LslErrorCode
 
     protected constructor(info: StreamInfo, options: StreamOutletOptions) {
         this.info = info
@@ -26,23 +32,23 @@ export default class LslStreamOutlet implements StreamOutlet {
 
         this.validateOptions()
         this.createStreamOutlet()
-        this.setPushSampleType()
+        this.setPushSampleMethod()
     }
 
     public static async Create(options: StreamOutletOptions) {
         const { waitAfterConstructionMs = 10 } = options ?? {}
 
-        const streamInfoOptions = {
+        const infoOptions = {
             channelNames: options.channelNames,
             channelFormat: options.channelFormat,
-            sampleRate: options.sampleRate,
+            sampleRateHz: options.sampleRateHz,
             name: options.name,
             type: options.type,
             sourceId: options.sourceId,
-            units: options.unit,
+            units: options.units,
         }
 
-        const info = this.LslStreamInfo(streamInfoOptions)
+        const info = this.LslStreamInfo(infoOptions)
         const instance = new (this.Class ?? this)(info, options)
 
         await this.wait(waitAfterConstructionMs)
@@ -52,24 +58,26 @@ export default class LslStreamOutlet implements StreamOutlet {
 
     private validateOptions() {
         assertValidChannelCount(this.channelCount)
-        assertValidSampleRate(this.sampleRate)
+        assertValidSampleRateHz(this.sampleRateHz)
         assertValidChannelFormat(this.channelFormat)
         assertValidChunkSize(this.chunkSize)
-        assertValidMaxBuffered(this.maxBuffered)
+        assertValidMaxBufferedMs(this.maxBufferedMs)
     }
 
     private createStreamOutlet() {
         this.outlet = this.lsl.createOutlet({
             info: this.boundStreamInfo,
             chunkSize: this.chunkSize,
-            maxBuffered: this.maxBuffered,
+            maxBufferedMs: this.maxBufferedMs,
         })
     }
 
-    private setPushSampleType() {
+    private setPushSampleMethod() {
         this.validateChannelFormat()
 
-        this.pushSampleByType = this.lsl[this.pushMethod].bind(this.lsl)
+        this.pushSampleMethod = (
+            this.lsl[this.pushMethod] as (options: unknown) => LslErrorCode
+        ).bind(this.lsl)
     }
 
     private validateChannelFormat() {
@@ -98,11 +106,13 @@ export default class LslStreamOutlet implements StreamOutlet {
     public pushSample(sample: LslSample) {
         const timestamp = this.lsl.localClock()
 
-        this.pushSampleByType({
-            outlet: this.outlet,
-            sample,
-            timestamp,
-        })
+        handleError(
+            this.pushSampleMethod({
+                outlet: this.outlet,
+                sample,
+                timestamp,
+            })
+        )
     }
 
     public destroy() {
@@ -133,24 +143,24 @@ export default class LslStreamOutlet implements StreamOutlet {
         return this.options.channelFormat
     }
 
-    public get sampleRate() {
-        return this.options.sampleRate
+    public get sampleRateHz() {
+        return this.options.sampleRateHz
     }
 
     public get chunkSize() {
         return this.options.chunkSize
     }
 
-    public get maxBuffered() {
-        return this.options.maxBuffered
+    public get maxBufferedMs() {
+        return this.options.maxBufferedMs ?? 360 * 1000
     }
 
     public get manufacturer() {
-        return this.options.manufacturer
+        return this.options.manufacturer ?? 'N/A'
     }
 
-    public get unit() {
-        return this.options.unit
+    public get units() {
+        return this.options.units ?? 'N/A'
     }
 
     private get boundStreamInfo() {
@@ -178,11 +188,11 @@ export interface StreamOutlet {
     readonly sourceId: string
     readonly channelNames: string[]
     readonly channelFormat: ChannelFormat
-    readonly sampleRate: number
+    readonly sampleRateHz: number
     readonly chunkSize: number
-    readonly maxBuffered: number
+    readonly maxBufferedMs: number
     readonly manufacturer: string
-    readonly unit: string
+    readonly units: string
 }
 
 export type StreamOutletConstructor = new (
@@ -196,10 +206,10 @@ export interface StreamOutletOptions {
     sourceId: string
     channelNames: string[]
     channelFormat: ChannelFormat
-    sampleRate: number
+    sampleRateHz: number
     chunkSize: number
-    maxBuffered: number
-    manufacturer: string
-    unit: string
+    maxBufferedMs?: number
+    manufacturer?: string
+    units?: string
     waitAfterConstructionMs?: number
 }

package/src/impl/LslWebSocketBridge.ts

@@ -1,13 +1,123 @@
+import { WebSocketServer } from 'ws'
+import { ChannelFormat } from './LiblslAdapter.js'
+import LslStreamInlet, { StreamInlet } from './LslStreamInlet.js'
+
 export default class LslWebSocketBridge implements StreamTransportBridge {
     public static Class?: StreamTransportBridgeConstructor
+    public static WSS = WebSocketServer
+
+    private inlet: StreamInlet
+    private wss: WebSocketServer
+    private isDestroyed = false
+
+    protected constructor(options: StreamTransportBridgeConstructorOptions) {
+        const { inlet, wss } = options
+
+        this.inlet = inlet
+        this.wss = wss
+    }
+
+    public static Create(options: StreamTransportBridgeOptions) {
+        const wss = this.WebSocketServer()
+        const inlet = this.LslStreamInlet(options, wss)
+
+        return new (this.Class ?? this)({ ...options, inlet, wss })
+    }
+
+    public activate() {
+        this.throwIfBridgeIsDestroyed()
+        this.startPullingData()
+    }
+
+    private throwIfBridgeIsDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error(
+                `\n\n Cannot re-activate bridge after destroying it! \n\n Please create and activate a new instance. \n`
+            )
+        }
+    }
+
+    private startPullingData() {
+        this.inlet.startPulling()
+    }
+
+    public deactivate() {
+        this.stopPullingData()
+    }
+
+    private stopPullingData() {
+        this.inlet.stopPulling()
+    }
 
-    protected constructor() {}
+    public destroy() {
+        this.destroyCppBoundInlet()
+        this.closeWebSocketServer()
+        this.isDestroyed = true
+    }
 
-    public static Create() {
-        return new (this.Class ?? this)()
+    private destroyCppBoundInlet() {
+        this.inlet.destroy()
     }
+
+    private closeWebSocketServer() {
+        this.wss.close()
+    }
+
+    private static createOnDataCallback(wss: WebSocketServer) {
+        return (samples: Float32Array, timestamps: Float64Array) => {
+            this.broadcastToClients(wss, samples, timestamps)
+        }
+    }
+
+    private static broadcastToClients(
+        wss: WebSocketServer,
+        samples: Float32Array<ArrayBufferLike>,
+        timestamps: Float64Array<ArrayBufferLike>
+    ) {
+        for (const client of wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(
+                    JSON.stringify({
+                        samples,
+                        timestamps,
+                    })
+                )
+            }
+        }
+    }
+
+    private static LslStreamInlet(
+        options: StreamTransportBridgeOptions,
+        wss: WebSocketServer
+    ) {
+        const onData = this.createOnDataCallback(wss)
+        return LslStreamInlet.Create(options, onData)
+    }
+
+    private static WebSocketServer() {
+        return new this.WSS({ port: 8080 })
+    }
+}
+
+export interface StreamTransportBridge {
+    activate(): void
+    deactivate(): void
+    destroy(): void
 }
 
-export interface StreamTransportBridge {}
+export type StreamTransportBridgeConstructor = new (
+    options: StreamTransportBridgeConstructorOptions
+) => StreamTransportBridge
+
+export interface StreamTransportBridgeOptions {
+    channelNames: string[]
+    channelFormat: ChannelFormat
+    sampleRateHz: number
+    chunkSize: number
+}
 
-export type StreamTransportBridgeConstructor = new () => StreamTransportBridge
+export interface StreamTransportBridgeConstructorOptions
+    extends StreamTransportBridgeOptions {
+    inlet: StreamInlet
+    wss: WebSocketServer
+}

package/src/index.ts

@@ -1,5 +1,3 @@
-export * from './types.js'
-
 // EventMarkerOutlet
 
 export { default as LslEventMarkerOutlet } from './impl/LslEventMarkerOutlet.js'

package/src/scripts/runLslStreamOutlet.ts

@@ -5,13 +5,12 @@ async function main() {
         name: 'Muse S (2nd gen)',
         type: 'EEG',
         channelNames: ['TP9', 'AF7', 'AF8', 'TP10', 'AUX'],
-        sampleRate: 256,
+        sampleRateHz: 256,
         channelFormat: 'float32',
         sourceId: 'muse-s-eeg',
         manufacturer: 'Interaxon Inc.',
-        unit: 'microvolt',
+        units: 'microvolt',
         chunkSize: 12,
-        maxBuffered: 360,
     })
 
     instance.pushSample([1, 2, 3, 4, 5])

package/src/scripts/runOutletToInlet.ts

@@ -0,0 +1,53 @@
+import LslStreamInlet from '../impl/LslStreamInlet.js'
+import LslStreamOutlet from '../impl/LslStreamOutlet.js'
+
+console.log('Creating outlet...')
+const outlet = await LslStreamOutlet.Create({
+    name: 'TestOutlet',
+    type: 'TEST',
+    sourceId: 'TestOutletID',
+    sampleRateHz: 100,
+    channelNames: ['Ch1', 'Ch2', 'Ch3'],
+    channelFormat: 'float32',
+    chunkSize: 1,
+    units: 'test',
+    manufacturer: 'test',
+})
+
+console.log('Creating inlet...')
+
+const inletOptions = {
+    name: 'TestOutlet',
+    type: 'TEST',
+    sourceId: 'TestOutletID',
+    sampleRateHz: 100,
+    channelNames: ['Ch1', 'Ch2', 'Ch3'],
+    channelFormat: 'float32' as const,
+    chunkSize: 1,
+}
+
+const inlet = LslStreamInlet.Create(inletOptions, (samples, timestamps) => {
+    console.log('Received samples:', samples, 'at timestamps:', timestamps)
+})
+
+console.log('Start pulling...')
+inlet.startPulling()
+
+console.log('Waiting for 100 ms...')
+await new Promise((resolve) => setTimeout(resolve, 100))
+
+console.log('Pushing samples...')
+for (let i = 0; i < 300; i++) {
+    const sample = [i, i, i]
+    outlet.pushSample(sample)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+}
+
+await new Promise((resolve) => setTimeout(resolve, 1000))
+
+console.log('Pushing more samples...')
+for (let i = 0; i < 30; i++) {
+    const sample = [i, i, i]
+    outlet.pushSample(sample)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+}