Stream Manager#

The CloudXR Stream Manager (NvStreamManager) is a Windows-based service that manages NVIDIA CloudXR™ runtime instances. It provides an RPC interface for starting, stopping, and managing CloudXR services, as well as client authentication for secure connections.

Overview#

The Stream Manager consists of two main components:

NvStreamManager.exe: The server component that hosts the RPC service for managing CloudXR instances. It handles:
- CloudXR service lifecycle management
- Multiple runtime version support
- Client token generation for secure connections
- Certificate fingerprint retrieval for TLS validation
SampleNvStreamManagerClient.exe: A sample client application that demonstrates how to interact with the Stream Manager server.

Architecture#

Prerequisites#

Operating System: Windows 11 (64-bit)
Visual C++ Redistributable: Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 (v14.x)
CloudXR Runtime: Installed and configured

Package Contents#

The Stream Manager is distributed as a separate package from CloudXR Runtime.

Server Components:

NvStreamManager.exe: Main Stream Manager server
cloudxr-runtime.yaml: Configuration file (optional)

Client Components:

SampleNvStreamManagerClient.exe: Prebuilt sample client executable
SampleNvStreamManagerClient.cpp: Sample client source code
NvStreamManagerClient.h: Client library header file
NvStreamManagerClient.dll: Client library DLL

Runtime Installation#

The Stream Manager expects CloudXR Runtime versions to be installed in a releases subfolder relative to the Stream Manager executable. Each runtime version must be in its own versioned directory.

Required folder structure:

NvStreamManager.exe
releases\
  6.0.0\
    openxr_cloudxr.json
    (other runtime files)

When you call StartCxrService 6.0.0, the Stream Manager looks for the runtime in .\releases\6.0.0\.

Important

Ensure that the CloudXR Runtime files are placed in the correct releases/<version>/ folder structure before starting the Stream Manager. The GetSupportedVersions command will list all properly installed runtime versions.

Starting the Stream Manager#

Basic Startup#

Start the Stream Manager server with default settings:

NvStreamManager.exe

This starts the server with:

Default pipe name: cloudxr-runtime
Default runtime path: .\releases

Custom Configuration#

Custom pipe name:

NvStreamManager.exe --pipe my-custom-pipe

Note

When using a custom pipe name, clients must connect using the same pipe name.

Custom configuration file:

# Use a different config file
NvStreamManager.exe --config path\to\config.yaml

# Disable configuration loading
NvStreamManager.exe --config ""

Using the Sample Client#

SampleNvStreamManagerClient.exe is an interactive command-line client that demonstrates how to use the Stream Manager API.

Manual Server Start#

Start the Stream Manager server (see previous section)
Run the client:
```
SampleNvStreamManagerClient.exe
```
The client automatically:
- Loads the NvStreamManagerClient.dll
- Connects to the server via named pipe
- Presents an interactive command prompt

Automatic Server Start#

The client can automatically start the Stream Manager as a background subprocess:

SampleNvStreamManagerClient.exe --run-stream-manager=<path-to-NvStreamManager.exe>

Example:

SampleNvStreamManagerClient.exe --run-stream-manager=..\Server\NvStreamManager.exe

Features of automatic mode:

Stream Manager starts as a background process with no console window
Log output is redirected to NvStreamManager_YYYYMMDD_HHMMSS.log
The Stream Manager process automatically exits when the client exits

Available Commands#

Command	Description	Example
`StartCxrService <version>`	Start CloudXR service with specified version	`StartCxrService 6.0.0`
`StopCxrService`	Stop running CloudXR service	`StopCxrService`
`GetSupportedVersions`	List available CloudXR versions	`GetSupportedVersions`
`GetCxrServiceJsonPath`	Get OpenXR runtime JSON path	`GetCxrServiceJsonPath`
`GetCxrServiceStatus`	Get service connection status	`GetCxrServiceStatus`
`SetClientId <id>`	Set client identifier and get auth token	`SetClientId MyApp123`
`GetCryptoKeyFingerprint <algo>`	Get certificate fingerprint (0=MD5, 1=SHA1, 2=SHA256, 3=SHA512)	`GetCryptoKeyFingerprint 2`
`ShutdownManager`	Shut down the manager process	`ShutdownManager`
`help`	Show help message	`help`
`exit` or `quit`	Exit the client	`exit`

Usage Examples#

Basic Workflow#

> GetSupportedVersions
Getting supported CloudXR versions
Supported versions:
  - 6.0.0

> SetClientId MyClient
Setting client ID: MyClient
Client ID set successfully
Token: AUTH_TOKEN_GENERATED_BY_SERVER

> StartCxrService 6.0.0
Starting CloudXR service with version: 6.0.0
CloudXR service start request successful

> GetCxrServiceStatus
Getting CloudXR service status
CloudXR Service Status:
  OpenXR Runtime: Running
  OpenXR App: Connected
  CloudXR Client: Connected
  OpenXR Log File Path: C:\Users\xxx\AppData\Local\Temp\com.nvidia.CloudXR_xxx

> StopCxrService
Stopping CloudXR service
CloudXR service stop request successful

Important

You must call SetClientId before StartCxrService. This registers the client and generates an authentication token.

Secure Connection Setup#

For CloudXR Framework clients using secure connection mode (localSecure), you must retrieve the certificate fingerprint in addition to the client token:

> SetClientId MyAVPClient
Setting client ID: MyAVPClient
Client ID set successfully
Token: AUTH_TOKEN_GENERATED_BY_SERVER

> GetCryptoKeyFingerprint 2
Getting cryptographic key fingerprint for algorithm: 2
Cryptographic key fingerprint: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

> StartCxrService 6.0.0
Starting CloudXR service with version: 6.0.0
CloudXR service start request successful

The client token and certificate fingerprint are used by CloudXR Framework applications when connecting with localSecure connection type. Refer to Secure Connection Mode for details.

Programmatic Integration#

To integrate the Stream Manager into your own applications, use the NvStreamManagerClient.dll API:

#include "NvStreamManagerClient.h"

// Create and connect client
nv_rpc_client_t client;
nv_rpc_client_create("cloudxr-runtime", &client);
nv_rpc_client_connect(client);

// Start CloudXR service
nv_rpc_client_start_cxr_service(client, "6.0.0", 5);

// Get OpenXR runtime JSON path
char json_path[1024];
nv_rpc_client_get_cxr_service_json_path(client, json_path, sizeof(json_path));

// Monitor service status
nv_rpc_cxr_service_status_t status;
nv_rpc_client_get_cxr_service_status(client, &status);

// Your application logic here...

// Cleanup
nv_rpc_client_stop_cxr_service(client);
nv_rpc_client_disconnect(client);
nv_rpc_client_destroy(client);

OpenXR Runtime Configuration#

When using the Stream Manager, you can programmatically configure the OpenXR loader to use the CloudXR runtime:

// Get the runtime JSON path from Stream Manager
char json_path[1024];
nv_rpc_client_get_cxr_service_json_path(client, json_path, sizeof(json_path));

// Initialize the OpenXR loader with the CloudXR runtime
PFN_xrInitializeLoaderKHR initializeLoader = nullptr;
xrGetInstanceProcAddr(
    XR_NULL_HANDLE,
    "xrInitializeLoaderKHR",
    reinterpret_cast<PFN_xrVoidFunction*>(&initializeLoader));

std::vector<XrLoaderInitPropertyValueEXT> propertyList = {};
propertyList.push_back(XrLoaderInitPropertyValueEXT{
    "XR_RUNTIME_JSON",
    json_path
});

XrLoaderInitInfoPropertiesEXT loaderProperties{
    .type = XR_TYPE_LOADER_INIT_INFO_PROPERTIES_EXT,
    .propertyValueCount = static_cast<uint32_t>(propertyList.size()),
    .propertyValues = propertyList.data(),
};

initializeLoader((XrLoaderInitInfoBaseHeaderKHR*)&loaderProperties);

// Now create your XrInstance - it will use the CloudXR runtime