使用 NVIDIA CloudXR.js 构建和流式传输基于浏览器的 XR 体验

向企业用户交付高保真 VR 和 AR 体验，通常需要进行原生应用开发、定制设备管理以及复杂的部署流水线。现在，借助新的 JavaScript SDK NVIDIA CloudXR.js，开发者可以将由 GPU 渲染的沉浸式内容直接流式传输到标准网页浏览器——无需应用商店、无需安装、无需针对特定设备构建版本。

NVIDIA CloudXR.js 将 NVIDIA RTX 远程渲染的全部能力带到了 Web 平台。这是沉浸式应用构建与交付方式的一次根本性转变。NVIDIA CloudXR.js 将企业 XR 的访问范围从原生开发工作流扩展到了广泛的 Web 开发者社区。

开发者在 NVIDIA Omniverse 中构建数字孪生、机器人远程操作系统或交互式 3D 培训环境时，现在可以通过一个 URL 触达 XR 头显上的用户。本文将介绍该 SDK 的架构、其核心 API，以及如何将其连接到 Omniverse、NVIDIA Isaac Lab 和 LÖVR 等服务器应用程序。

如何运行并托管 NVIDIA CloudXR.js 客户端

本节说明如何运行和托管 NVIDIA CloudXR.js Web 客户端，包括先决条件和架构概述。

先决条件

要运行和托管基于 CloudXR.js 的 Web 客户端，你需要一台安装了 Node.js v20 或更高版本以及 npm 的计算机。可以查看 NVIDIA CloudXR.js Sample Client，在无需构建 Web 客户端的情况下进行试用。你仍然需要一台运行 CloudXR Runtime 的 NVIDIA CloudXR 服务器，以及一个兼容 OpenXR 的应用。先决条件包括：

• 客户端 Node.js v20 或更高版本和 npm；兼容 WebGL2 和 WebXR 的浏览器（例如，头显上的 Meta Quest Browser 或 Pico Browser，或任何运行模拟器的浏览器）；熟悉 JavaScript/TypeScript 和基本 WebGL 概念；用于头显测试的 Meta Quest 2/3/3s（OS v79+）或 Pico 4 Ultra（Pico OS 15.4.4U+）
• 服务器端 配备 NVIDIA GPU 的服务器，安装符合最新要求的 NVIDIA CloudXR Runtime；兼容 OpenXR 的服务器应用程序，例如 Omniverse、Isaac Lab 或 LÖVR
• 强烈建议使用延迟低于 20 毫秒、带宽超过 100 Mbps 的 WiFi 6 或 6E 网络

CloudXR.js 架构

CloudXR.js 使用一种双层连接模型，将 Web 应用托管与 XR 串流管线分离（图 1）。

客户端 Web 服务器：标准 Node.js 开发服务器（或任何静态托管解决方案）通过 HTTP 或 HTTPS 将 Web 应用程序提供给客户端设备。

CloudXR Runtime 连接：SDK 从浏览器建立到服务器上运行的 CloudXR Runtime 的 WebSocket 连接。该通道承载基于 WebRTC 的视频流、姿态跟踪数据以及控制器/手部输入。

在服务器端，CloudXR Runtime 可与任何兼容 OpenXR 的应用程序配对。它捕获渲染后的立体帧，使用硬件加速的 AV1、H.265 或 H.264 对其进行编码，并将其流式传输到客户端。客户端解码视频，将其合成到 WebXR 帧缓冲区中，并将跟踪数据发送回服务器，从而以最高每秒 120 帧的速率闭合循环。

该 Web 应用本身与框架无关。CloudXR.js 可与原生 WebGL、React Three Fiber 或任何其他兼容 WebXR 的库集成。

安装 SDK

要将 CloudXR.js 添加到项目中，请从 NVIDIA NGC 下载 SDK。然后将其导入你的项目。

npm install </path/to/sdk/nvidia-cloudxr-version.tar.gz>

该软件包包含 TypeScript 类型定义，因此 IDE 自动补全和类型检查可开箱即用。在标准网页上执行此操作。

创建流式会话

整个 SDK 的接口都围绕单一入口点：createSession。导入它，配置连接和渲染参数，并传入可选的委托回调以处理生命周期事件。以下代码片段展示了使用 createSession API 的核心部分。

// Basic session creation
const session = createSession({
 serverAddress: '192.168.1.100',
 serverPort: 49100,
 useSecureConnection: false,
 perEyeWidth: 2048,
 perEyeHeight: 1792,
 // from WebGl API
 gl: webglContext, 
// from WebXR API
 referenceSpace: xrReferenceSpace
});

// With event delegates
const session = createSession(sessionOptions, {
 onStreamStarted: () => {
   console.info('CloudXR streaming started');
 },
 onStreamStopped: (error) => {
   if (error) {
     console.error('Streaming error:', error);
   } else {
     console.info('Streaming stopped normally');
   }
 }
});

// Connect to CloudXR Runtime
if (session.connect()) {
 console.info('Connection initiated');
}

perEyeWidth 和 perEyeHeight 的值（必须是 16 的倍数）定义每只眼睛视图的分辨率。SDK 会根据这些值自动推导出完整的流分辨率。

集成渲染循环

连接后，从你的 WebXR 渲染循环驱动流式传输管线。每一帧需要两次调用：先将当前跟踪状态发送到服务器，然后渲染接收到的帧。

function onXRFrame(time: number, frame: XRFrame) {
  // Send head pose, controllers, and hand tracking to the server
  session.sendTrackingStateToServer(time, frame);

  // Render the streamed frame into the WebXR layer
  session.render(time, frame, xrSession.renderState.baseLayer);
  // Continue the loop
  xrSession.requestAnimationFrame(onXRFrame);
}
xrSession.requestAnimationFrame(onXRFrame);

sendTrackingStateToServer 方法会自动捕获并传输控制器按钮按下、扳机值、控制器姿态、手部跟踪数据（当设备支持时）以及观看者的头部姿态。服务器使用这些数据，从正确的视角并以正确的输入状态渲染下一帧。随后，render 方法将解码后的视频合成到 XR 显示中。

探索示例客户端

CloudXR.js 提供两个示例客户端，用于演示不同的集成方法。

WebGL 示例

WebGL 示例（simple/）提供了一个最小化的单文件 TypeScript 实现，可直接与 WebXR 和 WebGL2 API 配合使用。它包括连接配置 UI、浏览器能力检查以及一个简单明了的渲染循环。这是了解 CloudXR.js 底层工作原理的最快途径。

React 示例

React 示例（react/）展示了一种使用 React Three Fiber、React Three XR 和 React Three UIKit 的生产级架构。它具备基于组件的会话管理、双 UI 系统（用于配置的 2D HTML，以及用于交互的 3D VR 内面板），并提供 WebGL 状态跟踪，以防止 React Three Fiber 与 CloudXR 之间发生渲染冲突。

这两个示例都支持 Docker 部署，便于快速测试：

# WebGL sample
docker build -t cloudxr-js-sample --build-arg EXAMPLE_NAME=simple .
docker run -d --name cloudxr-js-sample -p 8080:80 -p 8443:443 cloudxr-js-sample
# React sample
docker build -t cloudxr-react-sample --build-arg EXAMPLE_NAME=react .
docker run -d --name cloudxr-react-sample -p 8080:80 -p 8443:443 cloudxr-react-sample

对于支持热重载的本地开发，请安装依赖项并启动开发服务器：

cd simple  # or react
npm install </path/to/sdk/tarball.tar.gz
npm run dev-server

在浏览器中访问 http://localhost:8080。在桌面端，Immersive Web Emulator Runtime（IWER）会自动加载以模拟 Meta Quest 3，因此你无需实体头显即可进行开发和测试。

连接到服务器应用程序

CloudXR.js 可与任何在 CloudXR Runtime 旁运行的 OpenXR 兼容应用配合使用。以下三个示例展示了你可以流式传输的内容范围：NVIDIA Omniverse、NVIDIA Isaac Lab 和 LÖVR。

正文：NVIDIA Omniverse

将高保真的 USD 数字孪生场景流式传输到 XR 头显，用于建筑漫游、设计评审和工业培训。Omniverse Kit SDK 109.0.2 及更高版本包含集成的 CloudXR WebRTC 运行时，因此流式传输管线直接内置于该平台中。操作人员可使用手部追踪与 3D 内容交互，在流式传输环境中进行直接操控。

正文：NVIDIA Isaac Lab

为灵巧机器人构建遥操作工作流。佩戴 Quest 2/3/3s 或 Pico 4 Ultra 的操作员可以看到机器人仿真的实时立体渲染，并使用手部追踪来控制机器人。Isaac Lab 在 Linux 上通过 Docker 和 NVIDIA Container Toolkit 运行，支持双 GPU 配置以获得最高性能。有关详细信息，请参阅 Setting up CloudXR Teleoperation。

正文：LÖVR

LÖVR 是一个轻量级、开源、基于 Lua 的 VR 框架，提供了一条通往可运行服务器的简单路径。使用 --webrtc 标志启动 LÖVR，并连接 CloudXR.js 客户端。这非常适合快速原型设计和测试客户端设置。请访问 GitHub 上的 NVIDIA/cloudxr-lovr-sample 以开始使用。

面向生产环境配置网络

对于生产部署或 HTTPS 托管，请设置一个带有 TLS 终止的 WebSocket 代理。CloudXR.js 包含一个基于 Docker 的 HAProxy 配置示例，可自动处理此配置：

cd proxy
docker build -t cloudxr-wss-proxy .
docker run -d --name wss-proxy --network host \
  -e BACKEND_HOST=localhost \
  -e BACKEND_PORT=49100 \
  -e PROXY_PORT=48322 \
  cloudxr-wss-proxy

该代理会生成自签名证书，连接到 49100 端口上的 CloudXR Runtime，并在 48322 端口监听安全 WebSocket 连接。对于企业级 Kubernetes 部署，SDK 文档包含一个 NGINX Ingress 配置，支持对多个 CloudXR 服务器进行负载均衡。

确保你的防火墙允许 TCP 端口 49100（信令）、UDP 端口 47998（媒体流传输）以及 TCP 端口 48322（WSS 代理，如果使用 HTTPS）。

开始使用 CloudXR.js

NVIDIA CloudXR.js 将企业级 XR 流媒体带到 Web 平台——通过 URL 交付由 GPU 渲染的沉浸式内容，无需原生应用。该 SDK 提供了简洁、精简的 API，可与任何兼容 WebXR 的框架集成，并支持多种服务器应用，从 Omniverse 数字孪生到 Isaac Lab 机器人遥操作。它包含生产部署所需的网络和性能工具。

通过为每位 Web 开发者提供工具，使其能够构建并交付沉浸式体验，而无需承担原生 XR 开发的额外负担，CloudXR.js 让全新类别的应用成为可能。我们期待看到开发者社区利用这个新 SDK 构建出怎样的作品。

下载 CloudXR.js 并试用示例客户端。若想以最快路径获得可运行的演示，请从 LÖVR 示例服务器和 WebGL 客户端开始。如需完整的 API 参考、配置指南和部署文档，请访问 CloudXR.js SDK 文档。