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 stereo mode (split screen for left and right); setting it to false removes the stereo 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 out 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 stereo 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
        }
    }, '*');
});