videojs-hls-boomstream 1.2.99 → 1.3.0-alpha.1

package/README.md

@@ -1,321 +1,321 @@
-# videojs-hls-boomstream
-
-This plugin was developed for integration of videojs player and online video platform [Boomstream]( https://boomstream.com/ "Boomstream").
-Try it and hls delivery will be as easy as one, two, three.
-
-## Table of Contents
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-
-- [Installation](#installation)
-- [Usage](#usage)
-  - [`<script>` Tag](#script-tag)
-  - [Browserify ES6](#browserify-es6)
-- [License](#license)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-## Installation
-
-```sh
-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][videojs], so that the `videojs` global is available.
-
-```html
-<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.
-
-```js
-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:
-
-```js
-  player.on('error', function() {
-    console.log(player.error());
-  });
-```
-or 
-```js
-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
-```js
-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.)
-      ```js
-        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
-
-    ```js
-        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
-    ```js
-        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:
-```js
-player.boomstreamHls({ disableSkin: true });
-```
-
-## Plugins
-Quality selection button:
-```js
-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:
-```ts
-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:
-```ts
-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:
-```ts
-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) support@boomstream.com
-
-[videojs]: http://videojs.com/
+# videojs-hls-boomstream
+
+This plugin was developed for integration of videojs player and online video platform [Boomstream]( https://boomstream.com/ "Boomstream").
+Try it and hls delivery will be as easy as one, two, three.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [`<script>` Tag](#script-tag)
+  - [Browserify ES6](#browserify-es6)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+## Installation
+
+```sh
+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][videojs], so that the `videojs` global is available.
+
+```html
+<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.
+
+```js
+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:
+
+```js
+  player.on('error', function() {
+    console.log(player.error());
+  });
+```
+or 
+```js
+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
+```js
+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.)
+      ```js
+        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
+
+    ```js
+        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
+    ```js
+        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:
+```js
+player.boomstreamHls({ disableSkin: true });
+```
+
+## Plugins
+Quality selection button:
+```js
+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:
+```ts
+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:
+```ts
+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:
+```ts
+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) support@boomstream.com
+
+[videojs]: http://videojs.com/