@istreamplanet/preview-player.js NPM

PreviewPlayer Javascript Client

Javascript client for playing back PreviewPlayer streams. The following complete example shows how easy it is to use:

<html>
  <head>
    <!-- Include transpiled preview-player.js somehow, e.g. via webpack -->
    <script src="preview-player.min.js"></script>
  </head>
  <body>
    <video id="vid" autoplay></video>

    <script>
      // Get the video element from above.
      var video = document.querySelector('#vid');

      // Create a PreviewPlayer instance for a given video ID and set up handlers.
      var previewPlayer = new PreviewPlayer(video, 'SERVER:PORT/video/ID', 'token');

      previewPlayer.on('error', function(err) {
        // Print any errors to the Javascript console for debugging.
        console.log(err);
      });
    </script>
  </body>
</html>

Architecture

The client creates a persistent WebSocket connection to the backend. If the connection is successful it waits for control messages and media data blobs. Control messages tell it how to create media source elements which are used to feed the data blobs into the associated HTML <video> element.

New dynamic media source URLs are created as needed when streams change or are restarted. These URLs should be set on the video element like in the example above.

            /- Text control messages -> Create media source
WebSocket -<
            \- Binary blob messages -> Load into media source (buffer)

Clients will automatically reconnect when the WebSocket connection is lost.

Usage

npm install --save @istreamplanet/preview-player.js

Running tests

To run tests, execute the following command:

$ npm test

Reference

Constructor

`PreviewPlayer([video], [url], [preflightMetadata])`

Create a new PreviewPlayer instance. Takes an optional HTML video element, optional playback URL without the protocol and optional data to send to the server when the connection is first opened.

// Get the video element:
const video = document.querySelector('#my-video');
const url = 'host:port/video/id';
const preflightMetadata = {
  identity: 'identity',
  token: 'token'
};

// Create and play back a stream:
let mp = new PreviewPlayer(video, url, preflightMetadata);

// Create but call `play` separately. It is safe to call `play`
// multiple times:
mp = new PreviewPlayer(video, null, preflightMetadata);
mp.play(url, preflightMetadata);

// Or, manage everything yourself if you want:
mp = new PreviewPlayer();
mp.on('source', src => {
  video.src = src;
})
mp.on('buffer-updated', (source, buffer, start, end) => {
  // Seek into the buffer if playback falls behind.
  if (video.currentTime < start) {
    video.currentTime = start
  }
})
mp.on('error', err => {
  console.log(err);
  mp.destroy();
  mp = null;
})
video.addEventListener('canplay', () => {
  video.play();
})

Instance Properties

`preview-player.source`

The MediaSource for the current stream.

`preview-player.buffer`

The SourceBuffer attached to the MediaSource above.

`preview-player.ws`

The WebSocket connection to the server that is used to read control messages and video stream data.

Instance Methods

`previewPlayer.on(name, handler)`

previewPlayer.on('error', err => {
  console.log(`Error playing back! ${err}`);
})

`previewPlayer.play(url, preflightMetadata)`

Start playback of a new video URL (without the protocol).

previewPlayer.play('host:port/video/id', 'token');

`previewPlayer.destroy()`

Destroy and clean up the player. It is not safe to use the instance after destroy has been called.

previewPlayer.destroy();

Events

The following events are available for attaching a listener:

Event	Arguments	Description
`buffer-updated`	`source, buffer, start, end`	The media source buffer has been updated.
`error`	`err`	An error occurred.
`destroyed`	n/a	PreviewPlayer instance has cleaned up and is ready to be garbage collected.
`source`	`source`	A new source is ready and can be attached to an HTML `<video>` element's `src` attribute.
`latencyToSource`	`latencyToSource`	Estimate of the client player's latency to the source being consumed by the transcoder powering the stream.

@infinitebrahmanuniverse/nolb-_is @everything-registry/sub-chunk-473

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago