hypertools.io.lsl_stream

hypertools.io.lsl_stream(name=None, type=None, timeout=10.0, **resolve_kwargs)

Resolve a live Lab Streaming Layer (LSL) stream and return it as a plain Python iterator of per-sample numeric vectors, compatible with hypertools.io.streaming.is_stream/row_to_vector – so the result can be passed directly to hyp.plot(…, stream_init=…, stream_chunk= …).

Parameters:

namestr, optional

Resolve the stream by its LSL name property (via pylsl.resolve_byprop('name', name, ...)). Takes precedence over type when both are given.

typestr, optional

Resolve the stream by its LSL type property (e.g. 'EEG' or 'Gaze'), via pylsl.resolve_byprop('type', type, ...). Used only when name is not given. Only numeric channel formats are supported: string-typed streams (e.g. marker streams with channel_format='string') are rejected with a clear error, since hypertools’ streaming machinery consumes numeric vectors.

timeoutfloat

Seconds to wait for a matching stream to appear on the network before giving up (default: 10.0). When neither name nor type is given, this is also the wait time used to resolve ANY available stream (pylsl.resolve_streams). The same value also bounds mid-stream silence: once samples are flowing, the returned generator raises HypertoolsIOError if nothing arrives for ~`timeout` consecutive seconds (e.g. the source device disconnected).

**resolve_kwargs

Extra keyword arguments forwarded to the underlying pylsl resolve call (e.g. minimum= for pylsl.resolve_byprop).

Returns:

streamgenerator

An infinite generator yielding one sample (a list of channel values) per call, pulled from a pylsl.StreamInlet opened on the first resolved stream (a RuntimeWarning names the chosen stream when several match). NOTE that the multi-match check is best-effort: LSL resolution returns as soon as at least one stream matches, so a second matching outlet that announces itself a moment later goes undetected and the first stream is used silently. Pass name= to pin a specific stream, or force ambiguity detection with minimum=2 (forwarded to the pylsl resolve call) at the cost of always waiting the full timeout when only one matching stream exists. Passes hypertools.io.streaming.is_stream.

Raises:

ImportError

If pylsl is not installed.

TypeError

If name or type is not a string (or None).

ValueError

If timeout is not a positive number of seconds.

hypertools.core.exceptions.HypertoolsIOError

If no matching stream is found within timeout seconds, if the matched stream has a string (non-numeric) channel format, or – raised from the returned generator’s next() during iteration – if a stream that was delivering samples goes silent for ~`timeout` consecutive seconds.

Examples

>>> import hypertools as hyp
>>> stream = hyp.io.lsl_stream(type='EEG', timeout=5.0)
>>> hyp.plot(stream, stream_init=200, stream_chunk=20)