openplayerjs
Advanced tools
This awesome player mimics the HTML5 video/audio methods/events/properties, and integrates the most popular libraries to play different types of native media, such as MP4/MP3, HLS and M(PEG)-DASH.
It also has the ability to play VMAP, VAST and VPAID Ads in an effortless way!
20kb when gzipped.autoplay capabilities.fill mode is also included to scale and crop media relative to its parent container.crossorigin attribute.These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
The dist folder contains the files you will need yo use this awesome library. To obtain it, you can download the repository from https://github.com/openplayerjs/openplayerjs.git or use NPM to get it:
npm install openplayerjs
CDN is also available for better performance. See next section for more details.
Include OpenPlayer's stylesheet inside the <head> tag, and the script at the bottom of the <body> tag (both of them located in the dist folder). The bundles will contain both minified and uncompressed files, so use the one that fits the best your needs.
Since this player uses HTML5 markup, all the attributes for video/audio tags are available. The only 3 requirements to invoke the player are:
controls and playsinline attributes to provide cross-browser support.op-player op-player__media class names to invoke the player.That's it!
<html>
<head>
<link rel="stylesheet" href="/path/to/openplayer.css">
</head>
<body>
<video class="op-player op-player__media" controls playsinline>
<source src="/path/to/video.mp4" type="video/mp4">
</video>
<script src="/path/to/openplayer.js"></script>
</body>
</html>
We encourage to use CDN for major performance. To do it, in the snippet above, replace /path/to/openplayer.css and /path/to/openplayer.js with https://cdn.jsdelivr.net/npm/openplayerjs@[version]/dist/openplayer.min.css and https://cdn.jsdelivr.net/npm/openplayerjs@[version]/dist/openplayer.min.js.
NOTE: As stated at jsDeliver website, it is recommended to use a [version] number in the URL rather than @latest for production.
If you are planning to use OpenPlayer in a Node project, you can:
// Using as module
var openplayer = require('/path/to/openplayerjs');
// or importing the library (ES6)
import OpenPlayer from 'openplayerjs';
OpenPlayer supports the use of VTT closed captions by adding the track tag as indicated in the following snippet; you can also use the default attribute in the tag, but as a rule of thumb, all the attributes displayed below in the track tag MUST be there; otherwise, closed captions won't be displayed:
<html>
<head>
<link rel="stylesheet" href="/path/to/openplayer.css">
</head>
<body>
<video class="op-player op-player__media" controls playsinline>
<source src="/path/to/video.mp4" type="video/mp4">
<track kind="subtitles" src="/path/to/video.vtt" srclang="en" label="English">
</video>
<script src="/path/to/openplayer.js"></script>
</body>
</html>
Sometimes you need more flexibility instantiating the player (for example, adding cache busting to the VAST/VPAID URL, or even having a list of Ads URLs). So for that case, remove the op-player class from the video/audio tag (just leave op-player__media to preserve styles), and in Javascript use the following snippet:
var player = new OpenPlayer('[player ID]', [valid VAST/VPAID URL|List of VAST/VPAID URLs], [`true|false` for fullscreen effect by default], {
// Controls configuration by default; `levels` can be added as well since it's an optional feature;
// Each one of the items will have in their class name the `op-control__[left|middle|right]` according
// to the controls' structure listed below
controls: {
left: ['play', 'time', 'volume'],
middle: ['progress'],
right: ['captions', 'settings', 'fullscreen'],
},
// Allow items to be contained in a different space outside of `Settings`
detachMenus,
// Number of ms that takes the player to hide the Play button once it starts playing (video only)
// (bt default, `350`)
hidePlayBtnTimer,
// Number of seconds to rewind/forward media
// (by default, player will rewind/forward 5% of the total duration of media)
step,
// Initial volume of media in decimal numbers (by default, `1`)
startVolume,
// Initial play time of media in seconds (by default, `0`)
startTime,
// Allow loader to be displayed when loading video (by default, `false`)
showLoaderOnInit,
// Callback to be executed once an error is found (default, `console.error`)
// Params passed: Custom event with `detail: { type: 'HTML5|Ads|M(PEG)-DASH|HLS', message, data },`
onError,
ads: {
// Custom path/URL to IMA SDK
url,
// If set to `true`, load `ima3_debug.js` file for debugging purposes
debug
},
hls: {
// all HLS options available at https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning.
},
dash: {
// Possible values are SW_SECURE_CRYPTO, SW_SECURE_DECODE, HW_SECURE_CRYPTO, HW_SECURE_CRYPTO,
// HW_SECURE_DECODE, HW_SECURE_ALL
robustnessLevel,
// object containing property names corresponding to key system name strings (e.g. "org.w3.clearkey") and
// associated values being instances of ProtectionData
// (http://vm2.dashif.org/dash.js/docs/jsdocs/MediaPlayer.vo.protection.ProtectionData.html)
drm
},
});
// Don't forget to start the player
player.init();
NOTE: Only caveat here is that the video/audio tags need an ID ahead of time.
If you need more control over the player, OpenPlayer stores instances of each player in the document. To have access to a specific instance, use video/audio's id and use OpenPlayer.instances element.
NOTE: if an id attribute is not detected, OpenPlayer will autogenerate one.
// Selects the first video/audio that uses OpenPlayer
var id = document.querySelector('.op-player').id;
var player = OpenPlayer.instances[id];
The methods supported by the OpenPlayer instance are:
| Method | Description |
|---|---|
play | Play media. If Ads are detected, different methods than the native ones are triggered with this operation. |
pause | Pause media. If Ads are detected, different methods than the native ones are triggered with this operation. |
load | Load media. HLS and M(PEG)-DASH perform more operations during loading if browser does not support them natively. |
addCaptions | Append a new <track> tag to the video/audio tag and dispatch event so it gets registered/loaded in the player, via controlschanged event. |
addControl | Append a new button to the video/audio tag with the possibility dispatch a custom callback so it gets registered/loaded in the player, via controlschanged event. It requires an object with icon URL/path, title for the button, the position (right or left) of the button and a click callback to dispatch an action. |
destroy | Destroy OpenMedia Player instance (including all events associated) and return the video/audio tag to its original state. |
getAd | Retrieve an instance of the Ads object. |
getMedia | Retrieve an instance of the Media object. |
activeElement | Retrieve the current media object (could be Ads or any other media type). |
getContainer | Retrieve the parent element (with op-player class) of the native video/audio tag. |
getControls | Retrieve an instance of the controls object used in the player instance. |
getElement | Retrieve the original video/audio tag. |
getEvents | Retrieve the events attached to the player. |
init | Create all the markup and events needed for the player. |
isAd | Check if current media is an instance of an Ad. |
isMedia | Check if current media is an instance of a native media type. |
id | Retrieve current player's unique identifier. |
src | Retrieve/set the current Source list associated with the player. |
Since OpenPlayer is based on HTML5 media, the way to trigger events is using the video/audio tag.
Using the code above, you can attach/dispatch any valid event, using CustomEvent, like this:
player.getElement().addEventListener('ended', function() {
console.log('Your code when media ends playing');
});
var event = new CustomEvent('ended');
player.getElement().dispatchEvent(event);
All HTML5 media events are supported by OpenPlayer, and it incorporates some custom ones, mostly related to Ads:
| Event | Description |
|---|---|
controlshidden | Event executed when controls timer stops and hides control bar (video only). |
controlschanged | Event triggered when an element modified the state of the controls and they regenerate (i.e., adding new caption). |
captionschanged | Event triggered when user changes the current caption by selecting a new one from the Settings menu. |
playererror | Event executed when any error has occurred within the OpenPlayer instance; a response will be sent via onError config callback. See Usage with Javascript for more details. |
playerdestroyed | Event executed when an instance of OpenPlayer is destroyed (useful to remove extra elements created with the player's help). |
adsloaded | Event when Ads have been loaded successfully and can be played. |
adsstart | Event when Ads start being played. |
adsfirstquartile | Event triggered when Ad reached the first quarter of its length. |
adsmidpoint | Event triggered when Ad reached half of its length. |
adsthirdquartile | Event triggered when Ad reached the third quarter of its length. |
adscomplete | Event triggered when Ad reached the end of its length. |
adsskipped | Event triggered when user skips the Ad. |
adsvolumeChange | Event triggered when user increases/decreases the volume of Ad. |
adsallAdsCompleted | Event triggered when all Ads have been played. |
adsmediaended | Event executed when an Ad is going to be played after media has ended playing (currently used to change the Replay icon to Pause when playing a postroll Ad). |
In addition to the list above, HLS events and HLS error events are being supported by OpenPlayer, including all their details. For the error ones, they are classified as networkError, mediaError, muxError and otherError.
Witness the power of this player by browser the best examples!
If you want to suggest one, please submit an issue indicating what scenarios could OpenPlayerJS help you with.
LevelsMake sure you check Conventional Commits Standards for commit guidelines.
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details.
FAQs
HTML5 video and audio player
The npm package openplayerjs receives a total of 2,925 weekly downloads. As such, openplayerjs popularity was classified as popular.
We found that openplayerjs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 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
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.