@saccadejs/plugin-time-sync

@saccadejs/plugin-time-sync

A jsPsych plugin that measures the combined display + camera lag on the participant's machine and applies it to the saccade.js extension, so gaze timestamps line up with stimulus onsets.

Why you need it

A gaze sample carries the camera frame's captureTime. But the photons left the screen some milliseconds before that stamp — the display's own lag, invisible to JavaScript — and the camera pipeline added more of its own between the sensor and the timestamp. Both sit on the same performance.now() timeline jsPsych uses for stimulus onsets, and their sum is the constant you have to subtract from a gaze timestamp to line it up with what was actually on screen.

This plugin measures that sum with a screen→webcam loopback: it changes the whole screen between two brightness levels at known random moments, watches the mean luminance of the webcam image (the screen lights the participant's face and the room, so an ordinary user-facing webcam works), and cross-correlates the two.

There is no flicker. The schedule is sparse, with gaps of 0.5–1 s, so there are at most two changes per second: one flash (a change and its reversal), a third of the WCAG 2.3.1 / Harding limit of three flashes per second. The timing information is in the edges, not the rate, and a 15-second run has about 20 of them.

Requires the @saccadejs/extension extension to be registered in initJsPsych. Run it once, before your gaze-recording trials; put it after saccade-preview so the camera is already running.

Installation

npm install @saccadejs/core @saccadejs/extension @saccadejs/plugin-time-sync

Usage

<script src="https://unpkg.com/jspsych@8"></script>
<script src="https://unpkg.com/@saccadejs/core"></script>
<script src="https://unpkg.com/@saccadejs/extension"></script>
<script src="https://unpkg.com/@saccadejs/plugin-preview"></script>
<script src="https://unpkg.com/@saccadejs/plugin-time-sync"></script>
<script>
  const jsPsych = initJsPsych({ extensions: [{ type: jsPsychExtensionSaccade }] });

  jsPsych.run([
    { type: jsPsychSaccadePreview },
    { type: jsPsychSaccadeTimeSync }, // measures and applies the offset
    // ... calibrate, then your trials
  ]);
</script>

The trial shows the instructions with a start button first, then a progress readout while the screen changes, then ends. When apply_offset is true and the verdict is OK, the measured lag is handed to extension.setTimingOffset(), and every later trial's saccade_data[].t has it subtracted (and saccade_timing.corrected is true). Any other verdict is recorded but not applied.

Parameters

Parameter	Type	Default	Description
duration	integer	15000	How long the measurement runs, in ms. Longer gives more edges and a tighter estimate.
gap_min	integer	500	Minimum gap between brightness changes, in ms.
gap_max	integer	1000	Maximum gap between brightness changes, in ms.
contrast	"full" | "reduced"	"full"	"full" switches between black and white (strongest signal); "reduced" uses dark gray and light gray — gentler, but noisier.
instructions	HTML string	(see below)	Shown before the measurement starts. The default explains what is about to happen and states that it is not a flickering display.
button_text	string	"Start"	Text of the button that begins the measurement.
require_ok	boolean	false	If true, an UNRELIABLE result is measured once more before continuing. The trial always continues either way; verdict records what happened.
apply_offset	boolean	true	Apply the measured lag to the extension when the verdict is OK.

Data generated

Name	Type	Description
lag_ms	float	The measured display + camera lag. The constant to subtract from a gaze timestamp to put it on the stimulus clock.
plateau_width_ms	float	Width of the range of lags consistent with every observed edge — the uncertainty on lag_ms. One camera frame (~33 ms) or less is expected.
peak_d	float	Peak of the edge-difference statistic, 0–1. Below 0.5 means the camera never really saw the screen change.
halves_ms	array	[first, second] — the lag estimated separately from each half of the run. Numbers that disagree mean the lag drifted.
camera_period_ms	float	Mean interval between camera frames (33.3 for a 30 fps camera).
camera_jitter_ms	float	Standard deviation of that interval.
dropped_frames	integer	Camera frames the browser reported dropping during the run.
raf_period_ms	float	Mean interval between animation frames (16.7 on a 60 Hz display).
clock_source	string	"captureTime" (best), "receiveTime", or "callback" (the browser gave no capture timestamp at all).
verdict	string	"OK", "INCONCLUSIVE" or "UNRELIABLE". See below.
reason	string	A short explanation of a non-OK verdict; null when the verdict is OK.
applied	boolean	Whether the lag was applied to the extension.
rt	integer	Time from the start of the trial until the measurement finished.

Every field is null if the measurement threw (no camera, for instance); the trial still ends so the experiment can continue.

Verdicts

Verdict	Meaning
"OK"	The estimate is well constrained: a strong edge signal (peak_d ≥ 0.5), a plateau no wider than one camera frame (≤ 34 ms), and the two halves of the run agreeing.
"INCONCLUSIVE"	There was nothing to estimate from: no usable camera samples, or fewer than two luminance edges.
"UNRELIABLE"	An estimate exists but fails at least one of the checks above: a weak edge signal, a plateau wider than a camera frame, or halves that disagree. reason says which. lag_ms from such a run cannot be trusted.

apply_offset applies only an OK result. To use your own rule instead — for example, to apply an UNRELIABLE lag rather than none — turn it off and apply the lag yourself:

{
  type: jsPsychSaccadeTimeSync,
  apply_offset: false,
  on_finish: (data) => {
    if (data.lag_ms !== null) {
      jsPsych.extensions.saccade.setTimingOffset(data.lag_ms);
    }
  },
}

License

MIT