ezmsg.lsl.timing#

Breaks and jitter in a regularly sampled stream’s timestamps.

liblsl can remove timestamp jitter itself (proc_dejitter), but its filter has no notion of a break: when a sender pauses and resumes, the smoothed timestamps carry on as if no time had passed and take minutes to recover, so the break is invisible and the samples after it are mis-timed. A threshold that restarts the filter exists from liblsl 1.18, but it is process-wide configuration, off by default, and cannot be read back.

StreamTiming therefore does both jobs here, per inlet, on timestamps pulled without liblsl’s smoothing: it finds the breaks first, then removes jitter from each run between them.

Classes

class StreamTiming(srate, break_seconds=1.0, break_samples=500, dejitter=True, halftime=90.0)[source]#

Bases: object

Split a stream’s chunks at breaks and time each run without jitter.

A break is an interval between consecutive samples whose size exceeds both break_seconds and break_samples sample periods: pyxdf’s rule and defaults, so a live stream and its recording agree on where the breaks are.

Jitter is removed as liblsl does it: a straight line fitted to timestamp against sample count, weighting each sample half as much for every halftime seconds of age. The fit is done a chunk at a time and restarts at a break.

Parameters:
  • srate (float) – The stream’s nominal sampling rate, in Hz.

  • break_seconds (float) – See above. Non-positive (with break_samples) disables break detection.

  • break_samples (float) – See above.

  • dejitter (bool) – Whether to remove jitter. If False, each run is timed by its first raw timestamp.

  • halftime (float) – Age, in seconds, at which a sample’s weight in the fit has halved.

__init__(srate, break_seconds=1.0, break_samples=500, dejitter=True, halftime=90.0)[source]#
Parameters:
last: float | None#

The last raw timestamp seen.

split(timestamps)[source]#

Take the next chunk’s raw timestamps, in order.

Returns (start, stop, time, is_break) for each run in the chunk: the samples [start, stop), the time of the first of them, and whether a break precedes it. A chunk with no break in it is one run.

Parameters:

timestamps (ArrayLike)

Return type:

list[tuple[int, int, float, bool]]