Skip to content

Class lsl::stream_info

ClassList > lsl > stream_info

More...

  • #include <lsl_cpp.h>

Public Functions

Type Name
std::string as_xml () const
int32_t channel_bytes () const
Number of bytes occupied by a channel (0 for string-typed channels).
int32_t channel_count () const
channel_format_t channel_format () const
stream_info clone ()
Clones a streaminfo object.
double created_at () const
xml_element desc ()
std::shared_ptr< lsl_streaminfo_struct_ > handle () const
Get the implementation handle.
std::string hostname () const
Hostname of the providing machine.
bool matches_query (const char * query) const
lsl_stream_info_matches_query
std::string name () const
double nominal_srate () const
stream_info & operator= (const stream_info & rhs)
Assignment operator.
stream_info & operator= (stream_info && rhs) noexcept
int32_t sample_bytes () const
Number of bytes occupied by a sample (0 for string-typed channels).
bool security_enabled () const
std::string security_fingerprint () const
std::string session_id () const
std::string source_id () const
stream_info (const std::string & name, const std::string & type, int32_t channel_count=1, double nominal_srate=IRREGULAR_RATE, channel_format_t channel_format=cf_float32, const std::string & source_id=std::string())
stream_info ()
Default contructor.
stream_info (const stream_info &) noexcept
Copy constructor. Only increments the reference count!
stream_info (lsl_streaminfo handle)
stream_info (stream_info && rhs) noexcept
std::string type () const
std::string uid () const
int32_t version () const
Protocol version used to deliver the stream.

Public Static Functions

Type Name
stream_info from_xml (const std::string & xml)
Utility function to create a stream_info from an XML representation.

Detailed Description

The stream_info object stores the declaration of a data stream.

Represents the following information: a) stream data format (number of channels, channel format) b) core information (stream name, content type, sampling rate) c) 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 stream_info to describe its properties and then construct a stream_outlet with it to create the stream on the network. Recipients who discover the outlet can query the stream_info; it is also written to disk when recording the stream (playing a similar role as a file header).

Public Functions Documentation

function as_xml

inline std::string lsl::stream_info::as_xml () const

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.

function channel_bytes

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

inline int32_t lsl::stream_info::channel_bytes () const

function channel_count

inline int32_t lsl::stream_info::channel_count () const

Number of channels of the stream.

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

function channel_format

inline channel_format_t lsl::stream_info::channel_format () const

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.

function clone

Clones a streaminfo object. 

inline stream_info lsl::stream_info::clone ()

function created_at

inline double lsl::stream_info::created_at () const

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).

function desc

inline xml_element lsl::stream_info::desc ()

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 (github.com/sccn/xdf/wiki/Meta-Data 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.

function handle

Get the implementation handle. 

inline std::shared_ptr< lsl_streaminfo_struct_ > lsl::stream_info::handle () const

function hostname

Hostname of the providing machine. 

inline std::string lsl::stream_info::hostname () const

function matches_query

lsl_stream_info_matches_query 

inline bool lsl::stream_info::matches_query (
    const char * query
) const

function name

inline std::string lsl::stream_info::name () const

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).

function nominal_srate

inline double lsl::stream_info::nominal_srate () const

Sampling rate of the stream, according to the source (in Hz).

If a stream is irregularly sampled, this should be set to 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.

function operator=

Assignment operator. 

inline stream_info & lsl::stream_info::operator= (
    const stream_info & rhs
)

function operator=

stream_info & lsl::stream_info::operator= (
    stream_info && rhs
) noexcept

function sample_bytes

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

inline int32_t lsl::stream_info::sample_bytes () const

function security_enabled

inline bool lsl::stream_info::security_enabled () const

Check if the stream has security/encryption enabled.

When security is enabled, all data transmitted on this stream is encrypted using ChaCha20-Poly1305 authenticated encryption.

Returns:

true if security is enabled, false otherwise.

function security_fingerprint

inline std::string lsl::stream_info::security_fingerprint () const

Get the security fingerprint of the stream's public key.

The fingerprint is a SHA256 hash of the device's Ed25519 public key, formatted as "SHA256:xxxx...". This can be used to verify device identity.

Returns:

The fingerprint string, or empty string if security is not enabled.

function session_id

inline std::string lsl::stream_info::session_id () const

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).

function source_id

inline std::string lsl::stream_info::source_id () const

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.

function stream_info [1/5]

inline lsl::stream_info::stream_info (
    const std::string & name,
    const std::string & type,
    int32_t channel_count=1,
    double nominal_srate=IRREGULAR_RATE,
    channel_format_t channel_format=cf_float32,
    const std::string & source_id=std::string()
)

Construct a new stream_info object.

Core stream information is specified here. Any remaining meta-data can be added later.

Parameters:

  • 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.
  • type Content type of the stream. Please see https://github.com/sccn/xdf/wiki/Meta-Data (or web search for: XDF meta-data) for pre-defined content-type names, 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 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 cf_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.

function stream_info [2/5]

Default contructor. 

inline lsl::stream_info::stream_info ()

function stream_info [3/5]

Copy constructor. Only increments the reference count! 

lsl::stream_info::stream_info (
    const stream_info &
) noexcept

See also: clone()

function stream_info [4/5]

inline lsl::stream_info::stream_info (
    lsl_streaminfo handle
)

function stream_info [5/5]

lsl::stream_info::stream_info (
    stream_info && rhs
) noexcept

function type

inline std::string lsl::stream_info::type () const

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 in https://github.com/sccn/xdf/wiki/Meta-Data (or web search for: XDF meta-data).

function uid

inline std::string lsl::stream_info::uid () const

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).

function version

Protocol version used to deliver the stream. 

inline int32_t lsl::stream_info::version () const

Public Static Functions Documentation

function from_xml

Utility function to create a stream_info from an XML representation. 

static inline stream_info lsl::stream_info::from_xml (
    const std::string & xml
)

The documentation for this class was generated from the following file liblsl/include/lsl_cpp.h