What is the webrtc-stream-manager?

This package simplifies playing back videos via WebRTC from the Nx Server versions 5.1 or later.

What can it do?

The exported WebRTCStreamManager class handles establishing a WebRTC connection with the Server.

When initializing the connection using the connect static method, a video element could optionally be passed as an argument to be used to gather metrics as part of the stream switching algorithm.

The WebRTCStreamManager defaults to showing live, but also allows for updating the playback position to play streams from archive. The playback position could also be updated; when the position is updated, all WebRTCStreamManager instances playback positions are synced to the new time stamp.

Usage

The WebRTCStreamManager class exposes a connect static method, which is used to initialize a connection. Optionally, it accepts a reference to a video element to automatically close the connection once the player is no longer on the DOM.

Example webRtcUrlFactory Function

The WebRTCStreamManager.connect method takes as a first argument a function that returns the webrtc-tracker endpoint.

The camera_id query parameters and x-server-guid query parameters are required, pos is optional.

Authentication is handled either by cookies before calling WebRTCStreamManager.connect or by passing a system scoped access token as the last argument or by providing a digest authentication key using the auth query parameter.

Cookie authentication is recommended because digest authentication is disabled for 2fa enabled systems.

// Could be a direct connection '{serverIp}:{port}` or a cloud relayed connection '{serverId}.{cloudSystemId}.{relayUrl}'
const systemUrl = 'Server url';
const serverId = 'Server id';
const cameraId = 'Camera id';
const position = 0; // Initial position 
const webRtcUrlFactory = () => `wss://${systemUrl}/webrtc-tracker?camera_id=${cameraId}&x-server-guid=${serverId}&pos=${position}`;

Example Usage

The connect static methods returns an observable emits streams and errors.

To update a video element to use that stream, set the srcObject to the stream if it exists.

To start autoplaying, you can also set muted and autoplay to true.

Target Element

<video id="someTargetId" autoplay muted></video>
const videoElement = document.querySelector('video#someTargetId')

Initializing Connection and Setting Video Source

/** * Assumes that user is already authenticated using cookie authentication or an auth query param * is included as part of the url from webRtcUrlFactory. */
WebRTCStreamManager.connect(webRtcUrlFactory, videoElement).subscribe(
  ([stream, error]) => {
    if (stream) {
      targetVideoElement.srcObject = stream;
      targetVideoElement.muted = true;
      targetVideoElement.autoplay = true;
    }

    if (error) {
      handleError(error)
    }
   }
  );

Initializing Connection Using Access Token and Setting Video Source

/** * The access token should be a system scoped access token. *
* The connect static method can authenticate using cookie authentication automatically. */
WebRTCStreamManager.connect(webRtcUrlFactory, videoElement, hasSecondaryStream, systemScopedAccessToken).subscribe(
  ([stream, error]) => {
    if (stream) {
      targetVideoElement.srcObject = stream;
      targetVideoElement.muted = true;
      targetVideoElement.autoplay = true;
    } 

    if (error) {
      handleError(error) 
    }
  }
);

WebRTC Stream Manager Example

This is a minimal example of how to use the webrtc-stream-manager package to integrate streaming from a Server to your own integrations.

How to start the demo

Install workspace dependencies

Within the root folder run

npm install

This will install shared workspace dependencies and link local packages.

Run demo

Within the examples/webrtc-stream-manager-example folder run

npm start

Open demo page

Open http://127.0.0.1:5173.

Enter the Cloud Instance Url for the instance with the system you'd like to view a WebRTC stream.

Select Authenticate to log in using OAuth.

After OAuth redirects back to the demo, the first online system that supports WebRTC and the first online camera from that system is automatically selected.

If you would like to select a different system or camera, the available options will are available on the dropdown.

Click Start WebRTC Connection to begin playback.

Demo Source code

The relevant part of the source code related to the webrtc-stream-manager package is in the startStream function in the main.ts file.

We pass in the webRtcUrlFactory and videoElement into the WebRTCStreamManager.connect static method.

Then we subscribe to the returned observable and handle the stream or error that is emitted.

In this demo, we're just setting the srcObject to the stream.

const startStream = (relayUrl: string, cameraId: string, serverId: string) => {
  const webRtcUrlFactory = () => `wss://${relayUrl}/webrtc-tracker/?camera_id=${cameraId}&x-server-guid=${serverId}`;
  WebRTCStreamManager.connect(webRtcUrlFactory, videoElement).pipe(takeUntil(newStream$)).subscribe(([stream, error]) => {
  if (stream) {
    videoElement.srcObject = stream;
    videoElement.muted = true;
    videoElement.autoplay = true; 
  }
}