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 https://www.npmjs.com/package/@100mslive/hls-player as the package source.

npm i @100mslive/hls-player

HMSHLSPlayer methods

Below shows all the methods exposed from player

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:

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:

// 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:

// 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:

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.

hlsPlayer.setVolume(50);

Set video quality level to hls player

/**
*
* @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;
}

Events exposed from HMSHLSPlayer

We are exposing events from our hls player.

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

enum HLSPlaybackState {
  playing,
  paused,
}
interface HMSHLSPlaybackState {
  state: HLSPlaybackState;
}
hlsPlayer.on(HMSHLSPlayerEvents.PLAYBACK_STATE, (event: HMSHLSPlayerEvents, data: HMSHLSPlaybackState): void => {});

HLS Stats

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.

interface HMSHLSManifestLoaded {
  layers: HMSHLSLayer[];
}
hlsPlayer.on(HMSHLSPlayerEvents.MANIFEST_LOADED, (event: HMSHLSPlayerEvents, data: HMSHLSManifestLoaded): void => {});

Quality changed data

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

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.

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

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

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

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.

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);

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);
    }
}, []);