Stream Info¶
A stream info object stores the stream’s Metadata.
Doxygen output¶
-
class
stream_info
¶ Public Functions
-
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.
-
std::string
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).
-
std::string
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).
-
int32_t
channel_count
() const¶ Number of channels of the stream.
A stream has at least one channel; the channel count stays constant for all samples.
-
double
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.
-
channel_format_t
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.
-
std::string
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.
-
int32_t
version
() const¶ Protocol version used to deliver the stream.
-
double
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).
-
std::string
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).
-
std::string
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).
-
std::string
hostname
() const¶ Hostname of the providing machine.
-
xml_element
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.
-
bool
matches_query
(const char *query) const¶ Tries to match the stream info XML element
info
against an XPath query.Example query strings:
channel_count>5 and type='EEG' type='TestStream' or contains(name,'Brain') name='ExampleStream'
-
std::string
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.
-
int32_t
channel_bytes
() const¶ Number of bytes occupied by a channel (0 for string-typed channels).
-
int32_t
sample_bytes
() const¶ Number of bytes occupied by a sample (0 for string-typed channels).
-
lsl_streaminfo
handle
() const¶ Get the implementation handle.
-
stream_info
()¶ Default contructor.
-
stream_info
(const stream_info &rhs)¶ Copy constructor.
-
stream_info &
operator=
(const stream_info &rhs)¶ Assignment operator.
-
~stream_info
()¶ Destructor.
Public Static Functions
-
static stream_info
from_xml
(const std::string &xml)¶ Utility function to create a stream_info from an XML representation.
-