Instanciation
Returned by the call to oberplayer(), a player instance is structured as follows:
{
setup: Function,
load: Function,
destroy: Function,
api: Object,
eventsList: Object
}
Data Setup
An quick and easy way to instantiate a player is to use the oberplayeroptions data attribute on your player container div. The option object can be used as follows:
<div id="player_container_intro"
data-oberplayeroptions='{"playlist":[{"videoUrl": "https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4"}]}'>
</div>
Result
Function reference
oberplayer()
Description
This function is used for:
- retrieving a player instance for a given DOM element
- creating a player instance for a given DOM element if it doesn't already exist
Parameters
| Parameters | Description |
|---|---|
| DOM element | See configuration reference for more details |
Return value
| Description |
|---|
| player instance object |
If no argument is provided to the function, oberplayer() will return the first player instance found on the page.
See the Getting Started section for some examples.
async setup()
Description
This function is used for :
- setting up the optional player token (to activate premium features)
- loading one or more video playlist item(s).
Parameters
| Parameters | Description |
|---|---|
| player configuration object | See configuration reference for more details |
Return value
| Description | Type |
|---|---|
| player instance as Promise's resulting value | Promise |
load()
Description
This function loads a single video playlist item. For example, this function is useful if you want to load another video after the one loaded with the setup() function.
Parameters
| Parameters | Description |
|---|---|
| playlist item object | See configuration reference for more details |
Return value
| Description | Type |
|---|---|
| player instance as Promise's resulting value | Promise |
destroy()
Description
This function destroys a player instance.
Destroy method will remove all DOM elements and event listeners related to the player instance. If the goal is to load a new video, you should use the load() method instead.
Can be useful in some cases (for a single-page application, for example).
Of course, your player container will remain untouched.
Examples of usage
Destroy method
(async () => {
// create a player
await oberplayer(document.querySelector('#player_container')).setup({
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
});
// destroy it
oberplayer().destroy();
// re-create it
await oberplayer(document.querySelector('#player_container')).setup({
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
});
})();
Instantiation strategies
oberplayer()returns a player instance. The function can be called at any moment after the player has been created.setup()returns a Promise with a player instance as the resulting value and can load many videos in a playlistload()loads a single video playlist item.
Knowing that, you can organize your player instantiation in many ways
The shortest and easiest way
(async () => {
const player = await oberplayer(document.querySelector('#player_container')).setup({
playlist: [{
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
}]
});
})();
Divided into three steps
(async () => {
const player = oberplayer(document.querySelector('#player_container'));
await player.setup();
player.load({
playlist: [{
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
}]
});
})();
A bit shorter
(async () => {
const player = await oberplayer(document.querySelector('#player_container')).setup();
player.load({
playlist: [{
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
}]
});
})();
Update the current player instance
You can update the player on the fly without any need to destroy and re-instantiate the player. In terms of performance, thisit matters. This example will create a player with a video and then will update its video URL on the fly.
(async () => {
await oberplayer(document.querySelector('#player_container')).setup({
playlist: [{
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
autoplay: true,
muted: true
}]
});
// after 5 seconds, let's load another video
setTimeout(async () => {
await oberplayer().load({
videoUrl: 'https://cdn.oberplayer.com/fixtures/bbb_30fps.mpd'
});
}, 1000);
})();
Of course, it's not recommend to use setTimeout() to do this. We only included it in the demo; it shouldn't be reproduced (use events to be sure the first video has started)
Note : Some more datas can be passed to load() function. See load() function reference here.
Handle multiple player instances
As the returned player instance is not global, you can handle many player instances on a single page. Simply instantiate your players and start playing with them.
<div id="first_player_container"></div>
<div id="second_player_container"></div>
<script src="oberplayer.js"></script>
async function createTwoPlayers() {
try {
const first_player = oberplayer(document.querySelector('#first_player_container'));
await first_player.setup({
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
});
const second_player = oberplayer(document.querySelector('#second_player_container'));
await second_player.setup({
videoUrl: 'https://cdn.oberplayer.com/fixtures/mp4/bbb_27s_4k.mp4',
});
// wait for the players to be ready
first_player.on('ready',() => {
first_player.api.setVolume(0.9);
})
second_player.on('ready',() => {
second_player.api.setVolume(0.2);
})
} catch(err) {
console.error(err);
}
}
createTwoPlayers();
Keep in mind that calling oberplayer() without any argument will always return the first created player available. If you want another player, pass your original DOM element to the function to get the corresponding instance or store it in a var like the example above.
So, in this situation:
(oberplayer() === oberplayer(document.querySelector('#first_player_container'))) equals true