Troubleshooting the HTC Vive gaze module
The module fails to start
Cause. The Vive Streaming SDK failed to initialise. This happens when HTC’s Vive Business Streaming (VBS) driver is not installed on the workstation.
Fix. Install the VBS driver alongside SteamVR, then restart the session.
No gaze data, and nothing in the logs explains why
Cause. The module only acts on two of the five connection states the Vive Streaming SDK can report: “streaming” (starts face tracking) and “standby, waiting for a client” (stops it). The other three - no frame received from SteamVR, VBS driver not found, and SteamVR not running - are received but not logged or acted on. In any of those states the module waits indefinitely with no visible error.
Fix. Confirm SteamVR is running and actively streaming to the headset, and that the VBS driver is installed, before assuming the module itself is at fault.
Face tracking never starts even though the headset is connected
Cause. Once the headset is detected, the module retries starting face tracking on every capture tick, up to 1000 attempts for the session. If eye tracking still has not produced data after that budget is exhausted, the module stops retrying until the next session (module restart).
Fix. Restart the module (or the capture session) rather than waiting further once tracking has failed to start; check the headset’s eye tracker is calibrated and the eye cameras are unobstructed first, since that is the most common reason initialisation never completes within the retry budget.
Blink is reported for one eye but the wearer says they weren’t blinking
Cause. left_eye_occluded / right_eye_occluded are populated from the same per-eye blink
flag as blink, not from a separate occlusion or openness measurement - see
Data produced. Anything the SDK classifies as a blink is reported
as an occluded eye.
Fix. Use left_eyelid_openness / right_eyelid_openness if you need a continuous measure
instead of a blink-driven boolean.