Class liblsl.StreamInlet
A stream inlet.
Inlets are used to receive streaming data (and meta-data) from the lab network.
Namespace: LSL4Unity
Assembly: cs.temp.dll.dll
Syntax
public class StreamInletConstructors
StreamInlet(liblsl.StreamInfo, Int32, Int32, Boolean)
Initializes a new instance of liblsl.StreamInlet from a resolved stream info.
Declaration
public StreamInlet(liblsl.StreamInfo info, int maxBuflen = 360, int maxChunklen = 0, bool recover = true)Parameters
| Type | Name | Description |
|---|---|---|
| liblsl.StreamInfo | info | A resolved stream info object (as coming from one of the resolver functions). |
| Int32 | maxBuflen | Optionally the maximum amount of data to buffer (in seconds if there is a nominal sampling rate, otherwise x100 in samples). Recording applications want to use a fairly large buffer size here, while real-time applications would only buffer as much as they need to perform their next calculation. |
| Int32 | maxChunklen | Optionally the maximum size, in samples, at which chunks are transmitted (the default corresponds to the chunk sizes used by the sender). Recording applications can use a generous size here (leaving it to the network how to pack things), while real-time applications may want a finer (perhaps 1-sample) granularity. If left unspecified (=0), the sender determines the chunk granularity. |
| Boolean | recover | Try to silently recover lost streams that are recoverable (=those that that have a SourceId set). In all other cases (recover is false or the stream is not recoverable) functions may throw a liblsl.LostException if the stream's source is lost (e.g., due to an app or computer crash). |
Remarks
The liblsl.StreamInlet may also be constructed with a fully-specified liblsl.StreamInfo if the desired channel format and count is already known up-front, but this is strongly discouraged and should only ever be done if there is no time to resolve the stream up-front (e.g., due to limitations in the client program).
Methods
CloseStream()
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. If an application stops being interested in data from a source (temporarily or not) but keeps the outlet alive, it should call CloseStream() to not waste unnecessary system and network resources.
Declaration
public void CloseStream()Finalize()
Finalizes an instance of liblsl.StreamInlet.
The inlet will automatically disconnect if destroyed.
Declaration
protected void Finalize()Info(Double)
Retrieve the complete information of the given stream, including the extended description.
Can be invoked at any time of the stream's lifetime.
Declaration
public liblsl.StreamInfo Info(double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Double | timeout | Optional timeout of the operation (default: no timeout). |
Returns
| Type | Description |
|---|---|
| liblsl.StreamInfo |
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | If the timeout expires. |
| liblsl.LostException | If the stream source has been lost. |
OpenStream(Double)
Subscribe to the data stream.
All samples pushed in at the other end from this moment onwards will be queued and eventually be delivered in response to PullSample(Single[], Double) or PullChunk(Single[,], Double[], Double) calls. Pulling a sample without some preceding OpenStream is permitted (the stream will then be opened implicitly).
Declaration
public void OpenStream(double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Double | timeout | Optional timeout of the operation (default: no timeout). |
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | If the timeout expires. |
| liblsl.LostException | If the stream source has been lost. |
PullChunk(Char[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(char[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| Char[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullChunk(Double[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(double[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| Double[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullChunk(Int16[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(short[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| Int16[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullChunk(Int32[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(int[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| Int32[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullChunk(Single[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(float[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| Single[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullChunk(String[,], Double[], Double)
Pull a chunk of data from the inlet.
Declaration
public int PullChunk(string[, ] buffer, double[] times, double timeout = 0)Parameters
| Type | Name | Description |
|---|---|---|
| String[,] | buffer | A pre-allocated buffer where the channel data shall be stored. |
| Double[] | times | A pre-allocated buffer where time stamps shall be stored. |
| Double | timeout | Optionally the timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup. |
Returns
| Type | Description |
|---|---|
| Int32 | Number of samples written to the data and timestamp buffers. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(Char[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(char[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Char[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(Double[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(double[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Double[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(Int16[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(short[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Int16[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(Int32[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(int[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Int32[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(Single[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(float[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Single[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
PullSample(String[], Double)
Pull a sample from the inlet and read it into an array of values. Handles type checking and conversion.
Declaration
public double PullSample(string[] sample, double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| String[] | sample | An array to hold the resulting values. |
| Double | timeout | Optional, the timeout for this operation, if any. Use 0.0 to make the function non-blocking. |
Returns
| Type | Description |
|---|---|
| Double | The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by TimeCorrection(Double) to it. |
Exceptions
| Type | Condition |
|---|---|
| liblsl.LostException | If the stream source has been lost. |
SamplesAvailable()
Query whether samples are currently available for immediate pickup.
Declaration
public int SamplesAvailable()Returns
| Type | Description |
|---|---|
| Int32 | Number of samples available. |
Remarks
that it is not a good idea to use SamplesAvailable() to determine whether a pull_*() call would block:
to be sure, set the pull timeout to 0.0 or an acceptably low value.
If the underlying implementation supports it, the value will be the number of samples available (otherwise it will be 1 or 0).
SetPostprocessing(liblsl.processing_options_t)
Set post-processing flags to use.
By default, the inlet performs NO post-processing and returns the ground-truth time stamps, which can then be manually synchronized using TimeCorrection(), and then smoothed/dejittered if desired. This function allows automating these two and possibly more operations.
Declaration
public void SetPostprocessing(liblsl.processing_options_t flags = liblsl.processing_options_t.post_ALL)Parameters
| Type | Name | Description |
|---|---|---|
| liblsl.processing_options_t | flags | An integer that is the result of bitwise OR'ing one or more options from liblsl.processing_options_t together (e.g., post_clocksync|post_dejitter); the default is to enable all options. |
Remarks
When you enable this, you will no longer receive or be able to recover the original time stamps.
TimeCorrection(Double)
Retrieve an estimated time correction offset for the given stream.
The first call to this function takes several miliseconds 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).
Declaration
public double TimeCorrection(double timeout = 32000000)Parameters
| Type | Name | Description |
|---|---|---|
| Double | timeout | Optional timeout to acquire the first time-correction estimate (default: no timeout). |
Returns
| Type | Description |
|---|---|
| Double | The time correction estimate. This is the number that needs to be added to a time stamp
that was remotely generated via |
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | If the timeout expires. |
| liblsl.LostException | If the stream source has been lost. |
WasClockReset()
Query whether the clock was potentially reset since the last call to WasClockReset().
This is a rarely-used function that is only useful to applications that combine multiple TimeCorrection(Double) values to estimate precise clock drift; it allows to tolerate cases where the source machine was hot-swapped or restarted in between two measurements.
Declaration
public bool WasClockReset()Returns
| Type | Description |
|---|---|
| Boolean |
|