@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