mne_lsl.lsl.StreamInlet

class mne_lsl.lsl.StreamInlet(sinfo, chunk_size=0, max_buffered=360, recover=True, processing_flags=None)

An inlet to retrieve data and metadata on the network.

Parameters:

sinfoStreamInfo

Description of the stream to connect to.

chunk_sizeint ≥ 1 | 0

The desired chunk granularity in samples. By default, the chunk_size defined by the sender (outlet) is used.

max_bufferedint ≥ 0

The maximum amount of data to buffer in the Outlet. The number of samples buffered is max_buffered * 100 if the sampling rate is irregular, else it’s max_buffered seconds.

recoverbool

Attempt to silently recover lost streams that are recoverable (requires a source_id to be specified in the StreamInfo).

processing_flagssequence of str | 'all' | None

Set the post-processing options. By default, post-processing is disabled. Any combination of the processing flags is valid. The available flags are:

• 'clocksync': Automatic clock synchronization, equivalent to manually adding the estimated time_correction().

• 'dejitter': Remove jitter on the received timestamps with a smoothing algorithm.

• 'monotize': Force the timestamps to be monotically ascending. This option should not be enable if 'dejitter' is not enabled.

• 'threadsafe': Post-processing is thread-safe, thus the same inlet can be read from multiple threads.

Attributes

dtype	Channel format of a stream.
n_channels	Number of channels.
name	Name of the stream.
samples_available	Number of available samples on the StreamOutlet.
sfreq	Sampling rate of the stream, according to the source (in Hz).
stype	Type of the stream.
was_clock_reset	True if the clock was potentially reset since the last call.

Methods

close_stream()	Drop the current data stream.
flush()	Drop all queued and not-yet pulled samples.
get_sinfo([timeout])	StreamInfo corresponding to this Inlet.
open_stream([timeout])	Subscribe to a data stream.
pull_chunk([timeout, max_samples])	Pull a chunk of samples from the inlet.
pull_sample([timeout])	Pull a single sample from the inlet.
time_correction([timeout])	Retrieve an estimated time correction offset for the given stream.

close_stream()

Drop the current data stream.

All samples that are still buffered or in flight will be dropped and transmission and buffering of data for this inlet will be stopped. This method is used if an application stops being interested in data from a source (temporarily or not) but keeps the outlet alive, to not waste unnecessary system and network resources.

Warning

At the moment, liblsl is released in version 1.16. Closing and re-opening a stream does not work and new samples pushed to the outlet do not arrive at the inlet. c.f. this github issue.

flush()

Drop all queued and not-yet pulled samples.

Returns:

n_droppedint

Number of dropped samples.

get_sinfo(timeout=None)

StreamInfo corresponding to this Inlet.

Parameters:

timeoutfloat | None

Optional timeout (in seconds) of the operation. By default, timeout is disabled.

Returns:

sinfoStreamInfo

Description of the stream connected to the inlet.

open_stream(timeout=None)

Subscribe to a data stream.

All samples pushed in at the other end from this moment onwards will be queued and eventually be delivered in response to pull_sample() or pull_chunk() calls. Pulling a sample without subscribing to the stream with this method is permitted (the stream will be opened implicitly).

Parameters:

timeoutfloat | None

Optional timeout (in seconds) of the operation. By default, timeout is disabled.

Notes

Opening a stream is a non-blocking operation. Thus, samples pushed on an outlet while the stream is not yet open will be missed.

pull_chunk(timeout=0.0, max_samples=1024)

Pull a chunk of samples from the inlet.

Parameters:

timeoutfloat | None

Optional timeout (in seconds) of the operation. None correspond to a very large value, effectively disabling the timeout. 0. makes this function non-blocking even if no sample is available. See notes for additional details.

max_samplesint

Maximum number of samples to return. The function is blocking until this number of samples is available or until timeout is reached. See notes for additional details.

Returns:

sampleslist of list of str | array of shape (n_samples, n_channels)

If the channel format is 'string', returns a list of list of values for each channel and sample. Each sublist represents an entire channel. Else, returns a numpy array of shape (n_samples, n_channels).

timestampsarray of shape (n_samples,)

Acquisition timestamp on the remote machine. To map the timestamp to the local clock of the client machine, add the estimated time correction return by time_correction().

Notes

The argument timeout and max_samples control the blocking behavior of the pull operation. If the number of available sample is inferior to n_samples, the pull operation is blocking until timeout is reached. Thus, to return all the available samples at a given time, regardless of the number of samples requested, timeout must be set to 0.

Note that if timeout is reached and no sample is available, empty samples and timestamps arrays are returned.

pull_sample(timeout=0.0)

Pull a single sample from the inlet.

Parameters:

timeoutfloat | None

Optional timeout (in seconds) of the operation. None correspond to a very large value, effectively disabling the timeout. 0. makes this function non-blocking even if no sample is available. See notes for additional details.

Returns:

samplelist of str | array of shape (n_channels,)

If the channel format is 'string, returns a list of values for each channel. Else, returns a numpy array of shape (n_channels,).

timestampfloat | None

Acquisition timestamp on the remote machine. To map the timestamp to the local clock of the client machine, add the estimated time correction return by time_correction(). None if no sample was retrieved.

Notes

Note that if timeout is reached and no sample is available, an empty sample is returned and timestamp is set to None.

time_correction(timeout=None)

Retrieve an estimated time correction offset for the given stream.

The first call to this function takes several milliseconds until a reliable first estimate is obtained. Subsequent calls are instantaneous (and rely on periodic background updates). The precision of these estimates should be below 1 ms (empirically within +/-0.2 ms).

Parameters:

timeoutfloat | None

Optional timeout (in seconds) of the operation. By default, timeout is disabled.

Returns:

time_correctionfloat

Current estimate of the time correction. This number needs to be added to a timestamp that was remotely generated via local_clock() to map it into the local_clock() domain of the client machine.

property dtype

Channel format of a stream.

All channels in a stream have the same format.

Type:

dtype | "string"

property n_channels

Number of channels.

A stream must have at least one channel. The number of channels remains constant for all samples.

Type:

int

property name

Name of the stream.

The name of the stream is defined by the application creating the LSL outlet. Streams with identical names can coexist, at the cost of ambiguity for the recording application and/or the experimenter.

Type:

str

property samples_available

Number of available samples on the StreamOutlet.

Type:

int

property sfreq

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

If a stream is irregularly sampled, the sampling rate is set to 0.

Type:

float

property stype

Type of the stream.

The content type is a short string, such as "EEG", "Gaze", … which describes the content carried by the channel. If a stream contains mixed content, this value should be an empty string and the type should be stored in the description of individual channels.

Type:

str

property was_clock_reset

True if the clock was potentially reset since the last call.

Type:

bool

Examples using mne_lsl.lsl.StreamInlet

Introduction to real-time LSL streams

Introduction to real-time LSL streams

Low-level LSL API

Low-level LSL API