tencent cloud

云点播

动态与公告
产品动态
公告
产品简介
产品概述
产品特性
产品功能
产品优势
应用场景
解决方案
专业版
云点播专业版简介
快速入门
控制台指南
开发指南
购买指南
计费概述
计费方式
购买指引
账单查询
续费说明
欠费说明
退费说明
快速入门
控制台指南
控制台介绍
服务概览
应用管理
媒体管理
资源包管理
License 管理
实时日志分析
实践教程
媒体上传
如何将点播的媒体文件进行智能降冷
媒体处理
分发播放
如何接收事件通知
如何进行源站迁移
直播录制
如何进行自定义源站回源
直播精彩剪辑固化至云点播 VOD 指引
如何使用 EdgeOne 分发云点播内容
开发指南
媒体上传
媒体加工处理
媒体 AI
事件通知
媒体分发播放
媒体加密与版权保护
播放频道
访问管理
下载媒体文件
应用体系
错误码
播放器 SDK 文档
概述
基本概念
产品功能
Demo 体验
免费测试
购买指南
SDK 下载
License 指引
播放器教程
含 UI 集成方案
无 UI 集成方案
高级功能
API 文档
第三方播放器插件
Player SDK Policy
服务端 API 文档
History
Introduction
API Category
Other APIs
Media Processing APIs
Task Management APIs
Media Upload APIs
Media Management APIs
Event Notification Relevant API
Media Categorization APIs
Domain Name Management APIs
Distribution APIs
AI-based Sample Management APIs
Region Management APIs
Data Statistics APIs
Carousel-Related APIs
Just In Time Transcode APIs
No longer recommended APIs
Making API Requests
AI-based image processing APIs
Parameter Template APIs
Task Flow APIs
Data Types
Error Codes
Video on Demand API 2024-07-18
常见问题
移动端播放问题
费用相关问题
视频上传问题
视频发布问题
视频播放问题
Web 端播放问题
全屏播放问题
数据统计问题
访问管理相关问题
媒资降冷问题
相关协议
Service Level Agreement
VOD 政策
隐私政策
数据处理和安全协议
联系我们
词汇表

VR 播放插件

PDF
聚焦模式
字号
最后更新时间: 2026-02-26 17:10:51

功能简介

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 licenseUrl = "填入您购买的 License 的 URL";
String licenseKey = "填入您购买的 License 的 Key"
TXLiveBase.getInstance().setLicence(context, licenseUrl, licenseKey);
NSString *licenseURL = "填入您购买的 License 的 URL";
NSString *licenseKey = "填入您购买的 License 的 Key"
[TXLiveBase setLicenceURL:licenseURL 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全景视频单目模式,如需开启双目模式,vaule设为“12”即可
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 11);
}


}


//关闭终端VR全景视频
mVodPlayer.setStringOption("PARAM_MODULE_TYPE", 0);
//开启VR全景视频单目模式,如需开启双目模式vaule设为“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配置字典,用于存放具体的VR参数
Map<String, Object> config = new HashMap<>();
// 关闭传感器(陀螺仪),设置为false表示不通过设备转动改变视角
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ENABLE_SENSOR, false);
// 设置视场角为90度,取值范围30.0f-110.0f度,默认65.0f度
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_FOV, 90.0f);
// 设置手势滑动距离与角度比例,比例越大灵敏度越高,默认值为1/8f
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_RATE, 0.2f);
// 设置旋转XY角度斜率阈值为0.3,默认值0.5f,阈值范围内只选取长边旋转
config.put(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_VR_ANGLE_SLOPE_THRESHOLD, 0.3f);
// 将VR配置字典应用到播放器
mVodPlayer.setStringOption(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_CONFIG, config);
// 设置VR类型为全景单目模式(如需双目模式,使用PLAYER_OPTION_PARAM_MODULE_TYPE_VR_BINOCULAR)
mVodPlayer.setStringOption(TXVodConstants.PLAYER_OPTION_PARAM_MODULE_TYPE,
TXVodConstants.PLAYER_OPTION_PARAM_MODULE_TYPE_VR_PANORAMA);
// 启播
int result = mVodPlayer.startVodPlay(playUrl);
// 创建扩展信息字典,用于存放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] PLUGIN: did update monet module, result = 1
3. 如果出现下面的日志,表示签发的 License 不合法:
[MonetProcessor] Monet License invalid, error, set module is null


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈