JavaScript (Beta)

The JavaScript API is provided through the @eyeware/beam-eye-tracker ES module package in the SDK archive’s javascript folder. It exposes the beta Beam Eye Tracker JavaScript API through a WebAssembly runtime and can be used from browsers, Electron renderer processes, Electron main processes, and Node.js.

Functions

loadBeamEyeTrackerModule

Loads and initializes the underlying WebAssembly module.

export declare function loadBeamEyeTrackerModule(): Promise<unknown>;

createSession

Creates a Beam Eye Tracker JavaScript API instance.

• friendlyName: Name shown to the user by the Beam Eye Tracker application.

• viewportGeometry: Optional viewport rectangle used for viewport gaze mapping.

export declare function createSession(
  friendlyName: string,
  viewportGeometry?: ViewportGeometry,
): Promise<BeamEyeTrackerSession>;

Classes

BeamEyeTrackerSession

JavaScript API object for communicating with the Beam Eye Tracker application.

Methods

Creates an API instance from an already-loaded WebAssembly module.

constructor(module: unknown, friendlyName: string, viewportGeometry?: ViewportGeometry)

Releases native and JavaScript resources owned by this API instance.

destroy(): void

Returns the current tracking-data reception status.

getTrackingDataReceptionStatus(): TrackingDataReceptionStatus

Returns a human-readable name for a tracking-data reception status.

getTrackingDataReceptionStatusName(status?: TrackingDataReceptionStatus): string

Requests Beam Eye Tracker to launch and start tracking.

attemptStartingTheBeamEyeTracker(): void

Starts recentering the smoothed sim game camera.

startRecenterSimGameCamera(): boolean

Stops recentering the smoothed sim game camera.

stopRecenterSimGameCamera(): void

Waits asynchronously for a new tracking-state set.

Pass 0 to poll and return immediately. Pass a positive timeout to wait up to that number of milliseconds.

This method does not block the JavaScript event loop. It polls internally until new tracking data is available or the timeout expires.

waitForNewTrackingStateSet(timeoutMs?: number, pollIntervalMs?: number): Promise<boolean>

Returns the most recent tracking-state set.

getLastTrackingStateSet(): TrackingStateSet

Samples the smoothed sim game camera state from the caller’s loop.

sampleSmoothSimGameCameraState(): SimGameCameraState

Computes the final sim game camera transform from eye/head tracking components and caller-provided weights. Preferred for Beam Eye Tracker 2.6 and above when paired with sampleSmoothSimGameCameraState().

computeSmoothSimGameCameraTransformParameters(
    cameraState: SimGameCameraState,
    eyeTrackingWeight?: number,
    headTrackingWeight?: number,
  ): SimCameraTransform3D

Starts asynchronous tracking-data reception callbacks.

startReceivingTrackingData(callbacks: TrackingCallbacks): void

Stops asynchronous tracking-data reception callbacks.

stopReceivingTrackingData(): void

Constants

Status

Numeric tracking-data reception states reported by the Beam Eye Tracker JavaScript client.

export declare const Status: Readonly<{
  NOT_RECEIVING_TRACKING_DATA: 0;
  RECEIVING_TRACKING_DATA: 1;
  ATTEMPTING_TRACKING_AUTO_START: 2;
}>;

Types and Interfaces

TrackingDataReceptionStatus

Indicates whether the client is currently receiving frame-by-frame tracking data, or whether it is attempting to launch/start Beam Eye Tracker.

export type TrackingDataReceptionStatus = 0 | 1 | 2;

Point

Integer 2D point in screen coordinates.

export interface Point {
  x: number;
  y: number;
}

Vector3D

3D vector or point.

export interface Vector3D {
  x: number;
  y: number;
  z: number;
}

ViewportGeometry

Viewport rectangle used to map unified screen gaze into normalized viewport coordinates.

export interface ViewportGeometry {
  point00?: Point;
  point11?: Point;
}

SimCameraTransform3D

Six degree-of-freedom sim camera transform. Rotations are in radians and translations are in meters.

export interface SimCameraTransform3D {
  yaw_in_radians: number;
  pitch_in_radians: number;
  roll_in_radians: number;
  x_in_meters: number;
  y_in_meters: number;
  z_in_meters: number;
}

SimGameCameraState

Smoothed sim game camera state sampled from the Beam SDK.

export interface SimGameCameraState {
  valid: boolean;
  timestamp_in_seconds?: number;
  eye_tracking_pose_component?: SimCameraTransform3D;
  head_tracking_pose_component?: SimCameraTransform3D;
}

UserState

Raw and processed tracking data for the current user.

export interface UserState {
  valid: boolean;
  timestamp_in_seconds?: number;
  head_pose?: {
    confidence: number;
    translation_from_hcs_to_wcs: Vector3D;
    track_session_uid: string;
  };
  unified_screen_gaze?: {
    confidence: number;
    point_of_regard: Point;
    unbounded_point_of_regard: Point;
  };
  viewport_gaze?: {
    confidence: number;
    normalized_point_of_regard: Point;
  };
}

TrackingStateSet

Container for the latest tracking data produced by the Beam Eye Tracker application.

export interface TrackingStateSet {
  valid: boolean;
  timestamp_in_seconds?: number;
  user_state?: UserState;
  sim_game_camera_state?: SimGameCameraState;
}

TrackingCallbacks

Callbacks used for asynchronous tracking-data reception in JavaScript.

export interface TrackingCallbacks {
  onStatusChanged?: (status: TrackingDataReceptionStatus) => void;
  onTrackingStateSetUpdate?: (trackingStateSet: TrackingStateSet, timestamp: number) => void;
}

Browser Runtime Requirements

The current JavaScript package is a beta WebAssembly package. Browser hosts must serve the application and SDK files with cross-origin isolation headers because the runtime uses Emscripten pthreads and SharedArrayBuffer:

• Cross-Origin-Opener-Policy: same-origin

• Cross-Origin-Embedder-Policy: require-corp

For latency-critical desktop integrations, prefer the native C, C++, C#, or Python SDK clients for the target platform.

Keep the package’s lib directory next to index.js when copying or publishing the package. The generated WebAssembly runtime loads the wasm module from that relative layout.