VR 播放插件

最近更新时间:2026-02-13 17:18:42

我的收藏

功能简介

VR 播放组件可用于 VR 全景视频播放,播放中可以通过陀螺仪转动或手势操作来改变视角,360度无死角的观看全景视频。目前 VR 播放组件可支持配置单目或双目模式,单目模式适用于裸眼观看全景视频,双目模式适用于 VR 眼镜等设备观看。此外 iOS 端支持180度半球模型全景视频,可适应更多的使用场景。

使用条件

目前移动端播放器 SDK 11.3 以上版本及移动端播放器 SDK(高级版)均可使用 VR 播放插件。
VR 播放需获取 移动端播放器高级版 License 方可使用。

操作步骤

步骤1:获取插件

1. VR 播放插件(下文简称“插件”)作为独立的 SDK 提供,您可以根据项目需求进行集成,下载地址如下:
终端类别
VR 插件下载地址
Android 端
VR 插件
iOS 端
移动端播放器 SDK
大于或等于13.1版本 SDK 下载:VR 插件
小于13.1版本 SDK 下载:VR 插件
2. 将下载的插件 plugin_monet-release-v.x.x.x.aar 或 TXCMonetPlugin-release-v.x.x.x.framework(x.x.x. 为版本号)集成到工程,启动播放器实例后,宿主会自动加载插件。

步骤2:初始化 License

使用 VR 播放功能需要使用移动端播放器高级版 License,您可参见 移动端播放器 License 指引获取。若您已获取对应 License,可前往 腾讯云视立方控制台 > License 管理 > 移动端 License 获取对应 LicenseURL 和 LicenseKey,随后通过下面的接口进行初始化 License。
Android
iOS
String licenceUrl = "填入您购买的 License 的 URL";
String licenseKey = "填入您购买的 License 的 Key"
TXLiveBase.getInstance().setLicence(context, licenceUrl, licenseKey);
NSString *licenceURL = "填入您购买的 License 的 URL";
NSString *licenseKey = "填入您购买的 License 的 Key"
[TXLiveBase setLicenceURL:licenceURL key:licenseKey];

步骤3:开启或关闭终端 VR 全景视频能力

启动播放后(建议在收到 TXLiveConstants.PLAY_EVT_VOD_PLAY_PREPARED 事件后调用),可以通过 TXVodPlayer 下面的接口,进行开启和关闭 VR 全景视频:
Android
iOS
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXLiveConstants.PLAY_EVT_VOD_PLAY_PREPARED) {
//开启终端VR全景视频单目模式,如需开启双目模式,value设为“12”即可
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 11);
}


}


//关闭终端VR全景视频
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 0);
//开启VR全景视频单目模式,如需开启双目模式value设为“12”
//注意:VR全景视频的开启设置需要在播放器播放之前,或者如果在播放过程中进行设置,在设置以后需要重启一下
//播放,建议这里可以做一个切换动画
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
[extInfoMap setObject:@"11" forKey:@"PARAM_MODULE_TYPE"];
[_txVodPlayer setExtentOptionInfo:extInfoMap];

//关闭VR全景视频:
[extInfoMap setObject:@"0" forKey:@"PARAM_MODULE_TYPE"];

相关配置

Android
iOS

配置常量

所在类 TXVodConstants.java。
常量名
常量值
说明
PLAYER_OPTION_PARAM_MODULE_TYPE
"PARAM_MODULE_TYPE"
Module 类型。
PLAYER_OPTION_PARAM_MODULE_CONFIG
"PARAM_MODULE_CONFIG"
Module 配置。
PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR
"ENABLE_SENSOR"
是否开启传感器,默认 true。
PLAYER_OPTION_PARAM_MODULE_VR_FOV
"FOV"
视场角,默认65.0f度,限制范围30.0f-110.0f度。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X
"ANGLE_X"
水平旋转角度,正值右转,负值左转。0°表示正前方,取值范围-180°到180°。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y
"ANGLE_Y"
垂直旋转角度,正值上转,负值下转。0°表示水平视角,取值范围-85°到85°。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE
"ANGLE_RATE"
手势滑动距离与角度比例,比例越大灵敏度越高,默认值为1/8f。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD
"ANGLE_SLOPE_THRESHOLD"
旋转XY角度斜率阈值,默认值为0.5f,阈值范围内只选取长边旋转。
PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE
"MONET_AC_DO_ROTATE"
VR 旋转角度。

Module类型值

常量名
说明
PLAYER_OPTION_PARAM_MODULE_TYPE_NONE
0
空类型,即关闭超分和 VR 等。
PLAYER_OPTION_PARAM_MODULE_TYPE_SR
1
超分类型。
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA
11
VR 全景模型,单目。
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR
12
VR 全景模型,双目。

VR 播放回调事件

常量名
说明
PLAYER_OPTION_EVT_ANGLES
8001
旋转角度变化事件。
PLAYER_OPTION_EVT_KEY_ANGLE_X
"ANGLE_X"
水平旋转角度,正值右转,负值左转。
PLAYER_OPTION_EVT_KEY_ANGLE_Y
"ANGLE_Y"
垂直旋转角度,正值上转,负值下转。

配置常量

所在头文件 TXVodSDKEventDef.h。
宏定义
说明
PLAYER_OPTION_PARAM_MODULE_TYPE
@"PARAM_MODULE_TYPE"
Module 类型。
PLAYER_OPTION_PARAM_MODULE_CONFIG
@"PARAM_MODULE_CONFIG"
Module 配置。
PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR
@"ENABLE_SENSOR"
是否开启传感器,默认 true。
PLAYER_OPTION_PARAM_MODULE_VR_FOV
@"FOV"
视场角,默认65.0f度。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X
@"ANGLE_X"
水平旋转角度,正值右转,负值左转。0°表示正前方,取值范围-180°到180°。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_Y
@"ANGLE_Y"
垂直旋转角度,正值上转,负值下转。0°表示水平视角,取值范围-85°到85°。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE
@"ANGLE_RATE"
手势滑动距离与角度比例,比例越大灵敏度越高,默认值为1/3.0f。
PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD
@"ANGLE_SLOPE_THRESHOLD"
旋转 XY 角度斜率阈值,默认值为0.5f,阈值范围内只选取长边旋转。
PLAYER_OPTION_PARAM_MODULE_VR_DO_ROTATE
@"MONET_AC_DO_ROTATE"
VR 旋转角度。

Module类型值

常量名
说明
PLAYER_OPTION_PARAM_MODULE_TYPE_NONE
0
空类型,即关闭超分和 VR 等。
PLAYER_OPTION_PARAM_MODULE_TYPE_SR
1
超分类型。
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA
11
VR 全景模型,单目。
PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR
12
VR 全景模型,双目。

VR 播放回调事件

常量名
说明
PLAYER_OPTION_EVT_ANGLES
8001
旋转角度变化事件。
PLAYER_OPTION_EVT_KEY_ANGLE_X
"ANGLE_X"
水平旋转角度,正值右转,负值左转。
PLAYER_OPTION_EVT_KEY_ANGLE_Y
"ANGLE_Y"
垂直旋转角度,正值上转,负值下转。

插件加载配置

终端极速高清插件加入到工程后,默认会自动加载, 如果您不希望播放器加载该插件,可以通过下面的方式关闭:
Android
iOS
TXVodPlayConfig playConfig = new TXVodPlayConfig();
playConfig.mEnableRenderProcess = false;
mVodPlayer.setConfig(playConfig);
TXVodPlayConfig *playConfig = [[TXVodPlayConfig alloc] init];
playConfig.enableRenderProcess = NO;
[_txVodPlayer setConfig:playConfig];

设置混淆规则

在 proguard-rules.pro 文件中,将终端极速高清相关类加入不混淆名单(iOS 默认无):
-keep class com.tencent.** { *; }

功能使用

启播前配置 VR 相关信息

Android
iOS
// 创建扩展信息字典,用于存放VR配置
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
// 设置VR类型为全景单目模式(如需双目模式,使用PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR)
[extInfoMap setObject:@(PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA)
forKey:PLAYER_OPTION_PARAM_MODULE_TYPE];

// 创建VR配置字典,用于存放具体的VR参数
NSMutableDictionary *vrconfig = [NSMutableDictionary dictionary];
// 开启传感器(陀螺仪),设置为YES表示可通过设备转动改变视角
[vrconfig setObject:@(YES) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR];
// 设置视场角为110度,取值范围30.0f-110.0f度,默认65.0f度
[vrconfig setObject:@(110.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_FOV];
// 设置旋转XY角度斜率阈值为0.3,默认值0.5f,阈值范围内只选取长边旋转
[vrconfig setObject:@(0.3f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD];
// 将VR配置字典添加到扩展信息字典中
[extInfoMap setObject:vrconfig forKey:PLAYER_OPTION_PARAM_MODULE_CONFIG];
// 将扩展信息应用到播放器,完成VR配置
[self.vodPlayer setExtentOptionInfo:extInfoMap];
// 创建扩展信息字典,用于存放VR配置
NSMutableDictionary *extInfoMap = [NSMutableDictionary dictionary];
// 设置VR类型为全景单目模式(如需双目模式,使用PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR)
[extInfoMap setObject:@(PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA)
forKey:PLAYER_OPTION_PARAM_MODULE_TYPE];

// 创建VR配置字典,用于存放具体的VR参数
NSMutableDictionary *vrconfig = [NSMutableDictionary dictionary];
// 开启传感器(陀螺仪),设置为YES表示可通过设备转动改变视角
[vrconfig setObject:@(YES) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR];
// 设置视场角为110度,取值范围30.0f-110.0f度,默认65.0f度
[vrconfig setObject:@(110.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_FOV];
// 设置旋转XY角度斜率阈值为0.3,默认值0.5f,阈值范围内只选取长边旋转
[vrconfig setObject:@(0.3f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD];
// 将VR配置字典添加到扩展信息字典中
[extInfoMap setObject:vrconfig forKey:PLAYER_OPTION_PARAM_MODULE_CONFIG];
// 将扩展信息应用到播放器,完成VR配置
[self.vodPlayer setExtentOptionInfo:extInfoMap];

播放过程中旋转角度

Android
iOS
Map<String, Object> action = new HashMap<>();
// 水平旋转角度,正值右转,负值左转
action.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X, 10.0f);
// 垂直旋转角度,正值上转,负值下转
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];
/// 水平旋转角度,正值右转,负值左转
[action setObject:@(10.0f) forKey:PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_X];
/// 垂直旋转角度,正值上转,负值下转
[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];

监听 VR 播放回调事件

Android
iOS
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXVodConstants.PLAYER_OPTION_EVT_ANGLES) {
if (param != null) {
// 获取水平旋转角度
float angleX = param.getFloat(TXVodConstants.PLAYER_OPTION_EVT_KEY_ANGLE_X);
// 获取垂直旋转角度
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;
// 解析角度数据
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];
}
}
}
}

日志查看

Android
iOS
1. 终端 VR 全景视频插件加载成功日志:
D/HostEngine-PluginManger: [loadPlugin], succeed loading pluginId=2 ,pluginClazzName=com.tencent.liteav.monet.MonetPlugin
2. VR 全景视频功能成功开启日志:
D/MonetPlugin-Process: [updateModule], moduleType=11
3. 如果出现下面的日志,表示签发的 License 不合法:
E/MonetPlugin-Process: [updateModule], error, reason = license is invalid!!
1. 终端 VR 全景视频插件加载成功日志:
[PluginsSDK] plugin config : pluginId = 2, pluginName = Monet
2. 终端 VR 全景视频成功开启日志:
[MonetProcessor] monet change VR*** module, processor: 0x10034523
3. 如果出现下面的日志,表示签发的 License 不合法:
[MonetProcessor] Monet License invalid, processor:0x10034523, set module is null