⚠️  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).

Example value of the viewers property

{
  "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