@brightcove/player-loader
Advanced tools
An asynchronous script loader for the Brightcove Player.
Table of Contents generated with DocToc
Apache-2.0. Copyright (c) Brightcove, Inc.
While this library, Brightcove Player Loader, has an open-source license and is free-to-use, the Brightcove Player is not open-source or free-to-use; it is governed by the proprietary Brightcove Software License and is Copyright (c) Brightcove, Inc.
Similarly, all files in vendor/ do not fall under the Apache-2.0 license. Rather, they are governed by the proprietary Brightcove Software License and are Copyright (c) Brightcove, Inc.
Each Brightcove Player is constructed for our customers and served via our CDN. This works great for most traditional websites where adding an embed code into a template or CMS is straightforward - especially for non-developers!
However, as the web moves toward ES modules and our more technical customers adopt modern build tooling, many users don't want a copy/paste embed code. They want a module they can bundle into their web application without needing to write a lot of integration code to download their players and embed them.
This tool aims to solve that problem by providing our own library that can download any published Brightcove Player and embed it in the DOM.
Currently, this library supports Brightcove Players v6.0.0 and higher.
It may work for v5.x players in some configurations, but this is not a supported use-case.
This library supports common evergreen browsers - Chrome, Firefox, Edge, Safari - and IE11. Earlier versions of IE are not supported.
npm install --save @brightcove/player-loader
To include the Brightcove Player Loader on your website or web application, use any of the following methods.
This is the most modern use-case.
import brightcovePlayerLoader from '@brightcove/player-loader';
brightcovePlayerLoader();
When using with CommonJS or Browserify, install @brightcove/player-loader via npm and require the library as you would any other module:
var brightcovePlayerLoader = require('@brightcove/player-loader');
brightcovePlayerLoader();
NOTE: Use either
dist/brightcove-player-loader.jsordist/brightcove-player-loader.min.js. In either case, the global variablebrightcovePlayerLoaderwill be created.
When using with RequireJS (or another AMD library), get the script in whatever way you prefer and require the library as you normally would:
require(['@brightcove/player-loader'], function(brightcovePlayerLoader) {
brightcovePlayerLoader();
});
<script> TagNOTE: Use either
dist/brightcove-player-loader.jsordist/brightcove-player-loader.min.js. In either case, the global variablebrightcovePlayerLoaderwill be created.
This is the simplest case. Get the script in whatever way you prefer and include it:
<script src="//path/to/@brightcove/brightcove-player-loader.min.js"></script>
<script>
brightcovePlayerLoader();
</script>
Note: If you want to use this with React, we have an official react component called @brightcove/react-player-loader
The Brightcove Player Loader exposes a single function. This function takes an parameters object which describes the player it should load and returns a Promise which resolves when the player is loaded and created and rejects if anything fails.
This is a minimal example, using only the required parameters, which will load a Video Cloud account's default player:
brightcovePlayerLoader({
refNode: someElement,
accountId: '123456789'
});
This is a more complete example, using some optional parameters and handling the returned Promise:
brightcovePlayerLoader({
refNode: someElement,
refNodeInsert: 'replace',
accountId: '123456789',
playerId: 'AbCDeFgHi',
embedId: 'default',
videoId: '987654321'
})
.then(function(success) {
// The player has been created!
})
.catch(function(error) {
// Player creation failed!
});
This library will attempt to detect pre-existing players on the page. In other words, if this library runs after a Brightcove Player script was included earlier in the DOM, it will detect it and prevent additional downloads of the same player. For example:
<div id="player-container"></div>
<script src="https://players.brightcove.net/123456789/default_default/index.min.js"></script>
<script src="path/to/brightcove-player-loader.js"></script>
<script>
// This will create a player in #player-container, but will not download
// the player script a second time!
brightcovePlayerLoader({
refNode: '#player-container',
accountId: '123456789'
});
</script>
However, there is a limitation to this behavior. Players from separate accounts on the same page are not guaranteed to be properly detected. This is considered an unsupported use-case.
When used with the related webpack plugin, you can take advantage of the Player Loader's embed creation capabilities while avoiding an additional, asynchronous request by bundling your Brightcove Player into your webpack bundle.
Simply configure both libraries simultaneously and your player(s) should be bundled and no longer download asynchronously.
By default, this library will look for a global Promise. However, you can explicitly provide a Promise implementation via the Promise parameter:
brightcovePlayerLoader({
refNode: someElement,
accountId: '123456789',
playerId: 'AbCDeFgHi',
Promise: MyCustomPromise
})
.then(function(success) {
// The player has been created!
})
.catch(function(error) {
// Player creation failed!
});
Promises are not required for this library to work, but they are recommended. The only major browser that does not support Promise natively is IE11. We recommend polyfilling the window.Promise constructor if it does not exist.
In cases where no Promise global exists and none is provided, the Brightcove Player Loader will return undefined. There are callbacks available, which can be used instead of Promise - passing them will prevent a Promise from being returned:
brightcovePlayerLoader({
refNode: someElement,
accountId: '123456789',
onSuccess: function(success) {
// The player has been created!
},
onFailure: function(error) {
// Player creation failed!
}
});
NOTE: Providing these callbacks means opting-out of promises entirely. No
Promiseobject will be returned!
For resolved Promises or onSuccess callbacks, a single argument will be passed. This "success object" can have the following properties:
| Property | Description |
|---|---|
type | Either 'in-page' or 'iframe', describing the type of embed that was created. |
ref | The type of value assigned to this property will vary by the type. For 'in-page' embeds, it will be a Video.js Player object and for 'iframe' embeds, it will be the <iframe> DOM element. |
For rejected Promises or onFailure callbacks, a single argument will be passed. This will be a native Error object with a message describing what went wrong.
The Brightcove Player will create global variables and add elements to the DOM. This library exposes a reset() function, which can reset that state. Calling it will have the following effects:
script tags created by this library and clear its internal record of which files have been loaded.bc and videojs properties from the global namespace.brightcovePlayerLoader({
refNode: someElement,
refNodeInsert: 'replace',
accountId: '123456789',
playerId: 'AbCDeFgHi',
embedId: 'default',
videoId: '987654321'
})
.then(function(success) {
/*
At this point:
- at least one video player will be in the DOM.
- at least one script created by this library will be in the DOM.
- window.bc will exist.
- window.videojs will exist.
*/
brightcovePlayerLoader.reset();
/*
At this point:
- no video players will be in the DOM.
- no scripts created by this library will be in the DOM.
- window.bc will not exist.
- window.videojs will not exist.
*/
});
This reset() function can be useful in long-lived web pages, such as in single page applications and similar. It is left to implementers to determine whether or not they need to merely dispose their players or completely reset the Brightcove-provided functions.
The following are all the parameters that can be passed to the Brightcove Player Loader function. Required parameters are marked with an asterisk (*).
Parameters must be passed as an object.
accountId*string | numberA Video Cloud account ID.
adConfigIdstringThe Video Cloud SSAI Ad Config ID to be applied to the generated embed.
applicationIdstringThe application ID to be applied to the generated embed.
catalogSearchstring | ObjectNOTE: Only supported for Brightcove Player versions 6.18.0 and newer.
A Video Cloud Catalog search to perform. This can be a simple string search or a object that matches the Catalog getSearch method.
If a non-string value is given that is not serializable as JSON, this parameter will be ignored.
For example, this:
brightcovePlayerLoader({
// ...
catalogSearch: 'some search term'
});
...or:
brightcovePlayerLoader({
// ...
catalogSearch: {
q: 'some search term',
limit: 10
}
});
catalogSequenceArray | ObjectNOTE: Only supported for Brightcove Player versions 6.18.0 and newer.
A Video Cloud Catalog sequence to perform. See the Catalog getLazySequence method documentation for more.
If a non-string value is given that is not serializable as JSON, this parameter will be ignored.
For example, this:
brightcovePlayerLoader({
// ...
catalogSequence: [{
type: 'search',
id: {
q: 'some search term',
limit: 10
}
}, {
type: 'video',
id: '1234567890'
}, {
type: 'playlist',
id: '0987654321'
}]
});
deliveryConfigIdstringThe Dynamic Delivery Rules Config ID to be applied to the generated embed.
embedIdstring'default'The Brightcove Player embed ID for the player. The default value is correct for most users.
embedOptionsObjectUsed to provide certain options for embed generation. These include:
embedOptions.pipbooleanfalseIf true, will wrap the embed in a <div class="vjs-pip-container"> element. This should be used when you need support for the Brightcove Picture-in-Picture plugin.
embedOptions.playlistboolean | ObjectfalseFor in-page embeds, if true, will add a <div class="vjs-playlist"> element after the embed. This should be used when you need support for the Brightcove Playlist UI plugin.
Also for in-page embeds, our legacy playlist UI plugin used a <ul> element instead of a <div>. You can pass an object with legacy: true here to use a <ul>.
For iframe embeds, this parameter will be ignored.
embedOptions.responsiveboolean | ObjectfalseNOTE: This approach should work for in-page embeds, but it is recommended that you use the Video.js
fluidand/oraspectRatiooptions instead:options: { aspectRatio: '16:9' }
Used customize the embed code to produce a responsively-sized player using the "intrinsic ratio" wrapper approach.
When true, will produce a responsive embed code with a 16:9 aspect ratio that will fill its container.
An object can be provided to customize this with the following sub-properties:
aspectRatio: A string can be used to customize the aspect ratio to a value other than 16:9 (e.g., '4:3' or '16:10'). Any aspect ratio can be used - not just those supported by Video.js.iframeHorizontalPlaylist: For iframe players configured with a horizontal playlist, set to true to adjust the sizing of the responsive wrapper element to accommodate the additional height. This option is ignored for in-page players as they are styled independently from their associated playlist.maxWidth: A string used to restrain the maximum width of the player. This should use CSS units, such as pixels (e.g., '960px').embedOptions.tagNamestring'video-js'Used to customize the embed element's tag name. This parameter's value must be one of:
'video-js' or brightcovePlayerLoader.EMBED_TAG_NAME_VIDEOJS: This value is the default and is supported only by Brightcove Player v6.11.0 and higher.'video' or brightcovePlayerLoader.EMBED_TAG_NAME_VIDEO: This value may be used when support for Brightcove Player versions earlier than v6.11.0.This option is only supported when embedType is 'in-page'; it is ignored when embedType is 'iframe'.
embedOptions.unminifiedbooleanfalseIf true, will use the un-minified version of the player. This can be useful for debugging purposes, but comes at a cost of a larger player download. Not recommended for production!
embedTypestring'in-page'The embed code type to produce. This parameter's value must be one of the following:
'in-page' or brightcovePlayerLoader.EMBED_TYPE_IN_PAGE: Also referred to as the advanced embed code, this injects the player directly into the top-level web page.'iframe' or brightcovePlayerLoader.EMBED_TYPE_IFRAME: Also referred to as the basic embed code, this injects the player as an <iframe> element.onEmbedCreatedFunction(Element)A callback used to customize the embed element (either video-js element or an iframe element) before it is inserted into the DOM or customized as a result of embedOptions and before the player is downloaded and initialized.
The embed element may be mutated or, if this callback returns an element, that element will be used as the embed element.
Potential use-cases are adding/removing attributes or adding child elements, such as sources or tracks.
onFailureFunction(Error)A callback function which allows handling of failures when Promise is not available or not desired. Passing this function will prevent a Promise from being returned.
It gets a single Error object as an argument. The return value of this function is ignored.
onSuccessFunction(Object)A callback function which allows handling of successes when Promise is not available or not desired. Passing this function will prevent a Promise from being returned.
It gets a single "success object" as an argument. The return value of this function is ignored.
optionsObjectA Video.js options object to pass during the player creation process. These options will take precedence over any settings specified in the Brightcove Player configuration.
NOTE: Cannot be used with iframe embeds!
playerUrlstringIf you host the player that you are trying to load yourself, and you don't want to load the player from brightcove, pass the url for the player here.
Note: iframes should resolve to an HTML page and other embeds should point to a JavaScript file.
playerIdstring'default'A Brightcove Player ID.
playlistIdstring | numberA Video Cloud video ID or reference ID.
playlistVideoIdstring | numberA Video Cloud video ID that would be found in the resulting playlist specified by playlistId. This parameter is ignored if playlistId is missing.
posterstringA URL to a poster image to override that returned by the Playback API.
This option is only supported when embedType is 'in-page'; it is ignored when embedType is 'iframe'.
PromiseFunction(Function)window.PromiseUsed to explicitly provide a Promise implementation. If provided, this will be used in lieu of any global Promise.
refNode*Element | stringThe DOM element into which the player will be embedded. If not provided as a DOM element, it can be provided as a string, which will be passed to document.querySelector.
refNodeInsertstring'append'The manner in which the player will be inserted relative to the reference DOM element (specified by refNode). This parameter's value must be one of the following:
'append' or brightcovePlayerLoader.REF_NODE_INSERT_APPEND: The player will be the last child of the reference node.'prepend' or brightcovePlayerLoader.REF_NODE_INSERT_PREPEND: The player will be the first child of the reference node.'before' or brightcovePlayerLoader.REF_NODE_INSERT_BEFORE: The player will be previous sibling of the reference node.'after' or brightcovePlayerLoader.REF_NODE_INSERT_AFTER: The player will be the next sibling after the reference node.'replace' or brightcovePlayerLoader.REF_NODE_INSERT_REPLACE: The reference node will be removed and replaced by the player.videoIdstring | numberA Video Cloud video ID or reference ID.
The library exposes several constants attached to the main library function, brightcovePlayerLoader. Most can be used for parameter values and are mentioned under the relevant headings, but collected here for reference as well:
| Constant | Relevant Parameter |
|---|---|
EMBED_TAG_NAME_VIDEO | embedOptions.tagName |
EMBED_TAG_NAME_VIDEOJS | embedOptions.tagName |
EMBED_TYPE_IN_PAGE | embedType |
EMBED_TYPE_IFRAME | embedType |
REF_NODE_INSERT_APPEND | refNodeInsert |
REF_NODE_INSERT_PREPEND | refNodeInsert |
REF_NODE_INSERT_BEFORE | refNodeInsert |
REF_NODE_INSERT_AFTER | refNodeInsert |
REF_NODE_INSERT_REPLACE | refNodeInsert |
VERSION | n/a |
By default, the base URL used is the Brightcove CDN. However, for some non-production cases and testing, you may want to override the base URL. This can be achieved via a call to the setBaseUrl function:
brightcovePlayerLoader.setBaseUrl('https://localhost:9999/');
FAQs
An asynchronous script loader for the Brightcove Player.
The npm package @brightcove/player-loader receives a total of 62,930 weekly downloads. As such, @brightcove/player-loader popularity was classified as popular.
We found that @brightcove/player-loader demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 146 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.