videojs-hls-boomstream

boomstream.com videojs HLS plugin

Usage no npm install needed!

<script type="module">
  import videojsHlsBoomstream from 'https://cdn.skypack.dev/videojs-hls-boomstream';
</script>

README

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

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

License

MIT. Copyright (c) support@boomstream.com