更新记录

3.1.0(2021-04-26)

  1. 修复设置开始播放时间bug;
  2. 修复部分情况下底层库冲突引起打包冲突问题;
  3. 统一截屏返回值

3.0.0(2021-04-06)

  1. 增加播放开始后,自定义播放器大小功能(内测);
  2. 下载支持多个视频并行下载;
查看更多

平台兼容性

Android iOS
适用版本区间:4.4 - 11.0 适用版本区间:9 - 14

原生插件通用使用流程:

  1. 购买插件,选择该插件绑定的项目。
  2. 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
  3. 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
  4. 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
  5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择


腾讯云点播播放器

该模块可以实现腾讯云直播拉流播放,支持直播播放、暂停、继续、停止等基本控制,同时可以根据需要监听相应的直播事件。

技术支持

原生模块本身使用复杂,音视频功能强大,造成接入难度不小。 模块测试、接入请联系我们。

我们的客服微信: ruanyunkeji001或ruanyunkeji002

接口列表

RY-TencentVodPlayer

函数 功能
init 初始化
setPlayerEventListener 设置播放器事件监听
start 开始播放
setRenderMode 设置渲染模式
setRenderRotation 设置图像渲染角度
pause 暂停播放
resume 恢复播放
stop 停止播放
seek 调整进度
snapshot 播放过程中本地截图
setRate 设置播放速率
setHwAcc 启用或者禁用硬件编解码
getSuppportBitreaes 返回支持的码率
setBitrateIndex 设置码率索引

RY-TencentVodPlayer-Downloader

函数 功能
init 初始化
setDownloadListener 设置下载监听器
startDownloadUrl 开始Url下载
startDownload 开始下载
stopDownload 停止下载
deleteDownloadFile 删除下载文件

快速开始

步骤一: 腾讯云配置

这个步骤比较繁琐,可以联系我们上文中的客服进行指引

注册或登录腾讯云账号,并开通云点播服务,您可以联系我们上方客服进进行测试和体验。

步骤二: 开始使用模块

  1. 新建nvue文件,注意该模块必须在nvue中使用 模块名称为: RY-TencentVodPlayer,使用标签
    <div class="player">
        <RY-TencentVodPlayer ref="vodPlayer" v-bind:style = "{ width: playerWidth, height: playerHeight }"></RY-TencentVodPlayer>
    </div>

备注: 可以在js的data()中声明播放器的宽度和高度,这样在代码中可以控制这两个参数的改变,可以参考

data() {
    return {
        playerWidth: 0,
        playerHeight: 0,
        url: 'http://12510499xxxx9wR5K0A.mp4',
        cacheFolderPath: 'vodPlayer/cahce',
        maxCacheItems: 3,
        pos: 10,
        seekValue: 60,
        renderMode: 0,
        renderRotation: 0,
        isMute: true,
        rate: 1.0,
        enableMirror: true,
        enableHwAcc: true,
        enableAutoplay: true,
        enableLoop: true,
        snapshotPath: 'snapshot/snapshot001.png',
        index: 0
    }
}
  1. 模块初始化

init({params}, ret) 初始化点播

var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
self.playerWidth = windowWidth;
self.playerHeight = windowWidth * 9 / 16;
this.$refs.vodPlayer.init({
    docPath: plus.io.convertLocalFileSystemURL('_doc'),
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

可以通过直接控制组件的宽度和高度来控制显示界面的大小,如果上面的playerWidth和playerHeight。

步骤三: 设置监听

setPlayerEventListener({}, ret) 设置播放器事件监听回调

ret:

回调 含义
BeginEvt 视频播放开始
EndEvt 视频播放结束
onGetMessageEvt 用于接收夹在音视频流中的消息
onNetDisconnectErr 网络断连,且经多次重连亦不能恢复,更多重试请自行重启播放
this.$refs.livePlayer.setPlayerEventListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 3: 启动播放

vodPlayer支持两种播放模式,您可以根据需要自行选择

  1. 通过url播放

start({params}, ret) 开始播放

params:

参数 含义
url 点播视频url
appId 应用的Id
fileId 上传成功后生成的fileId
rect 播放器显示坐标和区域
var self = this;
this.$refs.vodPlayer.start({
    rect: {
        x: 0, 
        y: 0, 
        w: self.playerWidth,
        h: self.playerHeight
    },
    url: self.url
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  1. 通过fileId方式

在 媒资管理 找到对应的文件。点开后在右侧视频详情中,可以看到 fileId。

var self = this;
this.$refs.vodPlayer.start({
    appId: self.appId, 
    fileId: self.fileId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

通过 fileId 方式播放,播放器会向后台请求真实的播放地址。如果此时网络异常或 fileId 不存在,则会收到PLAY_ERR_GET_PLAYINFO_FAIL事件,反之收到PLAY_EVT_GET_PLAYINFO_SUCC表示请求成功。

step 4: 画面调整

  • view:大小和位置 如需修改画面的大小及位置,直接调整 RY-TencentVodPlayer 的大小和位置,SDK 会让视频画面跟着您的 view 的大小和位置进行实时的调整。

  • setRenderMode:铺满或适应

setRenderMode({params}, ret) 设置图像渲染模式

params:

参数 含义
mode 渲染模式
var self = this;
this.$refs.vodPlayer.setRenderMode({
    mode: self.renderMode
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

|可选值|含义| |0| 将图像等比例铺满整个屏幕,多余部分裁剪掉,此模式下画面不会留黑边,但可能因为部分区域被裁剪而显示不全。| |1|将图像等比例缩放,适配最长边,缩放后的宽和高都不会超过显示区域,居中显示,画面可能会留有黑边。|

  • setRenderRotation:画面旋转

setRenderRotation({params}, ret) 设置图像的渲染角度

params:

参数 含义
rotation 旋转角度
var self = this;
this.$refs.vodPlayer.setRenderRotation({
    rotation: self.renderRotation
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
可选值 含义
0 home 在下面
1 home 在左边
2 home 在上面
3 home 在右边

画面

step 5: 播放控制

seek({params}, ret) 调整进度

params:

参数 含义
value 要跳转的进度
var self = this;
this.$refs.vodPlayer.seek({
    value: self.seekValue
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

pause({}, ret) 暂停

this.$refs.vodPlayer.pause({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

resume({}, ret) 恢复播放

this.$refs.vodPlayer.resume({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 6: 结束播放

结束播放时,如果要退出当前的 UI 界面,要记得用 removeVideoWidget 销毁 view 控件,否则会产生内存泄露或闪屏问题。

stop({}, ret) 停止播放

this.$refs.vodPlayer.stop({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 7: 屏幕截图

通过调用 snapshot 您可以截取当前视频为一帧画面,此功能只会截取当前直播流的视频画面,如果您需要截取当前的整个 UI 界面,请调用 iOS 的系统 API 来实现。

屏幕截图

snapshot({params}, ret) 快照

params:

参数 含义
path 快照路径
var self = this;
this.$refs.vodPlayer.snapshot({
    path: self.snapshotPath
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 8: 变速播放

点播播放器支持变速播放,通过接口setRate设置点播播放速率来完成,支持快速与慢速播放,如0.5X、1.0X、1.2X、2X等。

变速播放

setRate({param}, ret) 设置播放速率

params:

参数 含义
rate 播放速率
var self = this;
this.$refs.vodPlayer.setRate({
    rate: self.rate
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 9: 本地缓存 [UGC 版本暂不支持]

在短视频播放场景中,视频文件的本地缓存是很刚需的一个特性,对于普通用户而言,一个已经看过的视频再次观看时,不应该再消耗一次流量。

  • 格式支持 SDK 支持 HLS(m3u8)和 MP4 两种常见点播格式的缓存功能。

  • 何时开启? SDK 并不默认开启缓存功能,对于用户回看率不高的场景,也并不推荐您开启此功能。

  • 如何开启? 开启此功能需要配置两个参数:本地缓存目录及需要缓存的视频个数。

this.$refs.vodPlayer.init({
    cacheFolderPath: self.cacheFolderPath, 
    maxCacheItems: self.maxCacheItems,
    docPath: plus.io.convertLocalFileSystemURL('_doc'),
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 10: 预加载

在短视频播放场景中,预加载功能对于流畅的观看体验很有帮助:在观看当前视频的同时,在后台加载即将要播放的下一个视频 URL,这样一来,当用户真正切换到下一个视频时,已经不需要从头开始加载了,而是可以做到立刻播放。

这就是视频播放中无缝切换的背后技术支撑,您可以使用 TXVodPlayer 中的 isAutoPlay 开关来实现这个功能,具体做法如下:

预加载

var url_A = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f10.mp4";
player_A.setAutoPlay({
    isAutoPlay: true
}, ret => {
});
player_A.start({
    url: url_A
}, ret => {
});

var url_B = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f20.mp4"
player_B.setAutoPlay({
    isAutoPlay: false
}, ret => { 
});
player_B.start({
    url: url_B
}, ret => {
});

等到视频 A 播放结束,自动(或者用户手动切换到)视频 B 时,调用 resume 函数即可实现立刻播放。

if (eventType == 'End') {
    player_A.stop({}, ret => {
    });
    player_B.resume({}, ret => {
    });
}

step 11: 贴片广告

autoPlay 还可以用来做贴片广告功能,由于设置了 autoPlay 为 NO 之后,播放器会立刻加载但又不会立刻播放,因此可以在此时展示贴片广告,等广告播放结束,在使用 resume 函数立即开始视频的播放。

step 12: 加密播放 [UGC 版本暂不支持]

视频加密方案主要用于在线教育等需要对视频版权进行保护的场景。如果要对您的视频资源进行加密保护,就不仅仅需要在播放器上做改造,还需要对视频源本身进行加密转码,亦需要您的后台和终端研发工程师都参与其中。联系我们获取 视频加密解决方案 中您会了解到全部细节内容。

目前 vodPlayer 也是支持加密播放的,您可以使用通过 URL 携带身份认证信息的方案,该种方案下 SDK 的调用方式跟普通情况没有什么区别。 您也可以使用 Cookie 携带身份认证信息的方案,该种方案下,需要您通过 TXVodPlayConfig 中的 headers 字段设置 cookie 信息于 HTTP 请求头中。

step 13: HTTP-REF [UGC 版本暂不支持]

headers 可以用来设置 HTTP 请求头,例如常用的防止 URL 被到处拷贝的 Referer 字段(腾讯云可以提供更加安全的签名防盗链方案),以及用于验证客户端身份信息的 Cookie 字段。

this.$refs.vodPlayer.init({
    headers: {
        ...
    },
    docPath: plus.io.convertLocalFileSystemURL('_doc'),
}, ret => {
});

step 14: 硬件加速

对于蓝光级别(1080p)的画质,简单采用软件解码的方式很难获得较为流畅的播放体验,所以如果您的场景是以游戏直播为主,一般都推荐开启硬件加速。

软解和硬解的切换需要在切换之前先 stop,切换之后再 start,否则会产生比较严重的花屏问题。

setHwAcc({params}, ret) 启用或者禁用硬件编解码

params:

参数 含义
isHwAcc 是否启用硬件解码
var self = this;
this.$refs.vodPlayer.setHwAcc({
    isHwAcc: self.enableHwAcc
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step 15: 多码率文件 [UGC 版本暂不支持]

SDK 支持 hls 的多码率格式,方便用户切换不同码率的播放流。在收到 PLAY_EVT_PLAY_BEGIN 事件后,可以通过下面方法获取多码率数组

getSuppportBitreaes({}, ret) 返回支持的码率(清晰度)

var self = this;
this.$refs.vodPlayer.getSupportedBitrates({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

在播放过程中,可以随时通过-[TXVodPlayer setBitrateIndex:]切换码率。切换过程中,会重新拉取另一条流的数据,因此会有稍许卡顿。SDK 针对腾讯云的多码率文件做过优化,可以做到切换无卡顿。

setBitrateIndex({params}, ret) 设置当前正在播放的码率索引

params:

参数 含义
index 码率的索引
var self = this;
this.$refs.vodPlayer.setBitrateIndex({
    index: self.index
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

进度展示

点播进度分为两个指标:加载进度和播放进度,目前是以事件通知的方式将这两个进度实时通知出来的。

您可以为vodPlayer对象绑定一个 setPlayerEventListener 监听器,进度通知会通过 Progress 事件回调到您的应用程序,该事件的附加信息中即包含上述两个进度指标。

进度

if (eventType == 'Progress') {
    var playable = ret.playable;
    var progress = ret.progress;
}

事件监听

除了 PROGRESS 进度信息,SDK 还会通过事件通知同步给您的应用程序很多其它的信息:

  1. 播放事件
事件名称 含义说明
Begin 视频播放开始,如果有转菊花什么的这个时候该停了
Progress 视频播放进度,会通知当前播放进度、加载进度和总体时长
Loading 视频播放 loading,如果能够恢复,之后会有 onVodLoadingEnd 事件
onVodLoadingEnd 视频播放 loading 结束,视频继续播放
  1. 结束事件
事件名称 含义说明
End 视频播放结束
onErrNetDisconnect 网络断连,且经多次重连亦不能恢复,更多重试请自行重启播放
onErrHlsKey HLS 解密 key 获取失败
  1. 分辨率事件
事件名称 含义说明
onChangeResolution 视频分辨率改变
onChangeRotation MP4 视频旋转角度

离线下载

点播离线播放是一个非常普遍的需求,用户可以在有网络的地方先下载好视频,等到了无网络的环境可以再次观看。SDK 提供了播放本地文件的能力,但仅限于 mp4 和 flv 这种单一文件格式,HLS 流媒体因为无法保存到本地,所以不能本地播放。现在,您可以通过RY-TencentVodPlayer-Downloader将 HLS 下载到本地,以实现离线播放 HLS 的能力。

step1: 准备工作

加载下载模块,并初始化配置

var downloader = uni.requireNativePlugin("RY-TencentVodPlayer-Downloader");
return {
    url: 'http://1251049xxxxxx0210.m3u8',
    appId: 125xxxx11,
    fileId: '52858xxxxx4527',
    path: 'vodDownloader',
    mediaKey: '',
    filePath: ''
}

init({}, ret) 初始化下载

downloader.init({
    docPath: plus.io.convertLocalFileSystemURL('_doc')
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step2: 开始下载

开始下载有两种方式:url 和 fileid。

  • url 方式非常简单,只需要传入下载地址即可

startDownloadUrl({params}, ret) url下载

params:

参数 含义
url 下载url
var self = this;
downloader.startDownloadUrl({
    url: self.url
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  • fileid 下载至少需要传入 appId 和 fileId

startDownload({params}, ret) 开始下载

参数 含义
appId 应用Id
fileId 文件Id
var self = this;
downloader.startDownload({
    appId: self.appId, 
    fileId: self.fileId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

step3: 任务信息

在接收任务信息前,需要先设置回调监听。

setDownloadListener({}, ret) 设置下载监听

ret:

回调 含义
onDownloadStart 任务开始
onDownloadProgress 任务进度
onDownloadStop 下载停止
onDownloadFinish 下载完成
onDownloadError 下载错误
downloader.setDownloadListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

由于 downloader 可以同时下载多个任务,所以回调接口里带上了mediaInfo对象,您可以访问 url 或 dataSource 判断下载源,同时还可以获取到下载进度、文件大小等信息。

step4: 中断下载

停止下载请调用stopDownload方法,参数为startDownloadUrl或startDownload返回的mediaKey。SDK 支持断点续传,当下载目录没有发生改变时,下次下载同一个文件时会从上次停止的地方重新开始。

如果您不需要重新下载,请调用deleteDownloadFile方法删除文件,以释放存储空间。

stopDownload({params}, ret) 停止下载

params:

|参数|含义| |mediaKey|媒体信息键|

var self = this;
downloader.stopDownload({
    mediaKey: self.mediaKey
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

deleteDownloadFile({params}, ret) 删除下载文件

params:

|参数|含义| |path|下载路径|

this.downloader.deleteDownloadFile({
    path: self.path
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
})

更多功能

获取内测功能和技术支持, 请联系我们客户微信: ruanyunkeji001或ruanyunkeji002

  • 高级参数(内测)
  • 播放器高级控制(内测)
  • 更多事件回调

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android: android.permission.INTERNET android.permission.ACCESS_NETWORK_STATE android.permission.ACCESS_WIFI_STATE android.permission.SYSTEM_ALERT_WINDOW android.permission.WRITE_EXTERNAL_STORAGE android.permission.READ_EXTERNAL_STORAGE iOS: 无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件使用的腾讯云点播SDK会采集数据,详情可参考:https://cloud.tencent.com/document/product/881

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问