logo

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.

Table of Contents

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 Yes Yes No No No

Configuration

Initialization

Web SDK

To indicate that your stream contains 360° content, pass a valid VRConfiguration asvr 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.source = { 
    sources: { 
        type : 'application/x-mpegurl',
        src : 'http://example.com/example-stream.m3u8'
    },
    vr: {
        360: true
    }
};
iOS SDK

To indicate that your stream contains 360° content, set the VRConfiguration property when setting the SourceDescription.

var sampleSource: SourceDescription {

    let src = "https://example.com/example-stream.m3u8" 
    let stream = "application/x-mpegurl"
    let vr = VRConfiguration(vr360: true, stereoMode: nil)
    return SourceDescription(
        source: TypedSource(
            src: src,
            type: stream
            ),
        vr: vr
        )
}
Android SDK

To indicate that your stream contains 360° content. Create a  VRConfiguration variable and set it in the SourceDescription

VRConfiguration vrConfiguration = new VRConfiguration(true);

SourceDescription sourceDescription = SourceDescription.Builder
                .sourceDescription(typedSource)
                .vrConfiguration(vrConfiguration)
                .build();

        tpv.getPlayer().setSource(sourceDescription);

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

A  object contains the settings for 360 VR video playback. (ONLY USABLE ON IOS 11+)

/* 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; 
iOS SDK

Construct a VRDirection object to set to the player.vr.direction property

//setting all direction values at oncelet vrDirection = VRDirection(pitch: 0, roll: 0, yaw: 0)
theoplayer.vr?.direction = vrDirection//setting one specific directional valuetheoplayer.vr?.direction.roll = 0      //roll,pitch,yaw
Android SDK

Construct a VRDirection object to set the direction

VRDirection vrDirection = new VRDirection(0,0,0);  // e.g. {pitch: 0, yaw: 0, roll: 0}
tpv.getPlayer().getVR().setDirection(vrDirection);

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'  // horizontal, vertical, nil
       }
};
iOS SDK

The snippet below enables stereo mode by setting stereoMode to StereoMode.Horizontal/StereoMode.Vertical

let vr = VRConfiguration(vr360: true, stereoMode: StereoMode.horizontal)
Android SDK

The snippet below activates stereo mode for android. 

tpv.getPlayer().getVR().setStereo(true);    

The following code sample listens tostereochange, directionchangeevents thrown by THEOplayer and stores the new stereo mode in a variable.

Web SDK
player.vr.addEventlistener('stereochange', function() {
    var isStereoEnabled = player.vr.stereo; // (boolean)
    // do something with it
});
iOS SDK
class VRDirectionChangeEventType : EventType<VRDirectionChangeEvent>  {
    init() {
        super.init(name: "directionchange", eventHandler: VRDirectionChangeEventHandler())
    }
}
class VRStereoChangeEventType : EventType<VRStereoChangeEvent>  {
    init() {
        super.init(name: "stereochange", eventHandler: VRStereoChangeEventHandler())
    }
}
public struct VREventTypes {
    public static var VR_DIRECTION_CHANGE : EventType<VRDirectionChangeEvent> = VRDirectionChangeEventType()
    public static var VR_STEREO_CHANGE : EventType<VRStereoChangeEvent> = VRStereoChangeEventType()
}

// Fires when the viewing direction changes.
public class VRDirectionChangeEvent: VREvent {
    init(date: Date) {
        super.init(type: "directionchange", date: date)
    }
}
// Fires when the player enters or exists VR mode.
public class VRStereoChangeEvent: VREvent {
    init(date: Date) {
        super.init(type: "stereochange", date: date)
    }
}
Android SDK
//DirectionChange
tpv.getPlayer().getVR().addEventListener(VREventTypes.DIRECTIONCHANGE, new EventListener<DirectionChangeEvent>() {
    @Override
    public void handleEvent(DirectionChangeEvent directionChangeEvent) {
        Log.v("Test","Direction");
    }
});

//StereoChange
tpv.getPlayer().getVR().addEventListener(VREventTypes.STEREOCHANGE, new EventListener<StereoChangeEvent>() {
    @Override
    public void handleEvent(StereoChangeEvent stereoChangeEvent) {
        Log.v("Test","stereo");
    }
});

//StateChange
tpv.getPlayer().getVR().addEventListener(VREventTypes.STATECHANGE, new EventListener<StateChangeEvent>() {
    @Override
    public void handleEvent(StateChangeEvent stateChangeEvent) {
        Log.v("Test","state");
    }
});

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

Remarks

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

github
Make sure to follow us on GitHub!
THEO-logo-white
twitter
facebook
linkedin
Copyright © 2020. All Rights Reserved.
Leuven
New York
Singapore
Barcelona