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/tvOS SDK and Legacy iOS/tvOS 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
)
}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/tvOS SDK and Legacy iOS/tvOS 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,yawAndroid 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/tvOS SDK and Legacy iOS/tvOS 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)Legacy Android SDK (4.12.x)
The snippet below activates stereo mode for Android.
tpv.getPlayer().getVR().setStereo(true); 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
});iOS/tvOS SDK and Legacy iOS/tvOS 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)
}
}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");
}
});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 Applications
The demo below illustrates the VR API in production for Web SDK.
Demo: 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.
