⚠️ Sunset Notice: This service will be discontinued as of September 30th, 2023. Learn more »
Did you come here for Live Video Shopping?
This is documentation for Bambuser Live Streaming SDK.
If you're looking for documentation regarding Live Video Shopping (opens new window) , see these pages (opens new window)
How to create a live video player on the web
For showing a Bambuser broadcast in a web app you have two options:
Iframe embed
The easiest way to embed Bambuser content is using an iframe, with a
signed resourceUri in the url. The controls in the iframe embed have been designed by us and cannot be changed by your application. If you want to use the browser's built-in controls for <video>
elements, check out the JavaScript player below.
Syntax
<iframe
src="https://cdn.bambuser.net/player/?resourceUri=YOUR_RESOURCE_URI"
style="border: none"
allowfullscreen></iframe>
Options
The iframe embed supports various options, provided via url parameters
(appended to the URL, separated by an ampersand &
):
name | type | description |
---|---|---|
autoplay | boolean | Start playing immediately after the page has loaded. Note: will not work in all browsers. |
volume | number | Set default volume to a value between 0 and 1. |
muted | boolean | Set to 1 to mute the player. |
noFullscreen | boolean | Disallow the player from going fullscreen. |
broadcastState | string | Allow playback only if the broadcast is in a specific state; either live or archived . |
scaleMode | string | Set the scale-mode to one of: aspectFill, aspectFit, fill (see descriptions below). |
showViewerCount | boolean | Set to 1 to display the number of concurrent live viewers. |
Example
A full-width player with a 16:9 aspect-ratio (opens new window)
<div style="width: 100%; padding-bottom: 56.25%; position: relative">
<iframe
style="position: absolute; width: 100%; height: 100%; border: none"
src="https://cdn.bambuser.net/player/?resourceUri=https%3A//cdn.bambuser.net/broadcasts/0b9860dd-359a-67c4-51d9-d87402770319%3Fda_signature_method%3DHMAC-SHA256%26da_id%3D9e1b1e83-657d-7c83-b8e7-0b782ac9543a%26da_timestamp%3D1482921565%26da_static%3D1%26da_ttl%3D0%26da_signature%3Dcacf92c6737bb60beb1ee1320ad85c0ae48b91f9c1fbcb3032f54d5cfedc7afe"
allowfullscreen></iframe>
</div>
Custom start and end position
If you want to highlight a certain time range in an archived video you may set custom start and end positions. Simply add #t=start,end
to the url. The positions are expected to be set in seconds.
Examples:
time range | result |
---|---|
t=10,20 | Plays interval [10, 20] |
t=,20 | Plays interval [start, 20] |
t=10 | Plays interval [10, end] |
Listening to player events
While the page that embeds the iframe player does not have direct access to the player's internal state, some events are dispatched to the parent page. These events are sent from the iframe to the parent page using Window.postMessage() (opens new window).
This allows a page using the iframe player to react to events emitted by the internal video element and keep itself up to date with what is going on inside the black box.
Example:
window.addEventListener('message', function(event) {
if (event.origin !== 'https://cdn.bambuser.net') {
// Don't trust messages from other origins
return;
}
var videoEvent = event.data.videoEvent;
if (videoEvent) {
console.log('video event:', videoEvent.name);
}
}, false);
JavaScript player
The JavaScript API lets you embed a player and control the player using JavaScript. This is the ideal option if you want to build your own UI.
Getting started
Load the bambuser-video-iframeapi.min.js
library and initialize a player instance
by calling BambuserPlayer.create(<target element>, <resourceUri>)
. The returned object
behaves much like an HTML5 <video> element, exposing a similar API and similar events.
Import the JavaScript and prepare an HTML element where you want to render the BambuserPlayer:
<script src="https://cdn.bambuser.net/player/lib/bambuser-video-iframeapi/latest/bambuser-video-iframeapi.min.js"></script>
<div id="player"></div>
When creating the BambuserPlayer, pass it the target HTML element, a signed resourceUri and optional parameters.
Example
var resourceUri = 'https://cdn.bambuser.net/broadcasts/0b9860dd-359a-67c4-51d9-d87402770319?da_signature_method=HMAC-SHA256&da_id=9e1b1e83-657d-7c83-b8e7-0b782ac9543a&da_timestamp=1482921565&da_static=1&da_ttl=0&da_signature=cacf92c6737bb60beb1ee1320ad85c0ae48b91f9c1fbcb3032f54d5cfedc7afe';
var player = BambuserPlayer.create(document.getElementById('player'), resourceUri, {
noFullscreen: true // Do not allow fullscreen
});
// Listen to player events
player.addEventListener('pause', function() {
console.log('player paused');
});
player.addEventListener('timeupdate', function() {
console.log('current time', player.currentTime);
});
/**
* Controlling the player programmatically
*/
// Hide the UI provided by the native player (see the note below regarding iDevices).
player.controls = false;
// Seek a few minutes into the video.
player.currentTime = 300;
// Start the video immediately.
player.play();
// NOTE: Setting player.autoplay=true would have the same effect.
// However, calling play() or setting player.autoplay=true will not
// work on many handheld devices (see the note below).
// Make the video play/pause when the user clicks on the container div.
document.getElementById('player').addEventListener('click', function() {
return player.paused ? player.play() : player.pause();
});
// NOTE: on many handheld devices play() will only work when called
// inside an event handler for a user gesture (like we did here).
// NOTE: iDevices insist on us using their own controls and will not let
// us start playback using the play() method, even when called from an event
// handler as described above.
if (navigator.userAgent.match(/iPad|iPhone|iPod/) && !window.MSStream) {
player.controls = true;
}
Autoplay
Being able to start playback programmatically,
either using play()
or the autoplay
property is restricted in many browsers.
Autoplay is only allowed under certain circumstances.
Read more about autoplay policies for...
Options
The BambuserPlayer.create()
function takes an optional third argument with an object containing additional options.
name | type | description |
---|---|---|
noFullscreen | boolean | Disables fullscreen |
timeshift | boolean | Enables seeking in live broadcasts, but disables low-latency viewing. It is recommended to enable timeshifting only when necessary, as it involves higher latency, and playback performance may suffer on very long broadcasts. |
startPosition | number | Sets a custom starting position. The position is expected to be set in seconds and only works for archived videos. |
endPosition | number | Sets a custom end position. The position is expected to be set in seconds and only works for archived videos. |
Object methods
play()
pause()
addEventListener()
removeEventListener()
Object properties
Supported HTML5 video properties:
autoplay
,
buffered
controls
,
currentTime
,
duration
,
ended
,
error
,
muted
,
paused
,
poster
,
seeking
,
volume
Custom properties
name | type | description |
---|---|---|
broadcastId | string | Get the broadcastId for the current loaded broadcast. |
isLive | boolean | Tells whether the broadcast is live rather than viewed on-demand. |
viewers | object | Shows the number of current and total viewers on the broadcast (see example below). |
timeshift | boolean | Get/set the current timeshift configuration. This property is settable only if timeshift mode has been enabled through the player constructor. Switching it off will essentially seek to the end. This property will not switch to low-latency mode. For low-latency mode, a new player must be constructed without timeshift-mode. |
scaleMode | string | Get/set the current scale-mode to one of: aspectFill, aspectFit, fill (see descriptions below). |
viewers
property
Example value of the {
"current": 1,
"total": 10
}
Scale modes
name | description |
---|---|
aspectFill | Preserve the video's aspect ratio and fill the player's bounds. |
aspectFit | Preserve the video's aspect ratio and fit the video within the player's bounds. |
fill | Stretch the video to fill the player's bounds. |
Events
Supported HTML5 video events:
canplay
,
durationchange
,
ended
,
error
,
loadeddata
,
loadedmetadata
,
pause
,
play
,
playing
,
progress
,
seeked
,
seeking
,
timeupdate
,
volumechange
,
waiting