tencent cloud

VR Playback Plugin
Last updated:2026-02-26 17:10:51
VR Playback Plugin
Last updated: 2026-02-26 17:10:51

Function Introduction

The VR playback component can be used for VR panoramic video playback. During playback, the viewing angle can be changed by gyroscope rotation or gesture operations, allowing for 360-degree unobstructed viewing of panoramic videos. Currently, the VR playback component supports configuring monocular or binocular modes. Monocular mode is suitable for naked-eye viewing of panoramic videos, while binocular mode is suitable for viewing with VR glasses and other devices. In addition, the iOS side supports 180-degree hemispherical panoramic videos, which can adapt to more usage scenarios.

Conditions for Use

Currently, the VR playback plugin can be used with mobile player SDK version 11.3 and above, as well as the mobile player SDK (Advanced Edition).
VR playback requires obtaining the advanced version of the mobile player License to use.

Operation Steps

Step 1: Obtain the Plugin

1. The VR playback plugin (hereinafter referred to as the "plugin") is provided as a separate SDK, which you can integrate into your project based on your project requirements. The download address is as follows:
Terminal Category
SDK Download Address
Android Side
VR plugin
iOS Side
Mobile Player SDK
For SDK versions 13.1 and above, download: VR plugin
For SDK versions below 13.1, download: VR plugin
2. Integrate the downloaded "plugin plugin_monet-release-v.x.x.x.aar" or "TXCMonetPlugin-release-v.x.x.x.framework" (where x.x.x. is the version number) into the project. After starting the player instance, the host will automatically load the plugin.

Step 2: Initialize License

To use the VR playback function, you need to use the advanced version of the mobile player License. You can refer to the mobile player License guide to obtain it. If you have obtained the corresponding License, you can go to VOD Console > License Management > Mobile License to get the corresponding LicenseURL and LicenseKey, and then initialize the License through the following interface.
Android
iOS
String licenseUrl = "Enter the URL of the License you purchased";
String licenseKey = "Enter the Key of the License you purchased"
TXLiveBase.getInstance().setLicence(context, licenseUrl, licenseKey);
NSString *licenseURL = "Enter the URL of the License you purchased";
NSString *licenseKey = "Enter the Key of the License you purchased"
[TXLiveBase setLicenceURL:licenseURL key:licenseKey];

Step 3: Enable or disable the terminal's VR panoramic video capability

After starting playback (it is recommended to call after receiving the TXLiveConstants.PLAY_EVT_VOD_PLAY_PREPARED event), you can enable and disable the VR panoramic video through the following interface in TXVodPlayer:
Android
iOS
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXLiveConstants.PLAY_EVT_VOD_PLAY_PREPARED) {
// Enable the terminal VR panoramic video monocular mode. If you need to enable the binocular mode, set the value to '12'.
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 11);
}


}


// Disable terminal VR panoramic video.
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 0);
// Enable VR panoramic video monocular mode. If you need to enable the binocular mode, set the value to '12'.
// Note: The settings for enabling VR panoramic video need to be set before the player starts playing, or if you set them during the playback process, you need to restart the playback after the setting.
// It is recommended to add a switch animation here.
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
[extInfoMap setObject:@"11" forKey:@"PARAM_MODULE_TYPE"];
[_txVodPlayer setExtentOptionInfo:extInfoMap];

// Disable terminal VR panoramic video.
[extInfoMap setObject:@"0" forKey:@"PARAM_MODULE_TYPE"];
Android
iOS

Configuring Constants

Located in the TXVodConstants.java class.
Constant name
Constant Value
Description
PLAYER_OPTION_PARAM_MODULE_TYPE
"PARAM_MODULE_TYPE"
Module Type.
PLAYER_OPTION_PARAM_MODULE_CONFIG
"PARAM_MODULE_CONFIG"
Module Configuration.
PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR
"ENABLE_SENSOR"
Enable sensor, default value is true.
PLAYER_OPTION_PARAM_MODULE_VR_FOV
"FOV"
Field of View (FOV), default value 65.0 degrees, with a valid range between 30.0 and 110.0 degrees.
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X
"ANGLE_X"
Horizontal rotation angle, where positive values indicate a rightward turn and negative values denote a leftward turn. 0° represents the forward-facing direction, with a valid range spanning from -180° to 180°.
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y
"ANGLE_Y"
Vertical rotation angle, where positive values indicate upward tilt and negative values indicate downward tilt. A value of 0° represents a horizontal view. The valid range is from -85° to 85°.
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE
"ANGLE_RATE"
The ratio of gesture sliding distance to angle, where a higher ratio indicates greater sensitivity. The default value is 1/8f.
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD
"ANGLE_SLOPE_THRESHOLD"
Rotation XY angle slope threshold, with a default value of 0.5f. Within this threshold range, only the long edges are selected for rotation.
PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE
"MONET_AC_DO_ROTATE"
VR rotation angle.

Module Type Values

Constant name
Constant Value
Description
PLAYER_OPTION_PARAM_MODULE_TYPE_NONE
0
The null type, which disables features such as super-resolution and VR.
PLAYER_OPTION_PARAM_MODULE_TYPE_SR
1
Super-resolution type.
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA
11
VR panoramic model, monocular.
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR
12
VR panoramic model, binocular.

VR Playback Callback Events

Constant name
Constant Value
Description
PLAYER_OPTION_EVT_ANGLES
8001
Rotation angle change event.
PLAYER_OPTION_EVT_KEY_ANGLE_X
"ANGLE_X"
Horizontal rotation angle, positive values indicate rightward rotation, negative values indicate leftward rotation.
PLAYER_OPTION_EVT_KEY_ANGLE_Y
"ANGLE_Y"
Vertical rotation angle, with positive values indicating upward rotation and negative values indicating downward rotation.

Configuring Constants

Header file: TXVodSDKEventDef.h
Constant name
Constant Value
Constant name
Constant Value
Description
PLAYER_OPTION_PARAM_MODULE_TYPE
@"PARAM_MODULE_TYPE"
Module Type.


PLAYER_OPTION_PARAM_MODULE_CONFIG
@"PARAM_MODULE_CONFIG"
Module Configuration.


PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR
@"ENABLE_SENSOR"
Enable sensor, default value is true.


PLAYER_OPTION_PARAM_MODULE_VR_FOV
@"FOV"
Field of View (FOV), default value 65.0 degrees, with a valid range between 30.0 and 110.0 degrees.


PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X
@"ANGLE_X"
Horizontal rotation angle, where positive values indicate a rightward turn and negative values denote a leftward turn. 0° represents the forward-facing direction, with a valid range spanning from -180° to 180°.


PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y
@"ANGLE_Y"
Vertical rotation angle, where positive values indicate upward tilt and negative values indicate downward tilt. A value of 0° represents a horizontal view. The valid range is from -85° to 85°.


PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE
@"ANGLE_RATE"
The ratio of gesture sliding distance to angle; a higher ratio indicates greater sensitivity, with a default value of 1/3.0f.


PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD
@"ANGLE_SLOPE_THRESHOLD"
Rotation XY angle slope threshold, with a default value of 0.5f. Within this threshold range, only the long edges are selected for rotation.


PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE
@"MONET_AC_DO_ROTATE"
VR rotation angle.



Module Type Values

Constant name
Constant Value
Description
PLAYER_OPTION_PARAM_MODULE_TYPE_NONE
0
The null type, which disables features such as super-resolution and VR.
PLAYER_OPTION_PARAM_MODULE_TYPE_SR
1
Super-resolution type.
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA
11
VR panoramic model, monocular.
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR
12
VR panoramic model, binocular.

VR Playback Callback Events

Constant name
Constant Value
Description
PLAYER_OPTION_EVT_ANGLES
8001
Rotation angle change event.
PLAYER_OPTION_EVT_KEY_ANGLE_X
"ANGLE_X"
Horizontal rotation angle, positive values indicate rightward rotation, negative values indicate leftward rotation.
PLAYER_OPTION_EVT_KEY_ANGLE_Y
"ANGLE_Y"
Vertical rotation angle, with positive values indicating upward rotation and negative values indicating downward rotation.

Plugin loading configuration

After adding the terminal ultra-fast HD plugin to the project, it will be automatically loaded by default. If you do not want the player to load this plugin, you can turn it off as follows:
Android
iOS
TXVodPlayConfig playConfig = new TXVodPlayConfig();
playConfig.mEnableRenderProcess = false;
mVodPlayer.setConfig(playConfig);
TXVodPlayConfig *playConfig = [[TXVodPlayConfig alloc] init];
playConfig.enableRenderProcess = NO;
[_txVodPlayer setConfig:playConfig];

Setting obfuscation rules

In the proguard-rules.pro file, add the terminal ultra-fast HD related classes to the non-obfuscation list (iOS is not obfuscated by default):
-keep class com.tencent.** { *; }

Feature Usage

Configuring VR Information Before Playback

Android
iOS
// Create a VR configuration dictionary to store specific VR parameters
Map<String, Object> config = new HashMap<>();
// Turn off the sensor (gyroscope). Setting it to false means that the viewing angle is not changed by device rotation.
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR, false);
// Set the field of view to 90 degrees, with a value range of 30.0f-110.0f degrees and a default of 65.0f degrees.
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_FOV, 90.0f);
// Set the ratio of gesture swipe distance to angle. The larger the ratio, the higher the sensitivity. The default value is 1/8f.
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE, 0.2f);
// Set the XY angle slope threshold for rotation to 0.3 (default value 0.5f). Within this threshold range, only the longer side will be selected for rotation.
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD, 0.3f);
// Apply the VR configuration dictionary to the player
mVodPlayer.setStringOption(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_CONFIG, config);
// Set the VR type to panoramic monocular mode (for binocular mode, use PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR)
mVodPlayer.setStringOption(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_TYPE,
TXVodConstants.PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA);
// Start playback
int result = mVodPlayer.startVodPlay(playUrl);
// Create an extended information dictionary to store VR configuration
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
// Set the VR type to panoramic monocular mode (use PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR for binocular mode)
[extInfoMap setObject:@(PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA)
forKey:PLAYER_OPTION_PARAM_MODULE_TYPE];
// Create a VR configuration dictionary to store specific VR parameters
NSMutableDictionary *vrconfig = [NSMutableDictionary dictionary];
// Enable the sensor (gyroscope), setting it to YES indicates that the viewing angle can be changed by rotating the device
[vrconfig setObject:@(YES) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR];
// Set the field of view to 110 degrees, with a range of 30.0f-110.0f degrees and a default of 65.0f degrees.
[vrconfig setObject:@(110.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_FOV];
// Set the XY angle slope threshold to 0.3, with a default value of 0.5f. Within this threshold range, only the longer side is selected for rotation.
[vrconfig setObject:@(0.3f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD];
// Add the VR configuration dictionary to the extended information dictionary.
[extInfoMap setObject:vrconfig forKey:PLAYER_OPTION_PARAM_MODULE_CONFIG];
// Apply the extended information to the player to complete the VR configuration.
[self.vodPlayer setExtentOptionInfo:extInfoMap];

Rotation Angle During Playback

Android
iOS
Map<String, Object> action = new HashMap<>();
// Horizontal rotation angle, positive value turns right, negative value turns left
action.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X, 10.0f);
// Vertical rotation angle, positive value turns up, negative value turns down
action.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y, 10.0f);
mVodPlayer.setStringOption(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE, action);
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
NSMutableDictionary *action = [NSMutableDictionary dictionary];
/// Horizontal rotation angle, positive value rotates right, negative value rotates left
[action setObject:@(10.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X];
/// Vertical rotation angle, positive value rotates up, negative value rotates down
[action setObject:@(10.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y];
[extInfoMap setObject:action forKey:PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE];
[self.vodPlayer setExtentOptionInfo:extInfoMap];

Monitoring VR Playback Callback Events

Android
iOS
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXVodConstants.PLAYER_OPTION_EVT_ANGLES) {
if (param != null) {
// Get horizontal rotation angle
float angleX = param.getFloat(TXVodConstants.PLAYER_OPTION_EVT_KEY_ANGLE_X);
// Get vertical rotation angle
float angleY = param.getFloat(TXVodConstants.PLAYER_OPTION_EVT_KEY_ANGLE_Y);
}
return;
}
}
-(void) onPlayEvent:(TXVodPlayer *)player event:(int)EvtID withParam:(NSDictionary*)param
{
if (EvtID == PLAYER_OPTION_EVT_ANGLES) {
float angleX = 0;
float angleY = 0;
// Analyze angle data
for (NSString *key in param) {
id value = [param objectForKey:key];
if ([key isEqualToString:PLAYER_OPTION_EVT_KEY_ANGLE_X]) {
angleX = [value floatValue];
} else if ([key isEqualToString:PLAYER_OPTION_EVT_KEY_ANGLE_Y]) {
angleY = [value floatValue];
}
}
}
}

Log viewing

Android
iOS
1. Terminal VR panoramic video plugin load success log:
D/HostEngine-PluginManger: [loadPlugin], succeed loading pluginId=2 ,pluginClazzName=com.tencent.liteav.monet.MonetPlugin
2. VR panoramic video feature successfully enabled log:
D/MonetPlugin-Process: [updateModule], moduleType=11
3. If the following log appears, it indicates that the issued License is invalid:
E/MonetPlugin-Process: [updateModule], error, reason = license is invalid!!
1. Terminal VR panoramic video plugin load success log:
[PluginsSDK] plugin config : pluginId = 2, pluginName = Monet
2. VR panoramic video feature successfully enabled log:
[MonetProcessor] PLUGIN: did update monet module, result = 1
3. If the following log appears, it indicates that the issued License is invalid:
[MonetProcessor] Monet License invalid, error, set module is null

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback