timing_core #

timing_core defines the record format and the analysis used to characterise the timing of a transport between devices: one-way latency, jitter, loss, clock offset and drift for each pair of devices. It is the basis of the transport_timing application and its analysis application, and can be used on its own to log and analyse timing in another program. The package is pure Dart and runs on all platforms, including the web.

API documentation · Guide: validating timing in a lab

Installation #

dart pub add timing_core

Recording #

Each device writes one log per run. The header describes the run, and logs with the same runId are analysed together.

final log = RunLogWriter(
  sink, // a BytesSink, to keep the log in memory until the run is over
  RunHeader(
    runId: runId,
    startedAt: DateTime.now(),
    deviceId: 'ipad1',
    deviceName: 'iPad 1',
    sourceId: mySourceId, // how other devices identify what this one sends
    test: 'latency',
    backend: 'lsl-coordinator',
    sampleRate: 1000,
    receiveMode: 'polled',
    pollInterval: 0.001,
  ),
);

log.sent(seq, sendClock);
log.received(
  sourceId,
  seq,
  receivedClock: timing.receivedClock,
  sourceClock: timing.sourceClock,
  clockOffset: timing.clockOffset,
  uncertainty: timing.uncertainty,
);
log.clockSync(sourceId, receivedClock: s.receivedClock, offset: s.offset,
    remoteTime: s.remoteTime, uncertainty: s.uncertainty);

await log.close();

The received and clockSync fields are those of peer_coordinator's MessageTiming and ClockSyncSample.

The file #

A log is an XDF file, so it opens in any XDF tool. The run header is in the file header's transport_timing element, as JSON.

Clocks are in seconds; NaN is a value that was not known. Every clock-offset estimate is also a standard XDF clock offset of its tt.received stream, so a reader that synchronises clocks maps that stream's time stamps onto the receiving device's clock, and latency is one subtraction:

streams, _ = pyxdf.load_xdf('tt_run_ipad1.xdf')
rx = next(s for s in streams if s['info']['name'][0] == 'tt.received')
latency = rx['time_series'][:, 2] - rx['time_stamps']   # received_clock − sent

Analysing #

final report = analyse([for (final bytes in files) RunLog.parse(bytes)]);
print(formatReport(report));

The same analysis is available from the command line: dart run timing_core:analyse [--json] <log>...

For each sender and receiver, a PairReport contains:

The log of a receiver is sufficient for all of these except losses at the very start or end of a run and the device name of the sender, which require the log of the sender.

Reporting results #

Alignment of time stamps #

Data from different devices are aligned with the time stamp of a sample and the clock offset: time on this clock = time stamp + offset.

The time stamp is the sender's clock when it sent (or, for LSL, pushed) the sample. It does not include delays inside the sending application, or the latency of an input device such as a mouse or keyboard that triggered the event.

The offset is estimated from timed round trips, of which the fastest of each burst is kept. Whatever the two directions of that round trip each took, the offset is wrong by no more than half the round trip. The whole round trip is reported as uncertainty, and half of it as the "±" of the report.

Between estimates the clocks drift apart by tens of parts per million, which is tens of microseconds per second. residualSd indicates how well a linear fit describes the drift; a drift that is not linear is visible there.

Latency #

latency = received − (time stamp + offset). Latency is resolved no more finely than the offset is known, so a latency below the "±" cannot be distinguished from zero, and negative values occur for the same reason.

The meaning of received depends on how samples are consumed:

A sample that was already waiting when receiving began (before the first listener, or after a pause) has the time at which it was collected, not the time at which it arrived. The same applies to samples held back by maxBacklog. This is useful for diagnosing whether a consumer keeps up with a stream. A stalled consumer does add latency, but for locating slow points in a topology the wait in the backlog can be excluded.

A sender that uses chunking may wait until the number of samples given by chunkSize is reached. The first sample of a chunk then waits longer than the last.

End-to-end latency that includes hardware, operating system and application is measured with the interactive test of transport_timing. It requires a separate device with a high-precision clock (for example a Bela board), a photodiode and a force-sensitive resistor, and characterises the complete path from a touch to the rendering of the display.