API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

VR

Virtual Reality playback configuration and controls

FieldOfView

Interface

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

Interface

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

Interface

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

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

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

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

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

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

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

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

factor

number

The zoom factor to apply.

Returns

boolean

  • True, if the VRHandler is ready, false otherwise.

TransitionTimingType

Enum

Enumeration Members

EaseIn

EaseIn: "ease-in"

EaseInOut

EaseInOut: "ease-in-out"

EaseOut

EaseOut: "ease-out"

None

None: "none"

Vec3

Interface

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

Interface

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

Interface

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

Interface

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

Enum

Enumeration Members

SBS

SBS: "sbs"

Single

Single: "single"

TAB

TAB: "tab"

VRControlConfig

Interface

Extended by

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

Interface

Extends

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

Enum

Enumeration Members

Error

Error: "error"

Playing

Playing: "playing"

Ready

Ready: "ready"

Uninitialized

Uninitialized: "uninitialized"

VRViewingWindowConfig

Interface

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

Interface

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

Enum

Enumeration Members

Fullscreen

Fullscreen: "fullscreen"

Inline

Inline: "inline"

PictureInPicture

PictureInPicture: "pictureinpicture"

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?