@istreamplanet/preview-player 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.initWithPreviewStreamsData(previewStreamsData)`

Initialize the PreviewPlayer with the given previewStreamsData.

previewPlayer.initWithPreviewStreamsData(JSON.parse(`
{
  "audio_tracks": [
    {
      "bitrate": <string>,
      "codec_string": <string>,
      "id": <int>,
      "num_channels": <int>,
      "sample_rate": <int>
    }
  ],
  "default_audio_track": {
    "bitrate": <string>,
    "codec_string": <string>,
    "id": <int>,
    "num_channels": <int>,
    "sample_rate": <int>
  },
  "default_url": "https://example.net/v1/<cluster>/org/<orgName>/ext_id/<channelExtId>/play?vid_id=<int>&aud_id=<int>",
  "default_video_track": {
    "bitrate": <int>,
    "codec_string": <string>,
    "frame_rate": <float>,
    "height": <int>,
    "id": <int>,
    "width": <int>
  },
  "token": <string>,
  "video_tracks": [
    {
      "bitrate": <int>,
      "codec_string": <string>,
      "frame_rate": <float>,
      "height": <int>,
      "id": <int>,
      "width": <int>
    }
  ]
}
`))

`previewPlayer.destroyPreviewStreamsData()`

Destroy the data in the player set by the previously given previewStreamsData.

previewPlayer.destroyPreviewStreamsData()

`previewPlayer.onRecoverable(function() { return <previewStreamsData> })`

When a recoverable event occurs, calls the provided function to get the new previewStreamsData. Will backoff if the function encounters any errors and attempt again up until a maximum retry. If the maxRetry passed in is equivalent to zero, then the player will attempt to recover with backoff until success.

preview.Player.onRecoverable(function() {
  // Makes a call to the edgestream service to retrieve new previewStreamsData.
  return previewStreamsData
}, 5)

`previewPlayer.getPlayableVideoTracks()`

Returns the video tracks that are playable by the current browser the video is embedded in.

let videoTracks = previewPlayer.getPlayableVideoTracks()

`previewPlayer.getPlayableAudioTracks()`

Returns the audio tracks that are playable by the current browser the video is embedded in.

let audioTracks = previewPlayer.getPlayableAudioTracks()

`previewPlayer.getVideoTracks()`

Returns all the video tracks that are part of the passed in previewStreamsData.

let videoTracks = previewPlayer.getVideoTracks()

`previewPlayer.getAudioTracks()`

Returns all the audio tracks that are part of the passed in previewStreamsData.

let audioTracks = previewPlayer.getAudioTracks()

`previewPlayer.getCurrentVideoTrack()`

Returns the current video tracks that is being played by the player.

let videoTrack = previewPlayer.getCurrentVideoTrack()

`previewPlayer.getCurrentAudioTrack()`

Returns the current audio tracks that is being played by the player.

let audioTrack = previewPlayer.getCurrentAudioTrack()

`previewPlayer.on(name, handler)`

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

`previewPlayer.playTracks(videoTrackId, audioTrackId)`

Start playback of a new video URL with the given video and audio track ids.

previewPlayer.playTracks(1, 2);

`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
`bufferUpdated`	`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.
`unrecoverable`	`[ERR_VIDEO_AUDIO_TRACK_MISSING, ERR_URL_MISSING, ERR_TOKEN_MISSING]`	Unable to play the stream. Error message provided to add clarity as to why it cannot be played.
`recoverable`	`[ERR_AUTHENTICATION_FAILED]`	Unable to play the stream but can be recovered utilizing the onRecoverable method.

async-mutex url

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

2 years ago

2 years ago

2 years ago

2 years ago