Skip to content
DevLab

Capturing for the best accuracy

The conditions Engine and Capture actually check, what the first seconds of a capture lack, and the whitepaper's recommendations.

On this page
  1. What leaves the device
  2. Browsers and frame rate
  3. What Engine checks in every batch
  4. Give it a few seconds
  5. Batches
  6. Recommendations from the whitepaper
  7. Quality signals

Capture runs in the browser and extracts facial geometry from every frame: 478 landmarks, 52 expression coefficients and the head pose. Only those numbers leave the device: no image, video or raw audio. With transcription, the text also leaves it. Extra signals (pulse colour values, voice features, hands and body) are off by default and only travel if you ask for them.

  • Chrome or Edge 94+, Safari 16.4+ (iOS 16.4+). Firefox is not a target: kodec has not been tested there.
  • Serve the page over HTTPS or from localhost.
  • The frame rate depends on the device, not on the platform: a recent laptop or phone usually stays close to the camera’s rate, an entry-level phone captures fewer frames per second, and a phone loses rate as it heats up in a long session. Read it at run time with onCodecEvent('capture-quality') (how), not from the phone model: what limits it is the face detection on the GPU (WebGL 2) and, on phones, heat in long sessions. The device, the mode and how to check them: Devices, quality and mode.
Condition If it fails
Each frame has featuresMeta Accepted and counted in framesWithoutFeaturesMeta; those frames give no valence or arousal axes
478 landmarks per frame 478 are expected (468 face + 10 iris). With 468, measured on 2026-08-09, Engine accepted every batch and the session never closed; a frame with no face (landmarks: []) has not been measured
52 expression coefficients per frame Accepted; the frame is used without them
Batches numbered from 1, the last one Final Without the Final, the step stays open; if batches are missing when the Final arrives: 400 with qualityCode: "KPN-EMO-MISSING-PACKETS" and missingOrders, and that Final stores nothing: send the missing ones and the Final again (see Declared limits)
step exists in the position’s plan 400 with qualityCode: "KPN-EMO-STEP"
JSON
{ "status": 400, "qualityCode": "KPN-EMO-STEP" }

Some indicators are computed over a window of recent frames, so the first seconds of a capture have no value for them. In a capture of the sample, workload first appears at about 5 seconds and then arrives in windows, not in every frame (which frame comes first changes from run to run):

JSON
{ "framesWithWorkload": 21, "framesTotal": 300 }

Plan captures longer than that: Measurement asks for at least 6 s. Engine does not enforce step durations; your interface does.

Send batches in order, a few seconds of frames each. With a camera, a frame is about 19.7 KB of JSON from SDK 0.35.0 (478 landmarks), so a few seconds already weigh a few megabytes. From 0.34.0 the SDK cuts each batch at 300 frames or 3 MB of frames, whichever comes first (about 150 camera frames); an SDK before 0.34.0 cut only by count, up to about 9.3 MB. If your proxy limits the body size, allow at least 4.5 MB, or 10 MB in front of an older SDK (see Proxy); if you send batches yourself, cut them by size as well as by number of frames. Resending the same batch is safe: Engine keeps the first copy.

These come from Neurologyca’s validation programme, not from checks in the API:

  • one person in view;
  • a stable distance and head angle: absolute levels are not comparable across setups;
  • a personal baseline before comparing people or sessions.

Quality degrades before it fails: low-quality signal lowers how much a reading can be trusted rather than raising an error.

Signal Where
framesWithoutFeaturesMeta Every 202 of a batch
framesWithoutMediaTime Every 202 of a batch: frames without mediaTimeMs (where a stimulus player was, optional per frame). Information, not an error
missingOrders The 202 of the last baseline batch, and the 400 with KPN-EMO-MISSING-PACKETS of a capture’s Final batch
qualityCode (KPN-EMO-…) 400 when a batch breaks the contract (step, media, plan, or batches missing before the Final)
processing.error Live stream: something failed while processing a capture; stage says what and final whether Engine will retry
hci.warning Live stream: a warning about an indicator your context includes, once per batch; it is not an alert; DevLab does not show the level that triggers it (threshold), so do not build on it; whether it is sent depends on the environment