Struct lsl::StreamInfo

pub struct StreamInfo { /* fields omitted */ }

The StreamInfo object stores the declaration of a data stream.

It represents the following information:

• stream data format (number of channels, channel format)
• core information (stream name, content type, sampling rate)
• optional meta-data about the stream content (channel labels, measurement units, etc.)

Whenever a program wants to provide a new stream on the lab network it will typically first create a StreamInfo to describe its properties and then construct a StreamOutlet with it to create the stream on the network.

The stream can then be discovered based on any of its meta-data, and recipients who discover the stream on the network can then query the full stream information.

The content of the StreamInfo encompasses all the static information that is known up-front about a data stream, and therefore, anything you would expect to find in a file header for a streaming data file should be written into the stream info (in fact, if you use a tool to record one or more streams into an XDF file, the stream info goes into the file header.

Examples: this library comes with example scripts for all common use cases (found in the crate's github repository). You can find various uses of the StreamInfo object in most of these files.

Implementations

impl StreamInfo

pub fn new(
    stream_name: &str,
    stream_type: &str,
    channel_count: u32,
    nominal_srate: f64,
    channel_format: ChannelFormat,
    source_id: &str
) -> Result<StreamInfo, Error>

Construct a new StreamInfo object. Core stream information is specified here. Any remaining meta-data can be added subsequently.

Arguments:

• stream_name: Name of the stream. Describes the device (or product series) that this stream makes available (for use by programs, experimenters or data analysts). Cannot be empty.
• stream_type: Content type of the stream. Please see here (or web search for: XDF meta-data) for pre-defined content-type names that LSL adheres to, but you can also make up your own. The content type is the preferred way to find streams (as opposed to searching by name).
• channel_count: Number of channels per sample. This stays constant for the lifetime of the stream.
• nominal_srate: The sampling rate (in Hz) as advertised by the data source, if regular (otherwise set to lsl::IRREGULAR_RATE).
• channel_format: Format/type of each channel. If your channels have different formats, consider supplying multiple streams or use the largest type that can hold them all (such as ChannelFormat::Double64).
• source_id: Unique identifier of the device or source of the data, if available (such as the serial number). This is critical for system robustness since it allows recipients to recover from failure even after the serving app, device or computer crashes (just by finding a stream with the same source id on the network again). Therefore, it is highly recommended to always try to provide whatever information can uniquely identify the data source itself. If you don't have a unique id, you may use an empty str here.

pub fn stream_name(&self) -> String

Name of the stream. This is a human-readable name. For streams offered by device modules, it refers to the type of device or product series that is generating the data of the stream. If the source is an application, the name may be a more generic or specific identifier. Multiple streams with the same name can coexist, though potentially at the cost of ambiguity (for the recording app or experimenter).

pub fn stream_type(&self) -> String

Content type of the stream. The content type is a short string such as "EEG", "Gaze" which describes the content carried by the channel (if known). If a stream contains mixed content this value need not be assigned but may instead be stored in the description of channel types. To be useful to applications and automated processing systems, using the recommended content types is preferred. Content types usually follow those pre-defined here (or web search for: XDF meta-data).

pub fn channel_count(&self) -> i32

Number of channels of the stream. A stream has at least one channel; the channel count stays constant for all samples.

pub fn nominal_srate(&self) -> f64

Sampling rate of the stream, according to the source (in Hz). If a stream is irregularly sampled, this should be set to lsl::IRREGULAR_RATE.

Note that no data will be lost even if this sampling rate is incorrect or if a device has temporary hiccups, since all samples will be recorded anyway (except for those dropped by the device itself). However, when the recording is imported into an application, a good importer may correct such errors more accurately if the advertised sampling rate was close to the specs of the device.

pub fn channel_format(&self) -> ChannelFormat

Channel format of the stream. All channels in a stream have the same format. However, a device might offer multiple time-synched streams each with its own format.

pub fn source_id(&self) -> String

Unique identifier of the stream's source, if available. The unique source (or device) identifier is an optional piece of information that, if available, allows that endpoints (such as the recording program) can re-acquire a stream automatically once it is back online.

pub fn version(&self) -> i32

Protocol version used to deliver the stream. Formatted like lsl::protocol_version().

pub fn created_at(&self) -> f64

Creation time stamp of the stream. This is the time stamp when the stream was first created (as determined via lsl::local_clock() on the providing machine).

pub fn uid(&self) -> String

Unique ID of the stream outlet instance (once assigned). This is a unique identifier of the stream outlet, and is guaranteed to be different across multiple instantiations of the same outlet (e.g., after a re-start).

pub fn session_id(&self) -> String

Session ID for the given stream. The session id is an optional human-assigned identifier of the recording session. While it is rarely used, it can be used to prevent concurrent recording activitites on the same sub-network (e.g., in multiple experiment areas) from seeing each other's streams (assigned via a configuration file by the experimenter, see Network Connectivity in the LSL wiki).

pub fn hostname(&self) -> String

Hostname of the providing machine.

pub fn desc(&mut self) -> XMLElement

Access the extended description of the stream.

It is highly recommended that at least the channel labels are described here. See code examples on the LSL wiki. Other information, such as amplifier settings, measurement units if deviating from defaults, setup information, subject information, etc., can be specified here, as well. Meta-data recommendations follow the XDF file format project here (or web search for: XDF meta-data).

Important: if you use a stream content type for which meta-data recommendations exist, please try to lay out your meta-data in agreement with these recommendations for compatibility with other applications.

pub fn matches_query(&self, query: &str) -> bool

Test whether the stream information matches the given query string. The query is evaluated using the same rules that govern lsl::resolve_bypred().

pub fn to_xml(&self) -> Result<String, Error>

Retrieve the entire streaminfo in XML format. This yields an XML document (in string form) whose top-level element is <info>. The info element contains one element for each field of the streaminfo class, including:

• the core elements <name>, <type>, <channel_count, <nominal_srate>, <channel_format>, <source_id>
• the misc elements <version>, <created_at>, <uid>, <session_id>, <v4address>, <v4data_port>, <v4service_port>, <v6address>, <v6data_port>, <v6service_port>
• the extended description element <desc> with user-defined sub-elements.

pub fn channel_bytes(&self) -> i32

Number of bytes occupied by a channel (0 for string-typed channels).

pub fn sample_bytes(&self) -> i32

Number of bytes occupied by a sample (0 for string-typed channels).

pub fn from_blank() -> Result<StreamInfo, Error>

Construct a blank StreamInfo.

pub fn from_xml(xml: &str) -> Result<StreamInfo, Error>

Create a StreamInfo from an XML string.

Trait Implementations

impl Clone for StreamInfo

fn clone(&self) -> StreamInfo

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StreamInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for StreamInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.