@neurodevs/node-lsl 12.0.6 → 13.0.0

package/src/assertions.ts

@@ -1,5 +1,5 @@
+import { ChannelFormat } from 'impl/LiblslAdapter.js'
 import { CHANNEL_FORMATS } from './consts.js'
-import { ChannelFormat } from './types.js'
 import {
     isGreaterThanOrEqualToZero,
     isPositiveInteger,
@@ -15,10 +15,10 @@ export function assertValidChunkSize(chunkSize: number) {
     }
 }
 
-export function assertValidMaxBuffered(maxBuffered: number) {
-    if (!isPositiveIntegerOrZero(maxBuffered)) {
+export function assertValidMaxBufferedMs(maxBufferedMs: number) {
+    if (!isPositiveIntegerOrZero(maxBufferedMs)) {
         throw new Error(
-            `Invalid max buffered! Must be a positive integer or zero, not: ${maxBuffered}.`
+            `Invalid max buffered! Must be a positive integer or zero, not: ${maxBufferedMs}.`
         )
     }
 }
@@ -31,10 +31,10 @@ export function assertValidChannelFormat(channelFormat: ChannelFormat) {
     }
 }
 
-export function assertValidSampleRate(sampleRate: number) {
-    if (!isGreaterThanOrEqualToZero(sampleRate)) {
+export function assertValidSampleRateHz(sampleRateHz: number) {
+    if (!isGreaterThanOrEqualToZero(sampleRateHz)) {
         throw new Error(
-            `Invalid sample rate! Must be a positive number or zero, not: ${sampleRate}.`
+            `Invalid sample rate! Must be a positive number or zero, not: ${sampleRateHz}.`
         )
     }
 }

package/src/handleError.ts

@@ -0,0 +1,24 @@
+export default function handleError(errorCode: number) {
+    switch (errorCode) {
+        case 0:
+            return
+        case -1:
+            throw new Error(`The liblsl operation failed due to a timeout!`)
+        case -2:
+            throw new Error(`The liblsl stream has been lost!`)
+        case -3:
+            throw new Error(`A liblsl argument was incorrectly specified!`)
+        case -4:
+            throw new Error(`An internal liblsl error has occurred!`)
+        default:
+            throw new Error(`An unknown liblsl error has occurred!`)
+    }
+}
+
+export enum LslErrorCode {
+    Ok = 0,
+    Timeout = -1,
+    Lost = -2,
+    BadArgument = -3,
+    InternalError = -4,
+}

package/src/impl/LiblslAdapter.ts

@@ -1,42 +1,37 @@
-import { DataType, define, open } from 'ffi-rs'
-
-import {
-    Liblsl,
-    LiblslBindings,
-    CreateStreamInfoOptions,
-    AppendChannelsToStreamInfoOptions,
-    CreateOutletOptions,
-    DestroyOutletOptions,
-    PushSampleFloatTimestampOptions,
-    PushSampleStringTimestampOptions,
-    CreateInletOptions,
-    DestroyInletOptions,
-    FlushInletOptions,
-} from '../types.js'
+import { DataType, define, JsExternal, load, open, unwrapPointer } from 'ffi-rs'
+
+import { CHANNEL_FORMATS } from '../consts.js'
+import { LslErrorCode } from '../handleError.js'
 
 export default class LiblslAdapter implements Liblsl {
-    public static ffiRsOpen = open
-    public static ffiRsDefine = define
+    public static open = open
+    public static define = define
+    public static load = load
+
     private static instance?: Liblsl
 
-    private path: string
+    public liblslPath: string
     private bindings!: LiblslBindings
 
+    private readonly defaultMacOsPath = `/opt/homebrew/Cellar/lsl/1.16.2/lib/liblsl.1.16.2.dylib`
+
     protected constructor() {
-        this.path = process.env.LIBLSL_PATH! ?? this.defaultMacOsPath
+        this.liblslPath = process.env.LIBLSL_PATH ?? this.defaultMacOsPath
         this.tryToLoadBindings()
     }
 
     private tryToLoadBindings() {
         try {
-            this.bindings = this.loadBindings(this.path)
+            this.loadBindings()
         } catch (error) {
-            throw new Error(this.generateFailedMessage(error as Error))
+            this.throwFailedToLoadLiblsl(error as Error)
         }
     }
 
-    private generateFailedMessage(error: Error) {
-        return `Loading the liblsl dylib failed! I tried to load it from ${this.path}.\n\n${error.message}\n\n`
+    private throwFailedToLoadLiblsl(error: Error) {
+        throw new Error(
+            `Loading the liblsl dylib failed! I tried to load it from ${this.liblslPath}.\n\n${error.message}\n\n`
+        )
     }
 
     public static getInstance() {
@@ -54,13 +49,193 @@ export default class LiblslAdapter implements Liblsl {
         delete this.instance
     }
 
-    private loadBindings(liblslPath: string) {
-        LiblslAdapter.ffiRsOpen({
+    private loadBindings() {
+        this.openLiblsl()
+        this.bindings = this.defineLiblslBindings()
+    }
+
+    private openLiblsl() {
+        this.open({
+            library: 'lsl',
+            path: this.liblslPath,
+        })
+    }
+
+    private defineLiblslBindings() {
+        return this.define(this.liblslFuncs) as unknown as LiblslBindings
+    }
+
+    public createStreamInfo(options: CreateStreamInfoOptions) {
+        const {
+            name,
+            type,
+            channelCount,
+            sampleRateHz,
+            channelFormat,
+            sourceId,
+        } = options
+
+        return this.bindings.lsl_create_streaminfo([
+            name,
+            type,
+            channelCount,
+            sampleRateHz,
+            channelFormat,
+            sourceId,
+        ])
+    }
+
+    public appendChannelsToStreamInfo(
+        options: AppendChannelsToStreamInfoOptions
+    ) {
+        const { info, channels } = options
+
+        const description = this.bindings.lsl_get_desc([info])
+        const parent = this.bindings.lsl_append_child([description, 'channels'])
+
+        for (const channel of channels) {
+            const child = this.bindings.lsl_append_child([parent, 'channel'])
+            this.bindings.lsl_append_child_value([
+                child,
+                'label',
+                channel.label,
+            ])
+            this.bindings.lsl_append_child_value([child, 'unit', channel.units])
+            this.bindings.lsl_append_child_value([child, 'type', channel.type])
+        }
+    }
+
+    public createOutlet(options: CreateOutletOptions) {
+        const { info, chunkSize, maxBufferedMs } = options
+
+        return this.bindings.lsl_create_outlet([
+            info,
+            chunkSize,
+            maxBufferedMs / 1000,
+        ])
+    }
+
+    public pushSampleFloatTimestamp(options: PushSampleFloatTimestampOptions) {
+        const { outlet, sample, timestamp } = options
+        return this.bindings.lsl_push_sample_ft([outlet, sample, timestamp])
+    }
+
+    public pushSampleStringTimestamp(
+        options: PushSampleStringTimestampOptions
+    ) {
+        const { outlet, sample, timestamp } = options
+        return this.bindings.lsl_push_sample_strt([outlet, sample, timestamp])
+    }
+
+    public destroyOutlet(options: DestroyOutletOptions) {
+        const { outlet } = options
+        this.bindings.lsl_destroy_outlet([outlet])
+    }
+
+    public createInlet(options: CreateInletOptions) {
+        const { info, chunkSize, maxBufferedMs } = options
+
+        return this.bindings.lsl_create_inlet([
+            info,
+            chunkSize,
+            maxBufferedMs / 1000,
+        ])
+    }
+
+    public pullSample(options: PullSampleOptions) {
+        const {
+            inlet,
+            dataBufferPtr,
+            dataBufferElements,
+            timeout,
+            errcodePtr,
+        } = options
+
+        return this.load({
+            library: 'lsl',
+            funcName: 'lsl_pull_sample_f',
+            retType: DataType.Double,
+            paramsType: [
+                DataType.External,
+                DataType.External,
+                DataType.I32,
+                DataType.Double,
+                DataType.External,
+            ],
+            paramsValue: [
+                inlet,
+                dataBufferPtr,
+                dataBufferElements,
+                timeout,
+                errcodePtr,
+            ],
+        })
+    }
+
+    public pullChunk(options: PullChunkOptions) {
+        const {
+            inlet,
+            dataBufferPtr,
+            timestampBufferPtr,
+            dataBufferElements,
+            timestampBufferElements,
+            timeout,
+            errcodePtr,
+        } = options
+
+        return this.load({
             library: 'lsl',
-            path: liblslPath,
+            funcName: 'lsl_pull_chunk_f',
+            retType: DataType.Double,
+            paramsType: [
+                DataType.External,
+                DataType.External,
+                DataType.External,
+                DataType.I32,
+                DataType.I32,
+                DataType.Double,
+                DataType.External,
+            ],
+            paramsValue: [
+                inlet,
+                unwrapPointer([dataBufferPtr])[0],
+                unwrapPointer([timestampBufferPtr])[0],
+                dataBufferElements,
+                timestampBufferElements,
+                timeout,
+                unwrapPointer([errcodePtr])[0],
+            ],
         })
+    }
+
+    public flushInlet(options: FlushInletOptions) {
+        const { inlet } = options
+        this.bindings.lsl_flush_inlet([inlet])
+    }
+
+    public destroyInlet(options: DestroyInletOptions) {
+        const { inlet } = options
+        this.bindings.lsl_destroy_inlet([inlet])
+    }
+
+    public localClock() {
+        return this.bindings.lsl_local_clock([])
+    }
+
+    private get open() {
+        return LiblslAdapter.open
+    }
+
+    private get define() {
+        return LiblslAdapter.define
+    }
 
-        return LiblslAdapter.ffiRsDefine({
+    private get load() {
+        return LiblslAdapter.load
+    }
+
+    private get liblslFuncs() {
+        return {
             lsl_create_streaminfo: {
                 library: 'lsl',
                 retType: DataType.External,
@@ -80,7 +255,7 @@ export default class LiblslAdapter implements Liblsl {
             },
             lsl_push_sample_ft: {
                 library: 'lsl',
-                retType: DataType.Void,
+                retType: DataType.I32,
                 paramsType: [
                     DataType.External,
                     DataType.FloatArray,
@@ -89,7 +264,7 @@ export default class LiblslAdapter implements Liblsl {
             },
             lsl_push_sample_strt: {
                 library: 'lsl',
-                retType: DataType.Void,
+                retType: DataType.I32,
                 paramsType: [
                     DataType.External,
                     DataType.StringArray,
@@ -140,87 +315,137 @@ export default class LiblslAdapter implements Liblsl {
                 retType: DataType.Double,
                 paramsType: [],
             },
-        }) as unknown as LiblslBindings
+        }
     }
+}
 
-    public createStreamInfo(options: CreateStreamInfoOptions) {
-        const {
-            name,
-            type,
-            channelCount,
-            sampleRate,
-            channelFormat,
-            sourceId,
-        } = options
+export interface Liblsl {
+    liblslPath: string
 
-        return this.bindings.lsl_create_streaminfo([
-            name,
-            type,
-            channelCount,
-            sampleRate,
-            channelFormat,
-            sourceId,
-        ])
-    }
+    createStreamInfo(options: CreateStreamInfoOptions): BoundStreamInfo
+    appendChannelsToStreamInfo(options: AppendChannelsToStreamInfoOptions): void
 
-    public appendChannelsToStreamInfo(
-        options: AppendChannelsToStreamInfoOptions
-    ) {
-        const { info, channels } = options
+    createOutlet(options: CreateOutletOptions): BoundOutlet
 
-        const description = this.bindings.lsl_get_desc([info])
-        const parent = this.bindings.lsl_append_child([description, 'channels'])
+    pushSampleFloatTimestamp(
+        options: PushSampleFloatTimestampOptions
+    ): LslErrorCode
 
-        for (const channel of channels) {
-            const child = this.bindings.lsl_append_child([parent, 'channel'])
-            this.bindings.lsl_append_child_value([
-                child,
-                'label',
-                channel.label,
-            ])
-            this.bindings.lsl_append_child_value([child, 'unit', channel.unit])
-            this.bindings.lsl_append_child_value([child, 'type', channel.type])
-        }
-    }
+    pushSampleStringTimestamp(
+        options: PushSampleStringTimestampOptions
+    ): LslErrorCode
 
-    public createOutlet(options: CreateOutletOptions) {
-        const { info, chunkSize, maxBuffered } = options
-        return this.bindings.lsl_create_outlet([info, chunkSize, maxBuffered])
-    }
+    destroyOutlet(options: DestroyOutletOptions): void
 
-    public pushSampleFloatTimestamp(options: PushSampleFloatTimestampOptions) {
-        const { outlet, sample, timestamp } = options
-        this.bindings.lsl_push_sample_ft([outlet, sample, timestamp])
-    }
+    createInlet(options: CreateInletOptions): BoundInlet
+    pullSample(options: PullSampleOptions): number
+    pullChunk(options: PullChunkOptions): number
+    flushInlet(options: FlushInletOptions): void
+    destroyInlet(options: DestroyInletOptions): void
 
-    public pushSampleStringTimestamp(
-        options: PushSampleStringTimestampOptions
-    ) {
-        const { outlet, sample, timestamp } = options
-        this.bindings.lsl_push_sample_strt([outlet, sample, timestamp])
-    }
+    localClock(): number
+}
 
-    public destroyOutlet(options: DestroyOutletOptions) {
-        const { outlet } = options
-        this.bindings.lsl_destroy_outlet([outlet])
-    }
+export interface CreateStreamInfoOptions {
+    name: string
+    type: string
+    channelCount: number
+    sampleRateHz: number
+    channelFormat: number
+    sourceId: string
+    manufacturer?: string
+    units?: string
+}
 
-    public createInlet(options: CreateInletOptions) {
-        const { info, chunkSize, maxBuffered } = options
-        return this.bindings.lsl_create_inlet([info, chunkSize, maxBuffered])
-    }
+export interface AppendChannelsToStreamInfoOptions {
+    info: BoundStreamInfo
+    channels: LslChannel[]
+}
 
-    public flushInlet(options: FlushInletOptions) {
-        const { inlet } = options
-        this.bindings.lsl_flush_inlet([inlet])
-    }
+export interface CreateOutletOptions {
+    info: BoundStreamInfo
+    chunkSize: number
+    maxBufferedMs: number
+}
 
-    public destroyInlet(_options: DestroyInletOptions) {}
+export interface PushSampleFloatTimestampOptions {
+    outlet: BoundOutlet
+    sample: number[]
+    timestamp: number
+}
 
-    public localClock() {
-        return this.bindings.lsl_local_clock([])
-    }
+export interface PushSampleStringTimestampOptions {
+    outlet: BoundOutlet
+    sample: string[]
+    timestamp: number
+}
+
+export interface DestroyOutletOptions {
+    outlet: BoundOutlet
+}
+
+export interface CreateInletOptions {
+    info: BoundStreamInfo
+    chunkSize: number
+    maxBufferedMs: number
+}
 
-    private readonly defaultMacOsPath =
-        '/opt/homebrew/Cellar/lsl/1.16.2/lib/liblsl.1.16.2.dylib'
+export interface PullSampleOptions {
+    inlet: BoundInlet
+    dataBufferPtr: JsExternal
+    dataBufferElements: number
+    timeout: number
+    errcodePtr: JsExternal
 }
+
+export interface PullChunkOptions {
+    inlet: BoundInlet
+    dataBufferPtr: JsExternal
+    timestampBufferPtr: JsExternal
+    dataBufferElements: number
+    timestampBufferElements: number
+    timeout: number
+    errcodePtr: JsExternal
+}
+
+export interface FlushInletOptions {
+    inlet: BoundInlet
+}
+
+export interface DestroyInletOptions {
+    inlet: BoundInlet
+}
+
+export interface LiblslBindings {
+    lsl_create_streaminfo(
+        args: [string, string, number, number, number, string]
+    ): BoundStreamInfo
+
+    lsl_create_outlet(args: [BoundStreamInfo, number, number]): BoundOutlet
+    lsl_push_sample_ft(args: [BoundOutlet, LslSample, number]): LslErrorCode
+    lsl_push_sample_strt(args: [BoundOutlet, LslSample, number]): LslErrorCode
+    lsl_destroy_outlet(args: [BoundOutlet]): void
+    lsl_create_inlet(args: any): BoundInlet
+    lsl_flush_inlet(args: [BoundInlet]): void
+    lsl_destroy_inlet(args: any): void
+    lsl_local_clock(args: []): number
+    lsl_get_desc(args: [BoundStreamInfo]): BoundDescription
+    lsl_append_child(args: [BoundDescription, string]): BoundChild
+    lsl_append_child_value(args: [BoundChild, string, string]): void
+}
+
+export type ChannelFormat = (typeof CHANNEL_FORMATS)[number]
+
+export interface LslChannel {
+    label: string
+    units: string
+    type: string
+}
+
+export type LslSample = (number | string | undefined)[]
+
+export interface BoundStreamInfo {}
+export interface BoundOutlet {}
+export interface BoundInlet {}
+export interface BoundDescription {}
+export interface BoundChild {}

package/src/impl/LslEventMarkerOutlet.ts

@@ -1,4 +1,3 @@
-import { DurationMarker } from '../types.js'
 import LslStreamOutlet, {
     StreamOutletOptions,
     StreamOutlet,
@@ -21,13 +20,13 @@ export default class LslEventMarkerOutlet implements EventMarkerOutlet {
             name: 'Event markers',
             type: 'Markers',
             channelNames: ['Markers'],
-            sampleRate: 0,
+            sampleRateHz: 0,
             channelFormat: 'string',
             sourceId: 'event-markers',
             manufacturer: 'N/A',
-            unit: 'N/A',
+            units: 'N/A',
             chunkSize: 0,
-            maxBuffered: 0,
+            maxBufferedMs: 0,
         } as StreamOutletOptions
 
         const outlet = await LslStreamOutlet.Create({
@@ -86,3 +85,8 @@ export interface EventMarkerOutlet {
 export type EventMarkerOutletConstructor = new (
     outlet: StreamOutlet
 ) => EventMarkerOutlet
+
+export interface DurationMarker {
+    name: string
+    durationMs: number
+}

package/src/impl/LslStreamInfo.ts

@@ -1,7 +1,7 @@
 import generateId from '@neurodevs/generate-id'
 
 import { CHANNEL_FORMATS_MAP } from '../consts.js'
-import { BoundStreamInfo, ChannelFormat } from '../types.js'
+import { BoundStreamInfo, ChannelFormat } from './LiblslAdapter.js'
 import LiblslAdapter from './LiblslAdapter.js'
 
 export default class LslStreamInfo implements StreamInfo {
@@ -14,16 +14,16 @@ export default class LslStreamInfo implements StreamInfo {
     protected streamInfo!: BoundStreamInfo
     private channelNames: string[]
     private channelFormat: ChannelFormat
-    private sampleRate: number
+    private sampleRateHz: number
 
     protected constructor(options: StreamInfoOptions) {
         const {
-            channelNames,
-            channelFormat,
-            sampleRate,
             name = this.defaultName,
             type = this.defaultType,
             sourceId = this.defaultSourceId,
+            channelNames,
+            channelFormat,
+            sampleRateHz,
             units = this.defaultUnits,
         } = options
 
@@ -32,8 +32,8 @@ export default class LslStreamInfo implements StreamInfo {
         this.sourceId = sourceId
         this.channelNames = channelNames
         this.channelFormat = channelFormat
+        this.sampleRateHz = sampleRateHz
         this.units = units
-        this.sampleRate = sampleRate
 
         this.createStreamInfo()
         this.appendChannelsToStreamInfo()
@@ -50,7 +50,7 @@ export default class LslStreamInfo implements StreamInfo {
             sourceId: this.sourceId,
             channelCount: this.channelCount,
             channelFormat: this.lslChannelFormat,
-            sampleRate: this.sampleRate,
+            sampleRateHz: this.sampleRateHz,
         })
     }
 
@@ -59,7 +59,7 @@ export default class LslStreamInfo implements StreamInfo {
             info: this.streamInfo,
             channels: this.channelNames.map((label: string) => ({
                 label,
-                unit: this.units,
+                units: this.units,
                 type: this.type,
             })),
         })
@@ -96,7 +96,7 @@ type StreamInfoConstructor = new (options: StreamInfoOptions) => StreamInfo
 export interface StreamInfoOptions {
     channelNames: string[]
     channelFormat: ChannelFormat
-    sampleRate: number
+    sampleRateHz: number
     name?: string
     type?: string
     sourceId?: string