@100mslive/hls-player 0.3.25-alpha.0 → 0.3.25-alpha.2

package/README.md

@@ -1,17 +1,348 @@
-`@100mslive/hls-player` is currently a wrapper on hls.js with easy to use interface and few add-ons for [100ms's interactive live streaming feature](https://www.100ms.live/docs/javascript/v2/how--to-guides/record-and-live-stream/hls/hls).
+# 100ms HLS Player
 
-Sample usage: 
+[![Lint, Test and Build](https://github.com/100mslive/web-sdks/actions/workflows/lint-test-build.yml/badge.svg)](https://github.com/100mslive/web-sdks/actions/workflows/lint-test-build.yml)
+[![Bundle Size](https://badgen.net/bundlephobia/minzip/@100mslive/hls-player)](https://bundlephobia.com/result?p=@100mslive/hls-player)
+[![License](https://img.shields.io/npm/l/@100mslive/hls-player)](https://www.100ms.live/)
+![Tree shaking](https://badgen.net/bundlephobia/tree-shaking/@100mslive/hls-player)
 
+The `HMSHLSPlayer` is an HLS player offered by 100ms that can be used to play HLS streams. The player takes a URL and video element to play the stream.
+
+## How to integrate HLS Player SDK
+
+You can use Node package manager or yarn to add HMSHLSPlayer sdk to your project.
+Use [@100mslive/hls-player](https://www.npmjs.com/package/@100mslive/hls-player) as the package source.
+
+```bash
+npm i @100mslive/hls-player
+```
+
+## HMSHLSPlayer methods
+
+Below shows all the methods exposed from player
+
+```javascript
+interface IHMSHLSPlayer {
+  /**
+   * @returns get html video element
+   */
+  getVideoElement(): HTMLVideoElement;
+
+  /**
+   * set video volumne
+   * @param { volume } - in range [0,100]
+   */
+  setVolume(volume: number): void;
+  /**
+   *
+   * @returns returns HMSHLSLayer which represents current
+   * quality.
+   */
+  getLayer(): HMSHLSLayer | null;
+  /**
+   *
+   * @param { HMSHLSLayer } layer - layer we want to set the stream to.
+   * set { height: auto } to set the layer to auto
+   */
+  setLayer(layer: HMSHLSLayer): void;
+  /**
+   * move the video to Live
+   */
+  seekToLivePosition(): Promise<void>;
+  /**
+   * play stream
+   * call this when autoplay error is received
+   */
+  play(): Promise<void>;
+  /**
+   * pause stream
+   */
+  pause(): void;
+
+  /**
+   * It will update the video element current time
+   * @param seekValue Pass currentTime in second
+   */
+  seekTo(seekValue: number): void;
+}
+```
+
+### How to use Player's HLS Stream
+
+You create an instance of HMSHLSPlayer like below:
+
+```javascript
+import { HMSHLSPlayer } from '@100mslive/hls-player';
+
+// hls url should be provided which player will run.
+// second parameter is optional, if you had video element then pass to player else we will create one.
+const hlsPlayer = new HMSHLSPlayer(hlsURL, videoEl)
+
+// if video element is not present, we will create a new video element which can be attached to your ui.
+const videoEl = hlsPlayer.getVideoElement();
+```
+
+### How to pause and resume the playback
+
+You call play/pause on the hlsPlayer instance like below:
+
+```javascript
+// return Promise<void>
+hmsPlayer.play()
+
+hmsPlayer.pause()
+```
+
+### How to seek forward or backward
+
+You use `seekTo` methods on the hlsPlayer to seek to any position in video, below is given example:
+
+```javascript
+// seekValue Pass currentTime in second
+hmsPlayer.seekTo(5)
+```
+
+### How to seek to live position
+
+You use `seekToLivePosition` methods on the hlsPlayer instance to go to the live poition like below:
+
+```javascript
+hmsPlayer.seekToLivePosition()
+```
+
+### How to change volume of HLS playback
+
+Use volume property to change the volume of HLS player. The volume level is between 0-100. Volume is set to 100 by default.
+
+```javascript
+hlsPlayer.setVolume(50);
 ```
-import {
-  HLSPlaybackState,
-} from "@100mslive/hls-player";
 
-// hlsUrl is the url in which the hls stream is ongoing
-// videoElement is the video element where you want to play the stream
-const player = new HMSHLSPlayer(hlsUrl, videoElement);
-player.play()
+### Set video quality level to hls player
 
+```javascript
+/**
+*
+* @returns returns HMSHLSLayer which represents current
+* quality.
+*/
+hlsPlayer.getLayer(): HMSHLSLayer | null;
+/**
+*
+* @param { HMSHLSLayer } layer - layer we want to set the stream to.
+* set { height: auto } to set the layer to auto
+*/
+hlsPlayer.setLayer(layer: HMSHLSLayer): void;
+
+// quality interface
+interface HMSHLSLayer {
+  readonly bitrate: number;
+  readonly height?: number;
+  readonly id?: number;
+  readonly width?: number;
+  url: string;
+  resolution?: string;
+}
 ```
 
-More details to be added soon.
+## Events exposed from HMSHLSPlayer
+
+We are exposing events from our hls player.
+
+```javascript
+enum HMSHLSPlayerEvents {
+  TIMED_METADATA_LOADED = 'timed-metadata',
+  SEEK_POS_BEHIND_LIVE_EDGE = 'seek-pos-behind-live-edge',
+
+  CURRENT_TIME = 'current-time',
+  AUTOPLAY_BLOCKED = 'autoplay-blocked',
+
+  MANIFEST_LOADED = 'manifest-loaded',
+  LAYER_UPDATED = 'layer-updated',
+
+  ERROR = 'error',
+  PLAYBACK_STATE = 'playback-state',
+  STATS = 'stats',
+}
+```
+
+### Playback state
+
+```javascript
+enum HLSPlaybackState {
+  playing,
+  paused,
+}
+interface HMSHLSPlaybackState {
+  state: HLSPlaybackState;
+}
+hlsPlayer.on(HMSHLSPlayerEvents.PLAYBACK_STATE, (event: HMSHLSPlayerEvents, data: HMSHLSPlaybackState): void => {});
+```
+
+### HLS Stats
+
+```javascript
+interface HlsPlayerStats {
+    /** Estimated bandwidth in bits/sec. Could be used to show connection speed. */
+    bandwidthEstimate?: number;
+    /** The bitrate of the current level that is playing. Given in bits/sec */
+    bitrate?: number;
+    /** the amount of video available in forward buffer. Given in ms */
+    bufferedDuration?: number;
+    /** how far is the current playback from live edge.*/
+    distanceFromLive?: number;
+    /** total Frames dropped since started watching the stream. */
+    droppedFrames?: number;
+    /** the m3u8 url of the current level that is being played */
+    url?: string;
+    /** the resolution of the level of the video that is being played */
+    videoSize?: {
+        height: number;
+        width: number;
+    };
+}
+
+hlsPlayer.on(HMSHLSPlayerEvents.STATS, (event: HMSHLSPlayerEvents, data: HlsPlayerStats): void => {});
+```
+
+### Manifest loaded data
+
+Hls player will provide a manifest which will provide a data like different quality layer once url is loaded.
+
+```javascript
+interface HMSHLSManifestLoaded {
+  layers: HMSHLSLayer[];
+}
+hlsPlayer.on(HMSHLSPlayerEvents.MANIFEST_LOADED, (event: HMSHLSPlayerEvents, data: HMSHLSManifestLoaded): void => {});
+```
+
+### Quality changed data
+
+```javascript
+interface HMSHLSLayerUpdated {
+  layer: HMSHLSLayer;
+}
+hlsPlayer.on(HMSHLSPlayerEvents.LAYER_UPDATED, (event: HMSHLSPlayerEvents, data: HMSHLSLayerUpdated): void => {});
+```
+
+### Live Event
+
+Player will let you know if player is plaaying video live or not
+
+```javascript
+interface HMSHLSStreamLive {
+  isLive: boolean;
+}
+hlsPlayer.on(HMSHLSPlayerEvents.SEEK_POS_BEHIND_LIVE_EDGE, (event: HMSHLSPlayerEvents, data: HMSHLSStreamLive): void => {});
+```
+
+### HLS timed-metadata
+
+HLS player will parse and send the timed-metadata.
+
+```javascript
+interface HMSHLSCue {
+  id?: string;
+  payload: string;
+  duration: number;
+  startDate: Date;
+  endDate?: Date;
+}
+hlsPlayer.on(HMSHLSPlayerEvents.TIMED_METADATA_LOADED, (event: HMSHLSPlayerEvents, data: HMSHLSCue): void => {});
+```
+
+### Error handling
+
+```javascript
+interface HMSHLSException {
+  name: string,
+   message: string,
+  description: string,
+  isTerminal: boolean, // decide if player error will automatically restart(if false)
+}
+hlsPlayer.on(HMSHLSPlayerEvents.ERROR, (event: HMSHLSPlayerEvents, data: HMSHLSException): void => {});
+hlsPlayer.on(HMSHLSPlayerEvents.AUTOPLAY_BLOCKED, (event: HMSHLSPlayerEvents, data: HMSHLSException): void => {});
+```
+
+### Video current time
+
+```javascript
+hlsPlayer.on(HMSHLSPlayerEvents.CURRENT_TIME, (event: HMSHLSPlayerEvents, data: number): void => {});
+```
+
+### Example for events usage
+
+Below are the simple example of how to use hls player's event
+
+```javascript
+const isPlaying = false;
+const playbackEventHandler = data => isPlaying = data.state === HLSPlaybackState.paused;
+hlsPlayer.on(HMSHLSPlayerEvents.PLAYBACK_STATE, playbackEventHandler);
+```
+
+## HLS Player example
+
+Below is a simple example in which hls-player will be used in your app.
+
+```javascript
+// Vanilla JavaScript Example
+import { HLSPlaybackState, HMSHLSPlayer, HMSHLSPlayerEvents } from "@100mslive/hls-player";
+
+const videoEl; // reference for video element
+const hlsUrl; // reference to hls url
+
+// variable to handle ui and take some actions
+let isLive = true, isPaused = false, isAutoBlockedPaused = false;
+
+const handleError = data => console.error("[HLSView] error in hls", data);
+const handleNoLongerLive = ({ isLive }) => isLive = isLive;
+
+const playbackEventHandler = data => isPaused = (data.state === HLSPlaybackState.paused);
+
+const handleAutoplayBlock = data => isAutoBlockedPaused = !!data;
+
+const hlsPlayer = new HMSHLSPlayer(hlsUrl, videoEl);
+
+hlsPlayer.on(HMSHLSPlayerEvents.SEEK_POS_BEHIND_LIVE_EDGE, handleNoLongerLive);
+hlsPlayer.on(HMSHLSPlayerEvents.ERROR, handleError);
+hlsPlayer.on(HMSHLSPlayerEvents.PLAYBACK_STATE, playbackEventHandler);
+hlsPlayer.on(HMSHLSPlayerEvents.AUTOPLAY_BLOCKED, handleAutoplayBlock);
+```
+
+```jsx
+// React Example
+import { HLSPlaybackState, HMSHLSPlayer, HMSHLSPlayerEvents } from "@100mslive/hls-player";
+import { useEffect, useState } from 'react';
+
+const videoEl; // reference for video element
+const hlsUrl; // reference to hls url
+
+// variable to handle ui and take some actions
+const [isVideoLive, setIsVideoLive] = useState(true);
+const [isHlsAutoplayBlocked, setIsHlsAutoplayBlocked] = useState(false);
+const [isPaused, setIsPaused] = useState(false);
+
+useEffect(() => {
+    const handleError = data => console.error("[HLSView] error in hls", data);
+    const handleNoLongerLive = ({ isLive }) => {
+        setIsVideoLive(isLive);
+    };
+
+    const playbackEventHandler = data =>
+        setIsPaused(data.state === HLSPlaybackState.paused);
+
+    const handleAutoplayBlock = data => setIsHlsAutoplayBlocked(!!data);
+    const hlsPlayer = new HMSHLSPlayer(hlsUrl, videoEl);
+
+    hlsPlayer.on(HMSHLSPlayerEvents.SEEK_POS_BEHIND_LIVE_EDGE, handleNoLongerLive);
+    hlsPlayer.on(HMSHLSPlayerEvents.ERROR, handleError);
+    hlsPlayer.on(HMSHLSPlayerEvents.PLAYBACK_STATE, playbackEventHandler);
+    hlsPlayer.on(HMSHLSPlayerEvents.AUTOPLAY_BLOCKED, handleAutoplayBlock);
+    return () => {
+        hlsPlayer.off(HMSHLSPlayerEvents.SEEK_POS_BEHIND_LIVE_EDGE, handleNoLongerLive);
+        hlsPlayer.off(HMSHLSPlayerEvents.ERROR, handleError);
+        hlsPlayer.off(HMSHLSPlayerEvents.PLAYBACK_STATE, playbackEventHandler);
+        hlsPlayer.off(HMSHLSPlayerEvents.AUTOPLAY_BLOCKED, handleAutoplayBlock);
+    }
+}, []);
+
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@100mslive/hls-player",
-  "version": "0.3.25-alpha.0",
+  "version": "0.3.25-alpha.2",
   "description": "HLS client library which uses HTML5 Video element and Media Source Extension for playback",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",
@@ -36,9 +36,17 @@
   "author": "100ms",
   "license": "MIT",
   "dependencies": {
-    "@100mslive/hls-stats": "0.4.25-alpha.0",
+    "@100mslive/hls-stats": "0.4.25-alpha.2",
     "eventemitter2": "^6.4.9",
     "hls.js": "1.4.12"
   },
-  "gitHead": "b9a15a40498feb37cf34dc6fab790cb9dcfcd775"
+  "keywords": [
+    "hls",
+    "video",
+    "player",
+    "webrtc",
+    "conferencing",
+    "100ms"
+  ],
+  "gitHead": "d4e908bd663f765d36f4b2203584613ab72b2e7f"
 }