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

^* For the moment, only supported on the legacy Android and iOS SDKs (4.12.x). Please reach out to us for VR support on the native SDKs.

Configuration

Initialization

Web SDK

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,
  },
};

Android SDK

Currently VR is not supported on native Android SDK. Please reach out to us for VR support on the native SDKs.

Legacy Android SDK (4.12.x)

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

iOS SDK

Currently VR is not supported on native iOS SDK. Please reach out to us for VR support on the native SDKs.

Legacy iOS SDK (4.12.x)

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

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 available 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;

Legacy Android SDK (4.12.x)

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

Legacy iOS SDK (4.12.x)

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

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

Legacy Android SDK (4.12.x)

The snippet below activates stereo mode for Android.

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

Legacy iOS SDK (4.12.x)

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

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

Listening to VR related events

The following code sample listens to stereochange, directionchange events 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
});

Legacy Android SDK (4.12.x)

//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");
    }
});

Legacy iOS SDK (4.12.x)

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

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.