node-labstreaminglayer
Version:
Node.js bindings for Lab Streaming Layer (LSL)
252 lines • 9 kB
TypeScript
/**
* @fileoverview StreamInfo class and XMLElement class for LSL stream metadata.
*
* This module provides classes for declaring and manipulating stream metadata.
* StreamInfo objects describe the properties of a data stream including its
* name, type, channel count, sampling rate, and data format.
*
* @module streamInfo
* @see {@link https://labstreaminglayer.readthedocs.io/} - LSL Documentation
*/
/**
* Represents the declaration of a data stream.
*
* StreamInfo is the primary metadata container for LSL streams. It stores:
* - Core properties: name, type, channel count, sampling rate, data format
* - Unique identifiers: source_id, uid, session_id
* - Host information: hostname, version, creation time
* - Extended metadata: channel labels, units, types via XML description
*
* @example
* ```typescript
* // Create a simple EEG stream
* const info = new StreamInfo('MyEEGStream', 'EEG', 8, 250, 'float32');
*
* // Add channel labels
* info.setChannelLabels(['Fp1', 'Fp2', 'F3', 'F4', 'C3', 'C4', 'P3', 'P4']);
* ```
*
* @class
*/
export declare class StreamInfo {
/** Pointer to the underlying LSL streaminfo C object */
private obj;
/**
* Creates a new StreamInfo object.
*
* @param {string} name - Human-readable name of the stream (e.g., 'BioSemi')
* @param {string} type - Content type of the stream (e.g., 'EEG', 'Markers', 'Audio')
* @param {number} channelCount - Number of channels in the stream
* @param {number} nominalSrate - Nominal sampling rate in Hz (0 for irregular)
* @param {number|string} channelFormat - Data format ('float32', 'string', etc. or constant)
* @param {string|null} sourceId - Unique source identifier (auto-generated if not provided)
* @param {any} handle - Internal: existing C object handle for wrapping
*
* @throws {Error} If channel format is unknown or stream creation fails
*/
constructor(name?: string, type?: string, channelCount?: number, nominalSrate?: number, channelFormat?: number | string, sourceId?: string | null, handle?: any);
/**
* Manually destroy the stream info object and free resources.
* This is called automatically when the object is garbage collected.
*/
destroy(): void;
/**
* Get the stream name.
* @returns The name of the stream
*/
name(): string;
/**
* Get the stream type.
* @returns The content type of the stream (e.g., 'EEG', 'Markers')
*/
type(): string;
/**
* Get the number of channels.
* @returns The channel count of the stream
*/
channelCount(): number;
/**
* Get the nominal sampling rate.
* @returns The sampling rate in Hz (0 for irregular rate)
*/
nominalSrate(): number;
/**
* Get the channel format.
* @returns The numeric channel format constant
*/
channelFormat(): number;
/**
* Get the unique source identifier.
* @returns The source ID of the stream
*/
sourceId(): string;
/**
* Get the protocol version used by the stream.
* @returns {number} LSL protocol version number
*/
version(): number;
/**
* Get the creation timestamp of the stream.
* @returns {number} LSL timestamp when the stream was created
*/
createdAt(): number;
/**
* Get the unique identifier of the stream.
* This UID is generated when the stream is created and remains constant.
* @returns {string} Unique stream identifier
*/
uid(): string;
/**
* Get the session identifier.
* Changes when the host system restarts or LSL is reinitialized.
* @returns {string} Current session identifier
*/
sessionId(): string;
/**
* Get the hostname of the machine hosting the stream.
* @returns {string} Hostname or IP address
*/
hostname(): string;
/**
* Get the XML description of the stream.
* This contains extended metadata like channel labels, units, etc.
* @returns {XMLElement} Root XML element for manipulation
*/
desc(): XMLElement;
/**
* Get the complete stream metadata as an XML string.
* Useful for debugging or saving stream configuration.
* @returns {string} XML representation of all stream metadata
*/
asXml(): string;
/**
* Get the labels for all channels.
* @returns {string[]|null} Array of channel labels or null if not set
* @example
* const labels = info.getChannelLabels(); // ['Fp1', 'Fp2', ...]
*/
getChannelLabels(): string[] | null;
/**
* Get the types for all channels.
* @returns {string[]|null} Array of channel types or null if not set
* @example
* const types = info.getChannelTypes(); // ['EEG', 'EEG', ...]
*/
getChannelTypes(): string[] | null;
/**
* Get the units for all channels.
* @returns {string[]|null} Array of channel units or null if not set
* @example
* const units = info.getChannelUnits(); // ['microvolts', 'microvolts', ...]
*/
getChannelUnits(): string[] | null;
/**
* Generic helper to extract channel information from XML.
* @private
* @param {string} name - Property name to extract ('label', 'type', or 'unit')
* @returns {string[]|null} Array of values or null if not found
*/
private _getChannelInfo;
/**
* Set labels for all channels.
* @param {string[]} labels - Array of channel labels (must match channel count)
* @throws {Error} If array length doesn't match channel count
* @example
* info.setChannelLabels(['Fp1', 'Fp2', 'F3', 'F4']);
*/
setChannelLabels(labels: string[]): void;
/**
* Set types for all channels.
* @param {string|string[]} types - Single type for all channels or array of types
* @example
* info.setChannelTypes('EEG'); // All channels are EEG
* info.setChannelTypes(['EEG', 'EEG', 'EOG', 'EOG']); // Mixed types
*/
setChannelTypes(types: string | string[]): void;
/**
* Set units for all channels.
* @param {string|number|(string|number)[]} units - Single unit or array of units
* @example
* info.setChannelUnits('microvolts'); // All channels in microvolts
* info.setChannelUnits(['microvolts', 'millivolts', 'celsius', 'percent']);
*/
setChannelUnits(units: string | number | (string | number)[]): void;
/**
* Generic helper to set channel information in XML.
* @private
* @param {string[]} chInfos - Array of values to set
* @param {string} name - Property name ('label', 'type', or 'unit')
* @throws {Error} If array length doesn't match channel count
*/
private _setChannelInfo;
/**
* Helper to ensure an XML node exists, creating it if necessary.
* @private
*/
private static _addFirstNode;
/**
* Helper to remove excess XML nodes.
* @private
*/
private static _pruneDescriptionNode;
/**
* Helper to set values in XML nodes.
* @private
*/
private static _setDescriptionNode;
/**
* Get the internal C object handle.
* @internal Used by StreamOutlet and StreamInlet
* @returns {any} Pointer to the C streaminfo object
*/
getHandle(): any;
}
/**
* Represents an XML element in the stream description.
*
* XMLElement provides methods for navigating and manipulating the XML tree
* structure that stores extended stream metadata. This is used for channel
* descriptions, hardware settings, synchronization parameters, etc.
*
* @example
* ```typescript
* const desc = info.desc();
* const acq = desc.appendChild('acquisition');
* acq.appendChildValue('manufacturer', 'ACME');
* acq.appendChildValue('model', 'StreamMaster3000');
* ```
*
* @class
*/
export declare class XMLElement {
/** Pointer to the underlying LSL XML element */
private e;
/**
* Creates an XMLElement wrapper.
* @internal Created internally by StreamInfo methods
* @param {any} handle - C XML element pointer
*/
constructor(handle: any);
firstChild(): XMLElement;
lastChild(): XMLElement;
child(name: string): XMLElement;
nextSibling(name?: string): XMLElement;
previousSibling(name?: string): XMLElement;
parent(): XMLElement;
empty(): boolean;
isText(): boolean;
name(): string;
value(): string;
childValue(name?: string): string;
appendChildValue(name: string, value: string): XMLElement;
prependChildValue(name: string, value: string): XMLElement;
setChildValue(name: string, value: string): XMLElement;
setName(name: string): boolean;
setValue(value: string): boolean;
appendChild(name: string): XMLElement;
prependChild(name: string): XMLElement;
appendCopy(elem: XMLElement): XMLElement;
prependCopy(elem: XMLElement): XMLElement;
removeChild(rhs: XMLElement | string): void;
}
//# sourceMappingURL=streamInfo.d.ts.map