VR

This article describes how to implement common use cases related to VR / 360 - for example how to use the API.

The VR feature enables video to be rendered in a VR / 360 - experience. The input should be a video source in an equirectangular format, and the output is a container where viewers can navigate around the scene.

The VR feature exposes the VR API. This API allows developers to change the pitch, direction and more.

360 / VR

360-degree video is a type of video where every angle from a single viewpoint is recorded and can played back. It offers a great sense of immersion for panoramic imagery or simulation purposes.

THEOplayer allows you to render these videos in your browser or on your mobile device, with a full set of API controls to control the viewing direction.

Next to the spherical or 360° video playback, THEOplayer also offers integration with VR devices through stereoscopic view, dubbed "stereo mode".

SDKs

Web SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK
Yes	No*	No*	No	No	No

^* VR is currently not supported in the native Android and iOS SDKs. Please reach out to us for VR support on the native SDKs.

Configuration

Initialization

Web SDK

The Web SDK uses the WebXR API for virtual reality playback. For platforms that do not natively support WebXR, you can add the WebXR polyfill to your web page.

Bug in official polyfill

The official polyfill has a bug in its rendering, see issue 167. Our team has already proposed and submitted a fix, but this fix has not yet been published in a new release of the polyfill.

In the meantime, you can use a patched build from our CDN. We highly recommend you to download and host this build on your own web server, since it will no longer be available once the official polyfill has been fixed.

Add the polyfill to your page:

<script src="//cdn.theoplayer.com/webxr/webxr-polyfill-patched.js"></script>

And enable it:

const POLYFILL_CONFIG = {
  allowCardboardOnDesktop: true,
};
new WebXRPolyfill(POLYFILL_CONFIG);

To indicate that your stream contains 360° content, pass a valid VRConfiguration as vr property when setting player.source.

For the full list of properties and events related to 360° video and VR, go to our API page.

var element = document.querySelector('.theoplayer');
var player = new THEOplayer.Player(element, {
  fluid: true,
});

player.vr.useDeviceMotionControls = true;

player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'http://example.com/example-stream.m3u8',
  },
  vr: {
    360: true,
  },
};

Manipulating the viewing direction within a 360 video

Below you can find an example querying the VR viewing direction and one setting the viewing direction.

Web SDK

/* reading the current position */
var currentViewingDirection = player.vr.direction; // e.g. {pitch: 0, yaw: 0, roll: 0}

/* setting the position */
player.vr.direction = { pitch: 0, yaw: 180, roll: 0 };

/* example of how you can update only one direction property */
var currentViewingDirection = player.vr.direction; /* e.g. {pitch: 0, yaw: 30, roll: 0} */
currentViewingDirection.pitch = 180; /* {pitch: 180, yaw:30, roll: 0} */
player.vr.direction = currentViewingDirection;

Setting stereoMode

Web SDK

The snippet below enables stereo mode by setting the stereoMode variable to horizontal/vertical.

player.source = {
  sources: [
    {
      src: 'http://example.com/example-stream.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  vr: {
    360: true,
    stereoMode: 'horizontal', // or 'vertical'
  },
};

Listening to VR related events

The following code sample listens to stereochange and directionchange events thrown by THEOplayer and stores the new values in a variable.

Web SDK

player.vr.addEventlistener('stereochange', () => {
  const isStereoEnabled = player.vr.stereo; // (boolean)
  // do something with it
});

player.vr.addEventlistener('directionchange', () => {
  const { yaw, roll, pitch } = player.vr.direction; // (object)
  // do something with it
});

Request Permissions

Since iOS 13, access to device orientation and motion data is disabled by default. You will need to include code to request the necessary permission, triggered by a user action.

You can do this by using the following function to handle a user interaction triggered event

function requestPermissions() {
  DeviceMotionEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('devicemotion', (e) => {
          console.log('Device motion permissions granted');
        });
      }
    })
    .catch(console.error);
  DeviceOrientationEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('deviceorientation', (e) => {
          console.log('Device orient permissions granted');
        });
      }
    })
    .catch(console.error);
}

Sample Application

The following demo illustrates the VR API in production for Web SDK: https://www.theoplayer.com/theoplayer-demo-virtual-reality-360-degree-view

Remarks

When trying to use the StereoMode functionality, the device must have the automatic rotation feature enabled.