videojs-hls-boomstream

This plugin was developed for integration of videojs player and online video platform Boomstream. Try it and hls delivery will be as easy as one, two, three.

Table of Contents

• Installation
• Usage
  • <script> Tag
  • Browserify ES6
• License

Installation

npm install --save videojs-hls-boomstream

Usage

To include videojs-hls-boomstream on your website or web application, use any of the following methods.

<script> Tag

This is the simplest case. Get the script in whatever way you prefer and include the plugin after you include video.js, so that the videojs global is available.

<script src="//path/to/video.min.js"></script>
<script src="//path/to/videojs-hls-boomstream.min.js"></script>
<script>
  var player = videojs('my-video', /*, <videojs options {}>, <ready callback ()>*/);

  player.boomstreamHls();
  player.src("<bms video source>");
</script>

Browserify ES6

When using with Browserify, install videojs-hls-boomstream via npm and import the plugin as you would any other module.

import videojs from 'video.js';
import * as BoomstreamHlsPlugin from "videojs-hls-boomstream";

...
BoomstreamHlsPlugin.init(videojs);


var player = videojs("my-video" /*, <videojs options {}>, <ready callback ()>*/);
player.boomstreamHls();
player.src("<bms video source>");

Catch errors

player.error() returns the most recent error. you can listen to the error event:

  player.on('error', function() {
    console.log(player.error());
  });

or

import { BMSPluginError, BMSPluginErrorType } from 'videojs-hls-boomstream';

  player.boomstreamHls({
    onerror: (e: BMSPluginError) => {
      switch(e.type) {
        case BMSPluginErrorType.RESPONSE:
          ...
        case BMSPluginErrorType.MEDIA:
          ...
        case BMSPluginErrorType.CONFIG:
          ...
      }
    }
  })

Plugin error structure

const enum BMSPluginErrorType {
  RESPONSE = 'ResponseError',
  MEDIA = 'MediaError',
  CONFIG = 'ConfigParseException'
}

interface BMSPluginError {
  type: BMSPluginErrorType;
  code: number;
  message: string;
  data?: any;
}

Plugin error types

• BMSPluginErrorType.RESPONSE - standart HTTP status codes (200, 300, 400, 500, etc.)

    BMSPluginError {
        code: 404, // response code
        data: { // optional response error data
            ...
        },
        message: "Not found", // response message
        name: "BMSPluginError", // class name
        type: "ResponseError" // error type
    }

• BMSPluginErrorType.MEDIA - bms plugin media errors (code, message):

  • 204, branding_processing

  • 403, branding_geo

  • 403, branding_protection

  • 404, branding_deleted

  • 404, branding_empty_playlist

  • 404, branding_not_found

  • 423, branding_access_expire

  • 423, branding_contacts

  • 423, branding_blocked

  • 423, branding_locked

  • 423, branding_sales_not_allowed

  • 423, branding_zero_balance (The "branding_" prefix in the message appears when the branding option is enabled)

  ---

  • 204, processing

  • 403, geo

  • 403, protection

  • 404, deleted

  • 404, empty_playlist

  • 404, not_found

  • 423, access_expire

  • 423, contacts

  • 423, blocked

  • 423, locked

  • 423, sales_not_allowed

  • 423, zero_balance

  ---

  • 500, application_error
  • 500, application_maintenance

      BMSPluginError {
          code: 403, // error code
          data: { // optional error data
              code: 403,
              message: "protection",
              translate: "Access denied.<br/>Online Videoplatform <a href='https://boomstream.com' target='_blank'>boomstream.com</a>"
          },
          message: "player.403_protection", // localized message for MediaError
          name: "BMSPluginError", // class name
          type: "MediaError" // error type
      }

• BMSPluginErrorType.CONFIG - occurs when config parsing has failed

      BMSPluginError {
          code: 0, // constant
          data: { // optional exception data
              ...
          },
          message: "unknown", // exception message
          name: "BMSPluginError", // class name
          type: "ConfigParseException" // error type
      }

Default skin

To disable boomstream skin, use:

player.boomstreamHls({ disableSkin: true });

Plugins

Quality selection button:

player.boomstreamHls({..., qualityPlugin: {disable: false, displayCurrentQuality: false, placementIndex: 0}});

Custom playlist

videojs-hls-boomstream creates bPlaylist property on player object if you try to play playlist media content. bPlaylist has the following interface:

interface bPlaylist {
  setMediaByIndex(itemIndex: number): void;
  setNextMedia(): void;
  setPreviousMedia(): void;
  enableAutoplay(delay: number): void;
  disableAutoplay(): void;
  getCurrentAutoplayConfig(): AutoplayConfig;
  getCurrentPlaylist(): BMSPlaylistType;
  getCurrentMedia(): BMSPlaylistItem;
}

bPlaylist uses the following types:

type AutoplayConfig = {
  enabled: boolean;
  delay: number;
}

type BMSPlaylistType = [BMSPlaylistItem, ...BMSPlaylistItem[]]

type BMSPlaylistItem = {
  sources: BMSPlaylistItemSources;
  poster: string;
  posters: Poster[];
  duration: number;
  name: string;
}

type Poster = {
  height: number;
  link: string;
  width: number;
}

enum VideoMimeTypesEnum {
  XMPEG = 'application/x-mpegURL',
  VNDAPPLEMPEGURL = 'application/vnd.apple.mpegurl',
  THREEGPG = 'video/3gpp',
  THREEGPG2 = 'video/3gpp2',
  THREEGP2 = 'video/3gp2',
  MPEG = 'video/mpeg',
  MP4 = 'video/mp4',
  OGG = 'video/ogg',
  QUICKTIME = 'video/quicktime',
  WEBM = 'video/webm',
  LIVE = 'live'
}

type VideoMimeTypesList = `${VideoMimeTypesEnum}`;

type BoomstreamLinks = {
  hls: string;
}

type Source = {
  bms: boolean;
  code: string;
  duration: number;
  encoded?: boolean;
  entityCode: string;
  isPublish?: boolean;
  link?: string | null;
  links?: BoomstreamLinks;
  isLive: boolean;
  name: string;
  poster: string;
  posters: Poster[];
  recovery_id: string;
  src: string;
  state: string;
  type: VideoMimeTypesList;
  token?: string;
}

type BoomstreamPlayerTech = videojs.Tech & {
  currentSource_: Source;
  session: null | number;
}

type BMSPlaylistItemSources = [Source, ...Source[]];

Below will be a description of the playlist methods:

• setMediaByIndex(itemIndex: number): void; - allows you to set media from playlist by index. itemIndex can be a finite BigInt or integer number >= 0. If you pass invalid data to this method it will print corresponding error in console and do nothing.
• setNextMedia(): void; - set next media in playlist. If current media was the last in playlist print corresponding warning message.
• setPreviousMedia(): void; - set previous media in playlist. If current media was the first in playlist print corresponding warning message.
• enableAutoplay(delay: number): void; - enable autoplay functional for playlist. If autoplay is enabled and user interacted with DOM, playlist loader automaticaly plays the media in playlist by a row with delay in seconds between playing playlist items. delay must be finite number >= 0. If delay is invalid method will print error message in console and do nothing. Autoplay is disabled by default. If you play current video when autoplay timeout is running timeout will be cleared.
• disableAutoplay(): void; - disables autoplay if it was enabled or do nothing.
• getCurrentAutoplayConfig(): AutoplayConfig; - returns current autoplay config (type is described above).
• getCurrentPlaylist(): BMSPlaylistType; - returns copy of current playlist (type is described above).
• getCurrentMedia(): BMSPlaylistItem; - returns copy of current media (type is described above).

Quality API

videojs-hls-boomstream creates bQuality property on player object if you enable quality plugin in options. bQuality has the following interface:

interface IQualityApi {
  getQualityList: () => UsersQuality[];
  getQualityById: (qualityId: string) => UsersQuality | undefined;
  getSelectedQualityId: () => string;
  setQualityById: (qualityId: string) => void;
}

interface UsersQuality {
  id: string;
  bandwidth: number;
  width?: number;
  height?: number;
  name?: string;
};

This api triggers (player.trigger) 2 types of events:

• qualities_initialized - triggers when quality list has been initialized (once for one media); has UsersQuality[] as a payload
• new_quality_selected - triggers every time a new quality sets by setQualityById method (not triggers when adaptive bitrate algorithm selects new quality when auto quality is setted); has quality id as a payload

Below will be a description of the quality api methods:

• getQualityList: () => UsersQuality[] - returns a list of available qualities for current media
• getQualityById: (qualityId: string) => UsersQuality | undefined - if qualityId isn't string print warning in console and return undefined; returns a quality object if found in quality list otherwise return undefined
• getSelectedQualityId: () => string - if selected quality is auto returns 'auto' otherwise returns quality id
• setQualityById: (qualityId: string) => void - if qualityId isn't string prints error in console and do nothing; if qualityId equals id which has already been selected prints warning in console and do nothing; otherwise set new quality and triggers new_quality_selected event with qualityId payload;

License

MIT. Copyright (c) [email protected]