https://github.com/openplayerjs/openplayerjs
Lightweight HTML5 video/audio player with smooth controls and ability to play VAST/VPAID/VMAP ads
https://github.com/openplayerjs/openplayerjs
audio dash hls html5 html5-audio html5-video html5-video-player javascript openplayerjs player typescript vast video
Last synced: 22 days ago
JSON representation
Lightweight HTML5 video/audio player with smooth controls and ability to play VAST/VPAID/VMAP ads
- Host: GitHub
- URL: https://github.com/openplayerjs/openplayerjs
- Owner: openplayerjs
- License: mit
- Created: 2018-09-03T17:41:25.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-03-03T22:37:59.000Z (26 days ago)
- Last Synced: 2026-03-04T03:43:09.166Z (26 days ago)
- Topics: audio, dash, hls, html5, html5-audio, html5-video, html5-video-player, javascript, openplayerjs, player, typescript, vast, video
- Language: TypeScript
- Homepage: https://www.openplayerjs.com
- Size: 16.2 MB
- Stars: 621
- Watchers: 10
- Forks: 89
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-video - openplayerjs - Lightweight HTML5 video/audio player with smooth controls and ability to play VAST/VPAID/VMAP ads. (Players)
README
# [OpenPlayer.js](https://www.openplayerjs.com)
[](https://coveralls.io/github/openplayerjs/openplayerjs?branch=master)
[](https://www.jsdelivr.com/package/npm/openplayerjs)
# OpenPlayerJS — modular, plugin-first, easier to extend
This is a media player that uses all the goods of HTML5 video/audio elements to play the most popular media in MP4/MP3, HLS and also has the ability to play VMAP / VAST / non linear / companion ads
> **🎉🎉🎉 OpenPlayerJS v3 is finally here!! 🎉🎉🎉**
>
> `v3` is a radical internal rebuild that keeps most of the player familiar to use, but makes it **much easier to extend** (controls, plugins, engines) and **much easier to maintain**.
>
> ✅ If you use **UMD/CDN** today, you can keep the classic `new OpenPlayerJS('id', options); player.init();` flow with some minor changes — see [**UMD compatibility** section](#-umd-compatibility-the-v2-way-still-works) below.
---
## ✨ What’s new in v3
- 🧩 **Modular packages** (install only what you need)
- 🔌 **Plugin-first architecture** (UI, Ads, Engines are plugins)
- 🎛️ **Imperative UI extensions** (`addElement`, `addControl` via `extendControls`)
- 🧱 Cleaner separation of concerns (core vs UI vs engines/plugins)
- 🔥 Ads are **no longer using Google IMA SDK**: we have built our own with the support using Dailymotion's open source libraries. This was to support ads all around the world and avoid geoblocking
---
## ❌ Breaking Changes
- ❌ **M(PEG)-DASH / FLV support dropped** in favor of just supporting what browsers natively supports; if there is a need for them in the future, they can be added as separate bundles (like the [hls one](./packages/hls/README.md)).
- ❌ Core **quality/levels support dropped**: API (`levels`, `level`) — quality is now engine-specific, and will require to be built inside each one of them.
- ❌ Several v2 "mega-config" options (moved to the right package: UI vs engine vs plugin); this approach can work when using UMD files, depending on what plugins are enabled.
> To learn more about these changes, read **[MIGRATION.v3.md](./MIGRATION.v3.md)**
---
## 📦 Packages
| Package | Purpose | Docs |
| -------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| `@openplayer/core` | Player lifecycle, plugin system, engines, events | [packages/core/README.md](./packages/core/README.md) |
| `@openplayer/player` | Default UI + built-in controls + UI extension APIs | [packages/player/README.md](./packages/player/README.md) |
| `@openplayer/hls` | HLS engine (powered by [`hls.js`](https://github.com/video-dev/hls.js)) | [packages/hls/README.md](./packages/hls/README.md) |
| `@openplayer/ads` | VAST/VMAP/non-linear/companion ads plugin + extension APIs | [packages/ads/README.md](./packages/ads/README.md) |
---
## How to use it?
### Verify Cross-Origin Resource Sharing (CORS)
When ads, captions, or streaming manifests are loaded from a different domain, the server must allow cross-origin requests. The typical error message looks like:
```
Access to fetch at 'https://cdn.example.com/video.m3u8' from origin 'https://myapp.com'
has been blocked by CORS policy.
```
To fix this on your server, add the following response headers:
```
Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Credentials: true
```
Or, for public assets, allow all origins:
```
Access-Control-Allow-Origin: *
```
---
### HTML setup
All you need in your markup is a standard `` or `` element with a `src` attached to it. Add the `controls` and `playsinline` attributes for cross-browser compatibility, and optionally include `` and `` children:
```html
```
> The `op-player__media` class applies the base player styles. The player's wrapper and controls are injected into the DOM automatically when `init()` is called.
#### Bandwidth optimization
To avoid downloading media before the user presses play, set `preload="none"` on the media element:
```html
```
> **Side effect:** With `preload="none"` the player cannot read the media's duration until playback starts. Provide the `duration` option if you want the UI to show the correct total time before the user presses play:
>
> ```ts
> new Core(media, { duration: 315 }); // 5 min 15 s or Infinity for live streamings
> ```
---
### JavaScript / TypeScript (ESM — recommended)
Install the packages you need:
```bash
# Core + UI (covers MP4, MP3, OGG, and any other natively-supported format)
npm install @openplayer/core @openplayer/player
# Add HLS support (powered by hls.js)
npm install @openplayer/hls hls.js
# Add ads support (VAST / VMAP)
npm install @openplayer/ads
```
Then wire everything up:
```ts
import { Core } from '@openplayer/core';
import { createUI, buildControls } from '@openplayer/player';
import '@openplayer/player/style.css';
const media = document.querySelector('#player')!;
const player = new Core(media, {
startTime: 0,
startVolume: 1,
startPlaybackRate: 1,
});
const controls = buildControls({
controls: {
top: ['progress'],
'center-left': ['play', 'duration', 'volume'],
'center-right': ['captions', 'fullscreen', 'settings'],
},
});
createUI(player, media, controls);
```
---
### 🌍 UMD compatibility (the “v2 way” still works)
If you prefer loading scripts from a CDN without a build step:
```html
const player = new OpenPlayerJS('player', {
startTime: 0,
startVolume: 1,
controls: {
top: ['progress'],
'center-left': ['play', 'duration', 'volume'],
'center-right': ['captions', 'fullscreen', 'settings'],
},
});
player.init();
```
---
## 📚 Legacy docs & changelog
- Old changelog: **[CHANGELOG.old.md](./CHANGELOG.old.md)**
- Legacy docs folder (v2 style): **[docs/](https://github.com/openplayerjs/openplayerjs/tree/v2.14.12/docs)**
---
## Built With
- [Typescript](https://www.typescriptlang.org/docs/home.html) - The Javascript for Pros.
## Authors
- **Rafael Miranda** - [rafa8626](https://github.com/rafa8626)
See also the list of [contributors](https://github.com/openplayerjs/openplayerjs/contributors) who participated in this project.
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
This project is licensed under the MIT License - see [LICENSE.md](LICENSE.md) for details.