Level 7 L7.11 pipeline thread

Getting a stream: timestamps, dropped samples, drift, recording

A recording is a file and a stream is a promise — samples at a stated rate, in order, complete, on a clock you can align to — and every part of the promise can fail quietly. One interface for a replayed file, a synthetic stream with planted faults and a headset; the block contract; the rate measured against the rate claimed; drops counted and verified; drift in milliseconds; a session recorded in the site's own format.

~75 min Notebook: nb-7-11-stream

Prerequisites: L7.10 · What a four-channel headband measures, L0.3 · Amplifiers, sampling and recording

1 claim on this page is unverified. TODO(confirm) marks a specific statement the author has not yet checked against a primary source. Everything else on this page has been reviewed. Treat a marked claim as provisional and go to the cited source rather than quoting the sentence.

What you will be able to do

  • Open a stream from a native-Bluetooth board through one driver, and from a replay file through the same interface
  • Convert vendor sample arrays into µV blocks with per-sample timestamps
  • Measure effective against nominal rate and count dropped samples
  • Record a session in the site's asset format with a JSON sidecar

Why this matters

Everything downstream of a stream assumes the stream told the truth: that the samples arrived at the rate the header says, in order, with nothing missing, stamped on a clock the cues are on too. A file has already settled all of that, badly or well, and pf-dropped-samples is the lesson about reading the damage afterwards. A stream is different in one way that changes the job: you are there when it fails, and you can measure the failure as it happens instead of inferring it a week later from events that drifted. This lesson is the measuring. It opens a stream three ways through one interface, states the contract every block satisfies, and then checks the promise — rate, completeness, clock — against a planted truth, which is the only place a check can be verified rather than merely reported. It ends by recording a session in the same format every asset on this site uses, so a learner’s own file and a shipped one are the same kind of thing.

Concepts

One interface, three sources

The course library (loop/eegloop) draws one line: below it, a source — a replayed recording, a synthetic stream, a headset through its driver; above it, everything else. Every source has the same five methods (info, start, read, stop, clock_now) and emits the same block. open_source('replay:<file>'), open_source('synthetic:gaps') and open_source('brainflow:<board-key>') return the same interface, and a filter, a gate, a feedback loop or a decoder written against it does not know which one it got.

That line is the whole reason the rest of the path can be taught on replayed and synthetic data and still be the code you run on a headset. The device path is real and tested — against a fake board with the driver’s interface on every runner, and against a paired headset only when someone sets EEGLOOP_HARDWARE — but nothing shipped on this site was produced through it (CONTRACTS, Phase 5: no live output is an answer key). The notebook’s device cell guards on the driver being installed, prints which path it took, and keeps the run command in a text cell rather than an output.

What this lesson connects to

The board table is the library’s, printed in L7.10; this lesson names no device. The Lab Streaming Layer is the transport much of the field uses between an acquisition program and an analysis one; L7.3’s streaming section, next on this path, says what it gives and what it does not — timestamps on the receiving computer’s clock, the same fact this lesson measures for the driver — and the library’s lsl source waits on a binding decision and says so. What it needs from the table is one row per geometry: the transport (native Bluetooth LE, no dongle, for both classes the path starts with) and the fact that the driver’s timestamps are the computer’s clock at packet arrival, not the device’s sample clock — verified as a design of the driver, TODO(confirm) per board as a measurement. Everything the acceptance report is built to settle per device (rate against claim, the package counter’s step, the timestamp structure, the units) is listed in loop/HARDWARE.md, and the report a human files after running it lives under site/notes/device-<key>.md with no serial number in it.

The block contract

A block is n_channels × n_samples in microvolts — the driver’s scaling applied once, at the source, and stated in the stream’s nominal facts — with:

  • a sample_index, the source’s own count of samples including the ones it lost, so the difference between two blocks’ indices is elapsed samples on the source’s clock, not samples delivered;
  • a t_start_s and per-sample timestamps_s on the source’s clock, whatever that clock is;
  • dropped_before, the number of samples the source knows it lost immediately before this block; a loss inside a run of buffered samples is recorded in the block’s flags instead, because it cannot be a “before”;
  • a flags dictionary later steps write into — the quality gate’s verdict, the envelope, the features — so a block carries its own provenance through the chain.

Two conventions follow. Blocks are a fixed length, because the block length is a row in the latency budget (L7.3) and a short last block would be a different pipeline for one step; the Reblocker turns whatever a driver delivers — 37 samples, then 27 — into fixed blocks with losses carried to the right place. And a source never hands out a block that straddles a loss: the samples before and after a gap are different runs of time, and a filter that carried its state across them would be pf-filter-across-boundaries in its online form. A chain built with a reset threshold forgets its state across a hole longer than its memory and flags the block.

The rate, measured against the rate claimed

A header says 256 Hz. The stream’s own timestamps say how many samples arrived over how much of the clock’s time, and the wall clock says how much of its time passed. The acceptance report prints the rate measured from the timestamps (and from the wall clock when the stream is paced) beside the rate claimed, and calls a difference over 1 % a warning and over 3 % a failure — because every latency and every band edge downstream is scaled by the true rate, and a nominal rate that is not the true one produces exactly the drift pf-dropped-samples describes. On the synthetic stream the measured rate is the nominal rate divided by (1 + 200 ppm), which is the planted drift read off as a rate.

Dropped samples: reported, then verified

A driver that counts packets can report a loss; a stream whose timestamps jump can reveal one; neither can verify its own count. The synthetic gaps scenario plants one loss — 64 samples at 60 s, 250 ms of timeline — and records it in its truth, and the notebook checks the library’s accounting against it to the sample. The same loss is visible three ways: the sample_index steps by 64 across one block, the interval between two timestamps is 65 sample periods where it should be one, and the DropAccount totals 64 in one event. On a headset the third way is what the package counter gives you and the second is what the timestamps give you; the report prints both, and prints the package counter’s increment histogram, because whether that counter steps once per sample or once per packet — and so whether a lost packet is undercounted by the packet length — is a fact per board that only a live stream can settle.

Drift, in milliseconds

Two clocks that disagree by parts per million disagree by more every second. The synthetic stream’s timestamps run 200 ppm fast against its sample clock: 24 ms after two minutes, six samples at 256 Hz, and growing. That is the width of an evoked response’s peak, and it is invisible in any single block. The notebook measures the slope directly and prints the arithmetic — ppm × seconds — the exercise asks for. The consequence for a BCI is a parameter rather than a paragraph: which clock the cues are on decides whether an epoch is cut where the brain’s response is, and L7.15’s epoch cutter is told. Here the point is only that the two clocks exist, that a stream’s own timestamps are the thing to measure, and that a rate “measured from the wall clock” and one “measured from the timestamps” can both be right and still disagree.

Recording a session in the site’s own format

Recorder writes what the source delivered, untouched, as a Float32 little-endian .bin — channels × samples, row-major, microvolts — with a JSON sidecar naming the channels, the rate, the units, the reference and the on-device filter state as the source reported them, every loss the source counted, and license: private. That is spec §4.5, the shape of every asset on this site, which is why ReplaySource.from_asset opens a learner’s recording and a shipped asset with the same call and why the notebook’s round trip — record, read back, compare — closes to the precision of float32. Nothing in the sidecar names the machine: the library scrubs absolute paths from every string it writes, and a pairing address or serial number never reaches a source’s facts in the first place, so no session, sidecar or report can carry one.

Where a recording of your own lives is your business; the repository ignores a directory for them, and a rendered notebook that names it, or that carries a pairing detail, is refused by the site’s own build.

The data behind this lesson

ds-eegbci S001 R01 (eyes open), ODC-By 1.0, on the occipitotemporal-4 sites, turned into a stream and recorded back out. The library’s synthetic gaps scenario, seed 20260920, with one planted loss of 64 samples at 60 s and 200 ppm of clock drift — every number about drops and drift in this lesson is a planted answer, checked. No headset produced anything on this page.

Explore

This lesson has no widget. The stream is the thing to explore, and the notebook is where it runs.

Practice

Getting a stream: one interface for a replayed recording, a synthetic stream with planted faults and a headset; the block contract; the rate measured against the rate claimed; a planted loss counted and verified; drift in milliseconds; a session recorded in the site's own asset format and read back nb-7-11-stream

Level 7 ~3 min
notebooks/L7/nb-7-11-stream.ipynb

Downloads from ds-eegbci.

Open in Colab Download Read it here

Exercises

Exercise ex-7-11-timeline-lost

Numeric

The library's synthetic 'gaps' scenario plants one loss of 64 samples in a 256 Hz stream. How many milliseconds of timeline does the loss remove?

ms

Exact answer required, in ms.

Exercise ex-7-11-drift

Numeric

A stream's timestamps run 200 parts per million fast against its sample clock. After 120 seconds, by how many milliseconds do the stamps lead the sample clock?

ms

Accepted within ±0.5 ms.

Exercise ex-7-11-log-at-acquisition

Free response

List what must be logged at acquisition time because it cannot be recovered afterwards from the samples alone. For each item, say in one clause what goes wrong downstream when it is missing.

Pitfalls

Pitfall

Dropped samples and clock drift

Symptom
Events drift relative to the data across the recording.
Cause

Two mechanisms, often together. Dropped samples: the acquisition buffer overflows (a busy computer, a slow disk, a wireless link) and a block of samples is lost without a gap being written; every later sample is now earlier in the file than it was in time, by the length of the dropped block, and events timestamped by a separate clock no longer match. Clock drift: two devices with their own oscill…

Detect
  • Compare the sample count with the sampling rate times the recorded duration (from an independent clock: the file’s start and end timestamps, or the stimulus log). - Plot the interval between successive periodic events (a fixed-rate stimulus, a clock marker) across the recording: dropped samples show as a jump, drift as a slope. - Look for discontinuities in the data at the moment of a drop: an…
Fix
  • Prevent it at acquisition: hardware triggers on the amplifier’s own clock, adequate buffers, a wired link, and a periodic hardware sync pulse recorded in both streams. - For drift with a known reference (a sync pulse or periodic marker), resample or linearly rescale the event times to the EEG clock; LSL-style recordings store the offsets needed to do it. - For dropped samples that can be locate…

Full entry with example →

Pitfall

Filtering across discontinuities

Symptom
Ringing at file joins, breaks, or buffer edges.
Cause

At a discontinuity the signal jumps: from the last sample of one run to the first sample of the next, from a value to zero padding at the file edge, or from the DC offset of one recording to that of another. To a filter a jump is a step, and a step response with overshoot or a long settling time produces ringing (for sharp FIR and high-order IIR filters) or a slow exponential swing (for a high-pa…

Detect
  • Keep a list of boundary events (MNE annotations of type BADboundary or equivalent) and inspect the filtered data around each one. - Look at the start and end of every file after filtering; compare with the unfiltered data. - Compute the impulse-response length of your filter and mark that much data on each side of every boundary as suspect. - In real-time pipelines, filter a test signal with a…
Fix
  • Filter each continuous run separately, then concatenate; never filter across a join. - Where a join is unavoidable, annotate the boundary and exclude epochs that overlap the boundary plus the filter’s impulse-response length. - Pad sensibly at file edges (MNE reflects the data by default; state the padding method) and discard the padded region’s worth of data from analysis. - Real-time: carry f…

Full entry with example →

Terms used here

Every term this lesson leans on, with the one-line meaning. Follow a term for its full entry.

Montage
The set of channel derivations displayed or analysed; also the standard electrode-position layout.