Interface: SessionOptions#

Defines configuration options for a CloudXR streaming session.

Defines all configuration parameters needed to create and configure a CloudXR streaming session. Required parameters must be provided, while optional parameters have sensible defaults.

Example#

const sessionOptions: SessionOptions = {
  // Required parameters
  serverAddress: '192.168.1.100',
  serverPort: 49100,
  useSecureConnection: false,
  gl: webglContext,
  perEyeWidth: 2048,
  perEyeHeight: 1792,
  referenceSpace: xrReferenceSpace,

  // Optional parameters with defaults
  deviceFrameRate: 90,
  maxStreamingBitrateKbps: 150000,
  codec: 'av1'
};

Properties#

serverAddress#

serverAddress: string

Address of the CloudXR Runtime.

Can be an IP address (e.g., ‘192.168.1.100’) or hostname. For local development, use ‘localhost’ or ‘127.0.0.1’.

Example#

serverAddress: '192.168.1.100'  // IP address
serverAddress: 'cloudxr-server.local'  // Hostname
serverAddress: 'localhost'  // Local development

serverPort#

serverPort: number

Port of the CloudXR Runtime.

The default CloudXR Runtime port is 49100. Ensure this port is accessible and not blocked by firewalls.

Default#

Example#

serverPort: 49100  // Default CloudXR port

useSecureConnection#

useSecureConnection: boolean

Connect using secure connection (WSS/HTTPS).

When true, uses secure WebSocket (WSS) connection. When false, uses unsecured WebSocket (WS) connection. For production deployments, secure connections are recommended.

Default#

false

Example#

useSecureConnection: false  // Development
useSecureConnection: true   // Production

mediaAddress?#

optional mediaAddress: string

Address for WebRTC media streaming connection.

Only needed when the streaming server is behind NAT and the media connection requires a different address than the signaling server. If not provided, the SDK uses ICE information from signaling. Must be a valid IPv4 address.

Example#

mediaAddress: '192.168.1.100'  // Media server IP for NAT traversal

mediaPort?#

optional mediaPort: number

Port for WebRTC media streaming connection.

Used together with mediaAddress when the streaming server is behind NAT. Use 0 to let the server choose the port from ICE information.

Note: This option only takes effect when mediaAddress is also set.

Example#

mediaPort: 49200  // Specific media port
mediaPort: 0      // Use server-provided port

signalingQueryParameters?#

optional signalingQueryParameters: string

Additional query parameters to append to the signaling URL.

These parameters are appended to the WebSocket signaling URL and are passed through to the server. Use this for custom authentication tokens, session identifiers, or other product-specific parameters.

The value is appended after the SDK’s internal query parameters using &.

Format: key1=value1&key2=value2

Generated URL: wss://server:port/path?<SDK params>&<signalingQueryParameters>

Example#

signalingQueryParameters: 'token=abc123&sessionId=xyz'
signalingQueryParameters: 'auth=bearer_token'

signalingResourcePath?#

optional signalingResourcePath: string

Resource path for proxied signaling connections.

Optional path to be included in the signaling URL when routing through a proxy service. The proxy is expected to remove this path before forwarding the request to the streaming server.

The path is inserted between the server address and the SDK’s internal paths.

Generated URL: wss://<serverAddress>:<serverPort>/<signalingResourcePath>/<SDK paths>?...

Example#

// Route through proxy with target server IP
signalingResourcePath: '192.168.1.100'
// Route through proxy with custom path
signalingResourcePath: 'cloudxr-proxy'
signalingResourcePath: '/api/v1/stream'

gl#

gl: WebGL2RenderingContext

WebGL context for rendering.

Must be a WebGL2RenderingContext obtained from a canvas element. This context will be used for all CloudXR rendering operations.

Example#

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2');
// Use gl in sessionOptions

perEyeWidth#

perEyeWidth: number

Width of each eye in pixels.

This should match the per-eye resolution you want to render. Must be a positive (finite) integer, multiple of 16, and >= 128. The actual stream width will be calculated as perEyeWidth * 2.

Example#

perEyeWidth: 2048  // Max width if using H264 codec

perEyeHeight#

perEyeHeight: number

Height of each eye in pixels.

This should match the per-eye resolution you want to render. Must be a positive (finite) integer, multiple of 16, and >= 128. The actual stream height will be calculated as perEyeHeight * 9 / 4.

Example#

perEyeHeight: 1792  // Max height if using H264 codec

reprojectionGridCols?#

optional reprojectionGridCols: number

Depth reprojection mesh column count (vertex columns, not cell columns).

Together with reprojectionGridRows, controls the reprojection mesh resolution.

Valid combinations:

if either reprojectionGridCols or reprojectionGridRows is undefined, use factor-based mesh sizing from stream resolution (default behavior)
reprojectionGridCols >= 2 and reprojectionGridRows >= 2: use explicit vertex-grid counts directly

Any mixed or invalid pair is rejected during session creation.

Default#

undefined (factor mode)

reprojectionGridRows?#

optional reprojectionGridRows: number

Depth reprojection mesh row count (vertex rows, not cell rows).

See reprojectionGridCols for full validation semantics.

Default#

undefined (factor mode)

referenceSpace#

referenceSpace: XRReferenceSpace

XR reference space to use for coordinate system calculations.

This is used for getting the viewer pose from the XR frame and should be obtained from the WebXR session.

Example#

const referenceSpace = await xrSession.requestReferenceSpace('local-floor');

glBinding?#

optional glBinding: XRWebGLBinding

XR WebGL binding used to query viewport information for each eye.

Optional binding that provides additional viewport information. If not provided, default viewport calculations will be used.

Example#

const glBinding = new XRWebGLBinding(xrSession, gl);

codec?#

optional codec: string

Video codec for streaming.

Supported codecs: ‘h264’, ‘av1’. AV1 provides better compression but requires more CPU/GPU resources for encoding/decoding.

Default#

'av1'

Example#

codec: 'av1'   // Better compression, more CPU intensive
codec: 'h264'  // Faster encoding/decoding, larger bandwidth

deviceFrameRate?#

optional deviceFrameRate: number

Device frame rate (maximum FPS).

The server will treat this as a maximum FPS and choose an appropriate streaming frame rate that is lower than this value. Higher frame rates provide smoother motion but require more bandwidth.

Default#

Example#

deviceFrameRate: 90   // Quest 3 standard
deviceFrameRate: 120  // High refresh rate
deviceFrameRate: 72   // Lower power mode

maxStreamingBitrateKbps?#

optional maxStreamingBitrateKbps: number

Maximum streaming bitrate in Kilobits per second.

Controls the maximum bandwidth used for streaming. Higher bitrates provide better quality but require more network bandwidth.

Default#

Example#

maxStreamingBitrateKbps: 150000  // 150 Mbps
maxStreamingBitrateKbps: 100000  // 100 Mbps (lower bandwidth)
maxStreamingBitrateKbps: 200000  // 200 Mbps (high quality)

telemetry?#

optional telemetry: object

Telemetry configuration options

enabled?#

optional enabled: boolean

Enable telemetry collection. Default is true.

appInfo?#

optional appInfo: object

Application information for telemetry

appInfo.version?#

optional version: string

Application version (e.g., “1.0.0”)

appInfo.product?#

optional product: string

Product name (e.g., “MyApp”)

enablePoseSmoothing?#

optional enablePoseSmoothing: boolean

Enable secondary smoothing on predicted positions.

When enabled, applies an additional smoothing pass to reduce jitter in predicted positions. This only affects position, not orientation.

Default#

true

Example#

enablePoseSmoothing: false  // Disable position smoothing

posePredictionFactor?#

optional posePredictionFactor: number

Pose prediction factor (0.0 to 1.0) that scales the prediction horizon.

This multiplier is applied to the calculated prediction horizon for both position and orientation. A value of 1.0 uses full prediction, 0.5 uses half the prediction horizon, and 0.0 disables prediction entirely.

Default#

1.0

Example#

posePredictionFactor: 0.5  // Use 50% of calculated prediction
posePredictionFactor: 0.0  // Disable prediction

enableTexSubImage2D?#

optional enableTexSubImage2D: boolean

Enable texSubImage2D for texture updates.

When enabled, uses texSubImage2D for updating textures after the initial allocation, which can improve performance on devices with newer Chromium browsers (such as Meta Quest Browser with Chromium 140). But it will cause enormously degraded performance on devices with older Chromium browsers.

Default#

false

Example#

enableTexSubImage2D: true  // Enable for Quest devices
enableTexSubImage2D: false // Disable for compatibility

useQuestColorWorkaround?#

optional useQuestColorWorkaround: boolean

Enable Quest color workaround for Display P3 color space.

When enabled, uses Display P3 color space for texture unpacking to work around WebXR color issues in the Meta Quest Browser.

@default false

iceServers?#

optional iceServers: object

ICE server configuration for STUN/TURN servers.

Used for NAT traversal when direct peer-to-peer connection is not possible. Provide TURN servers for enterprise deployments behind firewalls.

This configuration uses standard WebRTC types from the W3C WebRTC specification. See MDN RTCConfiguration for detailed documentation on these options.

iceServers?#

optional iceServers: RTCIceServer[]

Array of STUN/TURN server configurations.

Uses the standard WebRTC RTCIceServer format. Each server can specify urls (required), and optionally username and credential for TURN authentication.

See MDN iceServers documentation.

iceTransportPolicy?#

optional iceTransportPolicy: RTCIceTransportPolicy

ICE transport policy controlling candidate selection.

Uses the standard WebRTC RTCIceTransportPolicy type.

'all': Use all available candidates (default)
'relay': Only use TURN relay candidates, forcing all traffic through the TURN server

Note: The deprecated 'public' policy is not supported.

See MDN iceTransportPolicy documentation.

Example#

iceServers: {
  iceServers: [
    { urls: 'stun:stun.example.com:3478' },
    {
      urls: 'turn:turn.example.com:3478',
      username: 'user',
      credential: 'password'
    }
  ],
  iceTransportPolicy: 'all'  // 'all' or 'relay'
}