Is this page helpful?

OV Web RTC Library v6.6.0#

This package provides functionality for managing Omniverse Kit applications streaming from GFN, on a local machine, or from a container instance with a provided URL.

Versioned documentation: The complete API documentation is bundled with the published package. To read the docs that match the version you have installed, open node_modules/@nvidia/ov-web-rtc/docs/index.html in a browser after installing.

Usage#

The AppStreamer class is the main entry point into this library. You can use it to connect to, pause, unpause, and terminate a streaming Omniverse Kit application session. You can also use it to send and receive custom messages to and from the streaming Kit application. The Kit application can stream from GFN, NVCF, OVC, or an ad hoc development environment.

Scoping NPM#

The correct scope must be defined in your .npmrc file before installing.

@nvidia:registry=https://edge.urm.nvidia.com/artifactory/api/npm/omniverse-client-npm/

Installation#

npm install @nvidia/ov-web-rtc

Importing#

import { AppStreamer } from '@nvidia/ov-web-rtc'

GFN#

If connecting to an application running on GFN, you must import GFN separately. The recommended method to import GFN into a project is by sourcing the CDN in the project index.html file, as shown below:

<!DOCTYPE html>
<html lang="en">
    <body>
        <script src="https://sdk.nvidia.com/gfn/client-sdk/1.x/gfn-client-sdk.js"></script>
    </body>
</html>

Creating an AppStreamer#

Construct an AppStreamer instance and drive the session through its lifecycle methods — connect, start, stop, terminate — plus sendMessage for custom messages:

const stream = new AppStreamer();

Each instance owns its own underlying stream. The examples below use this stream instance.

The static form (AppStreamer.connect(...), AppStreamer.terminate(), and so on) is deprecated but still works for backward compatibility: it forwards to a single shared instance — race-prone when more than one stream is active — and each call logs a one-time deprecation warning. It will be removed in a future major release. Construct an instance with new AppStreamer() instead.

Examples#

Connecting#

The following code examples illustrate how to manage streaming connections directly to a container, as well as infrastructure environments such as GFN and NVCF.

Set up the Configuration#

Direct Configuration#

Configuration for a Kit application running in a directly accessible container, either local or remote:

// This example server is localhost, but can be a valid remote IP as well.

const streamParams: DirectConfig = {
    streamSource : StreamType.DIRECT,
    logLevel     : LogLevel.WARN,
    streamConfig : {
        server        : '<some ip address>',
        width         : 1920,
        height        : 1028,
        fps           : 60,
        onStart       : (message: StreamEvent) => {console.info('Stream started')},
        onStop        : (message: StreamEvent) => {console.info('Stream stopped')},
        onStreamStats : (message: StreamEvent) => {console.info('Stream stats')}
    }
};

Configure NVCF#

Configuration for a Kit application running on NVCF:

// This example server is localhost, but can be a valid remote IP as well.

const streamParams: NVCFConfig = {
    streamSource : StreamType.NVCF,
    logLevel     : LogLevel.WARN,
    streamConfig : {
        signalingPort   : <some port number>
        signalingServer : '<some URL>',
        signalingPath   : '<some path>'
        signalingQuery  : ''<some query>'
        width           : 1920,
        height          : 1028,
        fps             : 60,
        onStart         : (message: StreamEvent) => {console.info('Stream started')},
        onStop          : (message: StreamEvent) => {console.info('Stream stopped')},
        onStreamStats   : (message: StatsEvent) => {console.info('Stream stats')}
    }
};

Configure GFN#

Configuration for a Kit app running on GFN:

const streamParams: GFNConfig = {
    streamSource : StreamType.GFN,
    logLevel     : LogLevel.WARN,
    streamConfig : {
        // GFN will be resolved by the script source discussed above.
        GFN             : GFN,
        catalogClientId : <your value>,
        clientId        : <your value>,
        cmsId           : <your value>,
        onStart         : (message: StreamEvent) => {console.info('Stream started')},
        onStop          : (message: StreamEvent) => {console.info('Stream stopped')},
        onStreamStats   : (message: StreamEvent) => {console.info('Stream stats')}
    }
};

Connect & Disconnect#

Connect using Config params#

The library supports connections to Kit applications streaming from multiple infrastructure options. The options are of type StreamType. They allow you to change which infrastructure to connect to with only minor edits to the configuration. Below are examples of configurations for each streaming type.

Using the streamParams config:

stream.connect(streamParams)
    .then((result: StreamEvent) => {
       // The connection request was successful. The onStart
       // callback will fire when the stream is ready.
       console.info(result);
    })
    .catch((error: StreamEvent) => {
       // The connection request has failed.
       console.error(error);
    });

Disconnect#

Call terminate() on the same instance you connected with:

stream.terminate()
    .then((result: StreamEvent) => {
          // Request has been made successfully. The onStop
          // callback will fire when termination is complete.
          console.info(result));
    })
    .catch((error: StreamEvent) => {
          // The terminate request has failed.
          console.error(error));
    });

Callbacks#

All of the callbacks are optional, but there are a few that are very helpful.

onStart()#

Define your onStart callback in streamParams to determine the success of the connection request.

onStart(message: StreamEvent) : void {
    if ( message.status === EventStatus.SUCCESS ) {
        // The stream is connected and ready.
        console.info('onStart:', message));
    }
    else if ( message.status === EventStatus.WARNING ) {
        // There may be an issue with the stream connection.
        console.warn('onStart:', message));
    }
    else if ( message.status === EventStatus.ERROR ) {
        // The connection has failed.
        console.info('onStart:', message));
    }
}

onStop()#

Define your onStop callback message to determine unexpected and successful stream disconnections.

onStop(message: StreamEvent) : void {
    if ( message.action === EventAction.TERMINATE &&
          message.status === EventStatus.ERROR ) {
          // The connected stream has been disconnected unexpectedly.
          console.error('onStop:', message));
    }
    else if ( message.action === EventAction.TERMINATE &&
                message.status === EventStatus.SUCCESS ) {
          // A request to disconnect the stream was successful -
          // the stream has been disconnected.
          console.info('onStop:', message));
    }
}

onStreamStats()#

The onStreamStats callback, if passed, will be called at regular intervals to provide information and performance metrics about the connected stream.

onStreamStats(message: StatsEvent) : void {
    console.info('Stream stats:', message.stats);
}