功能简介
VR 播放组件可用于 VR 全景视频播放,播放中可以通过陀螺仪转动或手势操作来改变视角,360度无死角的观看全景视频。目前 VR 播放组件可支持配置单目或双目模式,单目模式适用于裸眼观看全景视频,双目模式适用于 VR 眼镜等设备观看。此外 iOS 端支持180度半球模型全景视频,可适应更多的使用场景。
使用条件
目前移动端播放器 SDK 11.3 以上版本及移动端播放器 SDK(高级版)均可使用 VR 播放插件。
VR 播放需获取 移动端播放器高级版 License 方可使用。
操作步骤
步骤1:获取插件
1. VR 播放插件(下文简称“插件”)作为独立的 SDK 提供,您可以根据项目需求进行集成,下载地址如下:
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。
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 全景视频:
@Overridepublic 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"];
相关配置
配置常量
所在类 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" | 垂直旋转角度,正值上转,负值下转。 |
插件加载配置
终端极速高清插件加入到工程后,默认会自动加载, 如果您不希望播放器加载该插件,可以通过下面的方式关闭:
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 相关信息
// 创建扩展信息字典,用于存放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];
播放过程中旋转角度
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 播放回调事件
@Overridepublic 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];}}}}
日志查看
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