360 Video and VR API

VR

The player's VR attributes can be used to change the stereo mode, the viewing direction and the vertical field of view.

The VR attributes are properties of the vr object, which is accessible through the player object.

Properties

The player.vr object can have the following properties:

Property Type Optional Description
direction VRDirection yes Sets or returns the viewing direction.
A VR direction object with properties yaw, pitch and roll must be set to change the direction; the values of these properties should be in degrees.
stereo boolean yes Enables/disabled or returns the the stereo mode. Can be set to "true" or "false".
Setting it to true renders the video in VR; setting it to false removes the VR rendering. Default value is false.
verticalFOV number yes Sets or returns the vertical field of view in VR. This value can be a degree in the range of  [0, 180]. Increasing this value creates a more zoomed in effect.

Events

The player.vr object supports the following events:

Event Description
directionchange Fires when the viewing direction changes.
stereochange Fires when the player enters or exists VR mode.

VRDirection

The VRDirection object can have the following properties:

Property Type Optional Description
pitch number no Rotational position around the Y-axis. Value in the range of -180 to 180.
roll number yes Rotational position around the X-axis. Value in the range of -180 to 180.
yaw number no Rotational position around the Z-axis. Value in the range of -180 to 180.

Considerations

Canvas limitations

THEOplayer VR utilises the Canvas API internally to render 360° content. As a result, the same considerations apply when using cross-origin or DRM protected content.

iPhone support requires iOS 10

On iOS 9 and lower, iPhone forces HTML5 video to play in fullscreen. As a result, the canvas used by THEOplayer VR will not be visible during playback, since it will be behind the fullscreen video.

iPhone users must upgrade to iOS 10 or higher for the full VR experience. Note that iPad is unaffected: VR is supported even on iOS 9 and lower.

Cross-origin iframes on iOS

iOS blocks cross-origin iframes from accessing devicemotion events (WebKit bug #152299). As a result, when using THEOplayer inside a cross-origin iframe, the player cannot rotate the VR display to align with the device's physical orientation. Fortunately, this can be worked around by listening for devicemotion events on the top frame and forwarding them as messages to the iframe. THEOplayer will automatically handle these messages as if they were native devicemotion events:

var playerIframe = document.querySelector('iframe');
window.addEventListener('devicemotion', function (event) {
    playerIframe.contentWindow.postMessage({
        type : 'devicemotion',
        deviceMotionEvent : {
            acceleration : event.acceleration,
            accelerationIncludingGravity : event.accelerationIncludingGravity,
            interval : event.interval,
            rotationRate : event.rotationRate,
            timeStamp : event.timeStamp
        }
    }, '*');
});