360°/VR Video Plugin

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Topic(s)
360 Video
Plugins

In this topic, you will learn how this plugin turns a properly recorded video element into a HTML5, panoramic, 360º video that can be played in Brightcove Player.

Example player

The sample video below demonstrates the use of the 360°/VR Plugin. Once you click on the video to play it, you can use either your mouse or the arrow keys to control the view on the desktop, or the gyroscope if viewing on a mobile device. The 360° video logo play button disappears on play.

 

Introduction

Features

The following are features of the 360°/VR Plugin:

  • Gyroscope integration on mobile devices: The perspective changes as you rotate your phone.
  • Cardboard/VR mode support: On devices that support it, the Cardboard viewer icon will appear in the control bar. When pressed, the projection will be adjusted to work with Cardboard-style VR goggles.
  • Video Cloud Media 360 Setting: If you are using Video Cloud videos, the plugin respects Video Cloud’s setting for 360 on Video Cloud media. If the value is not present it will play the video as a normal video. You do not have to ensure that only 360 videos are played on players using the 360°/VR Plugin.
  • Non-Video Cloud Media: If you are not using media served from Video Cloud, you can still use the plugin. You will need to call the vr plugin passing an object with a projection value set as follows:
    <script type="text/javascript">
      videojs.getPlayer('myPlayerID').ready(function() {
        var myPlayer = this;
        myPlayer.vr({projection: '360'});
      });
    </script>

    Of course, the code above assumes you have included the JavaScript and CSS files for the plugin, as described later in this document.

Browser compatibility

The plugin is compatible with the latest versions of these major browsers:

  • Chrome Desktop
  • Chrome Mobile (on Android 6+)
  • Firefox Desktop
  • Edge
  • Safari Desktop *
  • Safari Mobile (iOS 11.2+) *

The plugin does NOT work with Internet Explorer.

Limitations

You should be aware of the following when using the 360°/VR Plugin:

  • MP4 video renditions are preferred over HLS for videos that use this plugin.
  • Single Bitrate: You must select Single Bitrate High as the ingest profile for 360 videos. This is because 360/VR playback only shows a small portion of the frame at a time (more details on this appear in the next section of this document). Any other setting will result in very poor quality. If you are not using Video Cloud, we recommend you use a single high-resolution HLS rendition or MP4 video in order to disable rendition switching.

Implementation overview

Implementing the plugin is straightforward, just complete these two steps:

Ingest the 360 video

Once you have the 360 video recorded, you need to ingest it into Video Cloud. A little understanding of how 360 video works will help you understand some reasons for the Ingest Profile to choose. The 360 video is filmed to be projected on the interior of a sphere. This means that the visible area of the video in the player is only a fraction of the entire video. The following screenshot gives you a rough idea of this concept. The area inside the red rectangle is what is visible in the player, but only a small part of the entire video.

show part of video

Since only a small part of the video will be in the player at any one time, you want a very high quality rendition to be playing, with no chance of stepping down to a lower quality rendition. In essence, you are "zooming in" on part of the video and a poor quality rendition would yield a very poor quality viewing experience. For this reason, during the ingestion process you should use an Ingest Profile of high-quality, and few renditions. Brightcove recommends using the single-bitrate-high (2 renditions) Ingest Profile for 360 videos. This profile includes a high quality MP4 rendition, which is preferred over HLS renditions when using the 360 Plugin.

Be sure when the video is ingested it is marked for 360 projection, as shown here in the video's information section:

show part of video

Implement using Players module

To implement the 360°/VR Plugin you will add the name of the plugin and the URLs to the plugin's JavaScript and CSS files:

  1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
  2. Click the link for the player to open the player's properties.
  3. Click Plugins in the left navigation menu.
  4. Next click Add a Plugin.
  5. For the Plugin Name enter vr.
  6. For the JavaScript URL, enter:
    https://players.brightcove.net/videojs-vr/1/videojs-vr.min.js
  7. For the CSS URL, enter:
    https://players.brightcove.net/videojs-vr/1/videojs-vr.css
  8. You do not have to enter any options for Video Cloud videos. If you are using non-Video Cloud 360 videos you will have to set the projection here, as mentioned in the Introduction section.
  9. Click Save in the Plugins section.
  10. Click Styling in the left navigation menu.
  11. If you feel it will be a better viewing experience, you can disable the title and description dock. To do this, uncheck the Show title and description checkbox.
    disable dock
  12. To publish the player, click Publish & Embed > Publish Changes.
  13. To close the open dialog, click Close.

Options

forceCardboard

Type: boolean Default Value: false

Force the cardboard button to display on all devices.

projection

Type: string Default Value: auto

Video Type Value for projection Option
sphere 360, Sphere or equirectangular
cube Cube or 360_CUBE
NOT a 360 video None
If you want to check if the current video is a 360 video via player.mediainfo.projection AUTO
Side-by-side 360 video 360_LR
Top-to-bottom 360 video 360_TB

player.mediainfo.projection

Type: string Default Value: undefined

This value should be set on a source-by-source basis to turn 360 videos on an off depending upon the video.

debug

Type: boolean Default Value: false

Enable debug logging for this plugin.

Advertising

At this time support for advertising in this plugin is limited to IMA3 pre-rolls only. Other types of ads and other ad vendors are not currently supported.

Known issues

  • Although the 360°/VR Plugin may work with live streams, it is not officially supported.
  • The latest 360°/VR Plugin is compatible with Brightcove Player version 6.17.0 and later.
  • The 360°/VR Plugin does not function with Internet Explorer.
  • The 360°/VR Plugin does not support DRM.
  • Stereoscopic/stacked videos are not supported by the plugin.
  • On mobile devices only horizontal swiping works (this changes the view horizontally), but swiping the screen vertically does not do anything. The vertical swiping does work for desktop browsers.
  • The Standard (iframe) implementation of Brightcove Player will NOT change orientation.
  • Multiple players on a single page: If you have multiple players on the page using this plugin, and both use the advanced (in-page embed) player implementation, only the first player will function correctly. Multiple players on a page that use the standard (iframe) implementation will function correctly.
  • On iOS, for the 360 plugin to render videos correctly the Preload Video Before Playback setting must be set to Yes in the player:
    ios preload
  • On iOS, the fullscreen mode button is disabled since the 360°/VR Plugin does not work with the iOS native player. Because of this, it is recommended that you set the playsinline attribute for non-fullscreen video playback, as shown in the iOS and Brightcove Player document.

Changelog

17 Sep 2018

v1.5.0

  • New feature: Motion controls option
  • Bug fix: Removed the postinstall script to prevent install issues
  • Updated to generator-videojs-plugin 7.2.0
  • Updated videojs-generate-rollup-config to version 2.2.0

23 Aug 2018

v1.4.7

  • Using Generator 7

8 Aug 2018

v1.4.6

  • Updated dependencies

3 Aug 2018

v1.4.5

  • Babel the ES distribution by updating the generator

1 Aug 2018

v1.4.4

  • Dispose of event listeners on window correctly

20 Jul 2018

v1.4.3

  • Corrected incorrect CSS naming

5 July 2018

v1.4.2

  • Update to generator v6

18 Jun 2018

v1.4.1

  • Bug fixed: iOS sizing issue when deactivating VR display

8 Jun 2018

v1.4.0

  • Hide control bar while moving, allow clicking to play/pause, allow right click
  • Update rollup and rollup-plugin-json

23 May 2018

v1.3.0

  • Now handles 360_CUBE projection
  • Bug Fix: FrontSide -> BackSide for 360 videos due to changes in three.js
  • Bug Fix: No rotate instructions and iOS back arrow fix
  • Bug Fix: Re-implement touch pan controls
  • Bug Fix: Remove Safari video image canvas work-around
  • Bug Fix: vjs-fluid class usage, and remove mutationobserver work-around
  • Updated rollup to version 0.58.2
  • Updated rollup-plugin-babel to version 3.0.4
  • Updated rollup-plugin-commonjs to version 9.1.3
  • Updated three to version 0.92.0

8 May 2018

v1.2.1

  • Correctly show an error in IE/Safari when WebVR is unsupported

27 Mar 2018

v1.2.0

  • Bug fix: Chrome m55 Android gyro breakage by updating webvr-polyfill
  • Updated Rollup to version 0.57.1

20 Feb 2018

v1.1.1

  • Expose version correctly
  • OrbitControls: no pan, less speed, no zoom
  • Rework three example builds to fix webpack

31 Jan 2018

v1.1.0

  • Removed three unnecessary JavaScript files from the repo
  • Bug Fixes
    • Default projection typo
    • Native WebVR
    • Safari HLS

4 Dec 2017

v1.0.3

  • Implemented workaround for firefox/polyfill display issue

19 Oct 2017

v1.0.2

  • Makes stereo modes so actually stereo
  • Updated information in readme about equirectangular

29 Aug 2017

v1.0.1

  • Made the projection values equirectangular and 360 equivalent.

24 Aug 2017

v1.0.0

  • Added an option to force cardboard button
  • Exposed more of VRS methods
  • Added a cardboard button for native webvr support
  • Auto projection set to the correct value and not auto
  • Cleaned up window listeners
  • Correctly checks for cardboard button on control bar so two aren't added
  • Encode svg in CSS, use exact button replacement size
  • Made cardboard button pseudo fullscreen on iOS
  • Updated pin webvr-polyfill to 0.9.23
  • Fixed pixelation issues on some devices
  • Prevent initialization from happening twice
  • Separated and reset CardboardButton and BigVrPlayButton
  • Use player fullscreenchange event so fullscreen toggle works on Safari