Creating 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.

Syntax

<iframe
  src="https://dist.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.

Example

A full-width player with a 16:9 aspect-ratio

<div style="width: 100%; padding-bottom: 56.25%; position: relative">
  <iframe
    style="position: absolute; width: 100%; height: 100%; border: none"
    src="https://dist.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>

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().

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://dist.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://dist.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 html element, a signed resourceUri and desired options as parameters.

Example

var resourceUri = 'https://cdn.bambuser.net/broadcasts/3dab4df8-9cb0-21f0-a086-a866b0cd';

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;
}

iOS

A note regarding iOS devices. Being able to start playback programmatically, either using play() or the autoplay property works poorly on iPhones, iPads and iPods. While recent versions of iOS does honor the play() method and autoplayproperty under certain circumstances (read more here), it does not seem to do so when the target video element exists inside an iframe.

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.

Object methods

  • play()
  • pause()
  • addEventListener()
  • removeEventListener()

Object properties

Supported HTML5 video properties: autoplay, buffered controls, currentTime, duration, ended, error, paused, poster, seeking, volume

Custom properties

name type description
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, loadedmetadata, pause, play, playing, progress, seeked, seeking, timeupdate, volumechange, waiting