XRSessionManager

Owns the WebXR session lifecycle, frame loop, camera capture, and localization timing

import { XRSessionManager } from '@multisetai/vps/core';

Manages the full WebXR session: starts and stops the immersive-ar session, runs the frame loop, captures camera frames, and calls the Multiset API. Use this directly when building a custom renderer. When using Three.js or Needle Engine, the adapter creates and owns this internally.

Constructor

new XRSessionManager(gl: WebGL2RenderingContext, options: IXRSessionOptions)

Session Options

Parameter	Type	Default	Description
client	MultisetClient	Required	Authorized HTTP client
overlayRoot	HTMLElement	—	Root element for WebXR DOM overlay
autoLocalize	boolean	—	Start localization automatically when the session begins
relocalization	boolean	—	Re-localize when AR tracking loss is recovered
confidenceCheck	boolean	—	Reject results below confidenceThreshold
confidenceThreshold	number	0.5	Minimum accepted confidence (0.2 to 0.8)
poseTimeoutMs	number	10000	Max milliseconds to wait for a viewer pose before aborting
backgroundLocalization	boolean	—	Re-localize on an interval during the session
bgLocalizationInterval	number	30 (VPS) / 10 (OT)	Seconds between background localization attempts (10 to 180)
autoTracking	boolean	—	Start object tracking automatically (object tracking mode only)
restartTracking	boolean	—	Re-attempt tracking after tracking loss recovery
trackingCaptureDelayMs	number	0	Milliseconds to wait after session start before capturing for tracking
referenceSpaceType	'local' | 'local-floor'	'local'	XR reference space type
framebufferScaleFactor	number	—	XR framebuffer scale. Values below 1 reduce GPU load; values above 1 supersample.

Session Callbacks

Lifecycle

Callback	Arguments	Description
onSessionStart	()	AR session started
onSessionEnd	()	AR session ended
onError	(error: unknown)	Any error in the session lifecycle
onContextLost	()	WebGL context lost. Session auto-ends.
onContextRestored	()	WebGL context restored. User can restart the session.

VPS Localization

Callback	Arguments	Description
onLocalizationInit	()	Localization request started
onLocalizationResult	(result: ILocalizeAndMapDetails)	Localization succeeded and passed confidence check
onLocalizationFailure	(reason?: string)	Localization failed or was rejected by confidence check
onFrameCaptured	(frame: IFrameCaptureEvent)	Camera frame captured as a JPEG Blob
onCameraIntrinsics	(intrinsics: ICameraIntrinsicsEvent)	Camera intrinsic parameters for the captured frame
onPoseResult	(pose: IPoseResultEvent)	Raw pose from the API before confidence filtering

Object Tracking

Callback	Arguments	Description
onObjectTrackingInit	()	Object tracking request started
onObjectTrackingRequested	(frame, intrinsics)	Frame captured, request about to be sent
onObjectTrackingSuccess	(result: IObjectTrackingResponse)	Object detected
onObjectTrackingFailure	(reason?: string)	No object detected or request failed

Static Methods

Method	Returns	Description
XRSessionManager.isSupported()	Promise<boolean>	Check if the browser supports immersive-ar

Instance Methods

Method	Returns	Description
startSession()	Promise<void>	Start the AR session. Must be called from a user gesture handler.
stopSession()	void	Stop the active session
createButton()	HTMLButtonElement	Return a pre-styled START AR / STOP AR button
localizeFrame()	Promise<ILocalizeAndMapDetails | null>	Capture and localize one frame. Session must be active.
trackObjects()	Promise<IObjectTrackingResponse | null>	Capture and run object detection. Session must be active.
isActive()	boolean	Whether an AR session is currently running
getClient()	MultisetClient	Access the underlying HTTP client
dispose()	void	End session, remove all event listeners, release GL resources

Properties

Property	Type	Description
isLocalizing	boolean	Whether a localization or tracking request is in progress

Adapter Hooks

For custom renderer adapters, register handlers that are called on key session events:

Method	Description
setXRFrameHandler(handler)	Called every XR frame. Receives IXRFrameEvent.
setAdapterResultHandler(handler)	Called after successful VPS localization with the result and tracker reference space
setAdapterObjectTrackingHandler(handler)	Called after successful object tracking with the result and tracker reference space
setAdapterSessionHandlers(onStart, onEnd)	Called on session start and session end