VR

FieldOfView

The field of view for VR playback.

Properties

downDegrees

• downDegrees: number

The down degrees of the field of view.

leftDegrees

• leftDegrees: number

The left degrees of the field of view.

rightDegrees

• rightDegrees: number

The right degrees of the field of view.

upDegrees

• upDegrees: number

The up degrees of the field of view.

KeyMap

Properties

down

• Optional down: string[]

The keys that shall be used to move the viewing direction downwards. Each string represents a key combination,
where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

left

• Optional left: string[]

The keys that shall be used to move the viewing direction leftwards. Each string represents a key combination,
where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

right

• Optional right: string[]

The keys that shall be used to move the viewing direction rightwards. Each string represents a key combination,
where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

rotateClockwise

• Optional rotateClockwise: string[]

The keys that shall be used to rotate the viewing direction clockwise. Each string represents a key combination,
where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

rotateCounterclockwise

• Optional rotateCounterclockwise: string[]

The keys that shall be used to rotate the viewing direction counterclockwise. Each string represents a key
combination, where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

up

• Optional up: string[]

The keys that shall be used to move the viewing direction upwards. Each string represents a key combination,
where different keys are separated by a space character, i.e. 'w', 'ArrowUp' or 'Alt F4'.

PlayerVRAPI

Methods

deviceOrientationPermissionRequired

▸ deviceOrientationPermissionRequired(): boolean

Returns true, if a permission is required to access device orientation data.

Returns

boolean

True, if a permission is required, false otherwise.

disableGyroscope

▸ disableGyroscope(): boolean

Disables the gyroscope (also on VRHMDs).

Returns

boolean

True, if the VRHandler is ready, false otherwise.

disableKeyboardControl

▸ disableKeyboardControl(): boolean

Disables the keyboard controls.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

disableMouseControl

▸ disableMouseControl(): boolean

Disables the mouse controls.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

enableGyroscope

▸ enableGyroscope(): boolean

Enables the gyroscope (also on VRHMDs).

Returns

boolean

True, if the VRHandler is ready, false otherwise.

enableKeyboardControl

▸ enableKeyboardControl(): boolean

Enables the keyboard controls.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

enableMouseControl

▸ enableMouseControl(): boolean

Enables the mouse controls.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

getHorizontalFieldOfView

▸ getHorizontalFieldOfView(): number

Gets the horizontal field of view in degrees.

Returns

number

The horizontal field of view in degrees.

getLastError

▸ getLastError(): string

Returns the last recorded error or null, if no error occurred.

Returns

string

The last recorded error.

getState

▸ getState(): string

Returns the current state of the VR handler or null, if the VR handler is not yet initialized.

Returns

string

The current state of the VR handler.

getStereo

▸ getStereo(): boolean

Returns true, if stereo is enabled, false otherwise.

Returns

boolean

True, if stereo is enabled, false otherwise.

getVerticalFieldOfView

▸ getVerticalFieldOfView(): number

Gets the vertical field of view in degrees.

Returns

number

The vertical field of view in degrees.

getViewingDirection

▸ getViewingDirection(): ViewingDirection

Returns the current viewing direction, if the VRHandler is in the playing state.

Returns

ViewingDirection

The current viewing direction.

getViewingDirectionChangeEventInterval

▸ getViewingDirectionChangeEventInterval(): number

Gets the minimal interval between consecutive VRViewingDirectionChange events.

Returns

number

The minimal interval between consecutive VRViewingDirectionChange events.

getViewingDirectionChangeThreshold

▸ getViewingDirectionChangeThreshold(): number

Gets the number of degrees that the viewport can change before the VRViewingDirectionChange event is
triggered.

Returns

number

The threshold in degrees that the viewport can change before the
VRViewingDirectionChange event is triggered.

getZoom

▸ getZoom(): number

Returns the current zoom factor.

Returns

number

The current zoom factor, if the VRHandler is ready, -1 otherwise.

isGyroscopeEnabled

▸ isGyroscopeEnabled(): boolean

Returns true, if the gyroscope is enabled, false otherwise.

Returns

boolean

True, if the gyroscope is enabled, false otherwise.

isKeyboardControlEnabled

▸ isKeyboardControlEnabled(): boolean

Returns true, if keyboard controls are enabled, false otherwise.

Returns

boolean

True, if keyboard controls are enabled, false otherwise.

isMouseControlEnabled

▸ isMouseControlEnabled(): boolean

Returns true, if mouse controls are enabled, false otherwise.

Returns

boolean

True, if mouse controls are enabled, false otherwise.

moveViewingDirection

▸ moveViewingDirection(direction): boolean

Moves the current VR viewing direction in the given direction with the given speed. The speed is determined by the
length of the direction vector in degrees / second. The movement will be continued for 110ms, after that period
the
movement will be dampened and fade out. To sustain a smooth viewport movement, no more than 100ms must pass
between
consecutive calls to this function.

Parameters

Name	Type	Description
`direction`	`Vec3`	A three-component vector describing the direction and speed in which the viewing direction shall be moved.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

requestDeviceOrientationPermission

▸ requestDeviceOrientationPermission(): Promise<void>

Requests the permission needed to access device orientation data, if required.

Returns

Promise<void>

A promise that resolves when the required permissions have been acquired.

setHorizontalFieldOfView

▸ setHorizontalFieldOfView(fieldOfView): boolean

Sets the horizontal field of view in degrees.

Parameters

Name	Type	Description
`fieldOfView`	`number`	The horizontal field of view in degrees.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

setStereo

▸ setStereo(enableStereo): boolean

Enables or disables stereo mode for VR content.

Parameters

Name	Type	Description
`enableStereo`	`boolean`	If true, stereo mode will be enabled.

Returns

boolean

True if API call was successful, false otherwise.

setVerticalFieldOfView

▸ setVerticalFieldOfView(fieldOfView): boolean

Sets the vertical field of view in degrees.

Parameters

Name	Type	Description
`fieldOfView`	`number`	The vertical field of view in degrees.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

setViewingDirection

▸ setViewingDirection(viewingDirection): boolean

Sets the given viewing direction, if the VRHandler is in the playing state.

Parameters

Name	Type	Description
`viewingDirection`	`ViewingDirection`	The viewing direction to set.

Returns

boolean

True, if the viewing direction could be set, false otherwise.

setViewingDirectionChangeEventInterval

▸ setViewingDirectionChangeEventInterval(interval): boolean

Sets the minimal interval between consecutive VRViewingDirectionChange events. The default value is 250ms.

Parameters

Name	Type	Description
`interval`	`number`	The minimal interval between consecutive VRViewingDirectionChange events.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

setViewingDirectionChangeThreshold

▸ setViewingDirectionChangeThreshold(threshold): boolean

Sets the number of degrees that the viewport can change before the VRViewingDirectionChange event is
triggered. The default value is 5°.

Parameters

Name	Type	Description
`threshold`	`number`	The threshold in degrees that the viewport can change before the VRViewingDirectionChange event is triggered.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

zoom

▸ zoom(factor): boolean

Applies a zoom factor to the current field of view.

Parameters

Name	Type	Description
`factor`	`number`	The zoom factor to apply.

Returns

boolean

True, if the VRHandler is ready, false otherwise.

TransitionTimingType

Enumeration Members

EaseIn

• EaseIn = "ease-in"

EaseInOut

• EaseInOut = "ease-in-out"

EaseOut

• EaseOut = "ease-out"

None

• None = "none"

Vec3

Represents a two-dimensional vector.

Properties

phi

• phi: number

The roll of the vector.

x

• x: number

The x component of the vector.

y

• y: number

The y component of the vector.

ViewingDirection

The direction in which the viewport of the VR player is looking.

Properties

pitch

• pitch: number

Rotation around the horizontal axis in degrees.

roll

• roll: number

Rotation around the depth axis in degrees.

yaw

• yaw: number

Rotation around the vertical axis in degrees.

ViewingWindow

Represents a viewing window for VR content. The current viewing direction is restricted to the set viewing window.

Properties

maxPitch

• maxPitch: number

Upper bound for pitch.

maxYaw

• maxYaw: number

Upper bound for yaw.

minPitch

• minPitch: number

Lower bound for pitch.

minYaw

• minYaw: number

Lower bound for yaw.

VRConfig

Example:

source: {
  dash : 'http://path/to/mpd/file.mpd',
  vr: {
    contentType: bitmovin.player.vr.ContentType.Single,
    startPosition: 180,
    initialRotation: true,
    initialRotateRate: 0.025
  }
}

Properties

apiControl

• Optional apiControl: VRControlConfig

The api control config.

cardboard

• Optional cardboard: string

Allows to set a cardboard config as string to adjust the VR/360 rendering to a specific cardboard device.
The QR codes on cardboards contain short URLs, which lead to a long URL, e.g.
http://google.com/cardboard/cfg?p=CghSZWQgQnVsbBILUmVkIEJ1bGwgVlId7FE4PSWPwnU9KhAAAEhCAABIQgAASEIAAEhCWAA1KVwPPToICtcjPArXIzxQAGAC.
The content of parameter p should be used as string.

Example:

{
  ...
  cardboard:
'CghSZWQgQnVsbBILUmVkIEJ1bGwgVlId7FE4PSWPwnU9KhAAAEhCAABIQgAASEIAAEhCWAA1KVwPPToICtcjPArXIzxQAGAC'
}

contentFieldOfView

• Optional contentFieldOfView: number

Specifies the width of the content, stated in degrees.

contentType

• contentType: VRContentType

Specifies the type of the VR/360 content.

enableFrameRateMeasurements

• Optional enableFrameRateMeasurements: boolean

Specifies whether performance measurements shall be enabled or not.

horizontalFieldOfView

• Optional horizontalFieldOfView: number

Specifies the horizontal field of view in degrees.

keyboardControl

• Optional keyboardControl: VRKeyboardControlConfig

The keyboard control config.

mouseControl

• Optional mouseControl: VRControlConfig

The mouse control config.

restrictedInlinePlayback

• Optional restrictedInlinePlayback: boolean

Specifies whether the restricted inline playback shall be used or not.

startPosition

• Optional startPosition: number

Specifies the starting viewpoint, stated in degrees.

stereo

• Optional stereo: boolean

Specifies if the video should start in stereo mode (true) or not (false, default).

verticalFieldOfView

• Optional verticalFieldOfView: number

Specifies the vertical field of view in degrees.

viewingDirectionChangeEventInterval

• Optional viewingDirectionChangeEventInterval: number

The minimal interval between consecutive VRViewingDirectionChange events.

viewingDirectionChangeThreshold

• Optional viewingDirectionChangeThreshold: number

The threshold in degrees that the viewport can change before the VRViewingDirectionChange event is
triggered.

viewingWindow

• Optional viewingWindow: VRViewingWindowConfig

Specifies the angles the user can view around within the VR/360 video.
Per default, the user has no limitations.

VRContentType

Enumeration Members

SBS

• SBS = "sbs"

Single

• Single = "single"

TAB

• TAB = "tab"

VRControlConfig

Hierarchy

VRControlConfig

↳ VRKeyboardControlConfig

Properties

maxDisplacementSpeed

• Optional maxDisplacementSpeed: number

The maximum displacement speed in degrees per second. Default values are 90°/s for keyboard controls, and
Infinity for mouse and API controls.

transitionTime

• Optional transitionTime: number

The time that a transition should take.

transitionTimingType

• Optional transitionTimingType: TransitionTimingType

Specifies the transition timing that shall be used for this control.

VRKeyboardControlConfig

Hierarchy

VRControlConfig

↳ VRKeyboardControlConfig

Properties

keyMap

• Optional keyMap: KeyMap

Specifies which keys should be used for the keyboard control.

maxDisplacementSpeed

• Optional maxDisplacementSpeed: number

The maximum displacement speed in degrees per second. Default values are 90°/s for keyboard controls, and
Infinity for mouse and API controls.

Inherited from

VRControlConfig.maxDisplacementSpeed

transitionTime

• Optional transitionTime: number

The time that a transition should take.

Inherited from

VRControlConfig.transitionTime

transitionTimingType

• Optional transitionTimingType: TransitionTimingType

Specifies the transition timing that shall be used for this control.

Inherited from

VRControlConfig.transitionTimingType

VRState

Enumeration Members

Error

• Error = "error"

Playing

• Playing = "playing"

Ready

• Ready = "ready"

Uninitialized

• Uninitialized = "uninitialized"

VRViewingWindowConfig

Properties

maxPitch

• maxPitch: number

Specifies how far right the user can look. Valid values are from 0 to 360 (default: 360).

maxYaw

• maxYaw: number

Specifies how high the user can look. Valid values are from -90 to 90 (default: 90).

minPitch

• minPitch: number

Specifies how far left the user can look. Valid values are from 0 to 360 (default: 0).

minYaw

• minYaw: number

Specifies how low the user can look. Valid values are from -90 to 90 (default: -90).

ViewModeOptions

Properties

fullscreenElement

• Optional fullscreenElement: HTMLElement

An optional alternative element to be put into Fullscreen instead of the default player
(container) element.

Since: v8.0

ViewMode

Enumeration Members

Fullscreen

• Fullscreen = "fullscreen"

Inline

• Inline = "inline"

PictureInPicture

• PictureInPicture = "pictureinpicture"