云点播 超级播放器 TCPlayer

注意：说明：

二、基础知识

对接前需要了解如下基础知识：

·直播和点播
直播视频源是实时的，一旦主播停播，直播地址就失去意义，而且由于是实时直播，所以播放器在播直播视频的时候是没有进度条的。
点播视频源是某个服务器上的文件，只要文件没有被提供方删除，就可以随时播放， 而且由于整个视频都在服务器上，所以播放器在播点播视频的时候是有进度条的。

·协议支持
TCPlayerLite 的视频播放能力本身不是网页代码实现的，而是靠浏览器支持，所以其兼容性不像我们想象的那么好，因此，不是所有的手机浏览器都能有符合预期的表现。一般用于网页直播的视频源地址是以 M3U8 结尾的地址，我们称其为 HLS (HTTP Live Streaming)，这是苹果推出的标准，目前各种手机浏览器产品对这种格式的兼容性也最好，但它有个问题：延迟比较大，一般是20s – 30s左右的延迟。

注意：在不支持 WebRTC 的浏览器环境，传入播放器的 WebRTC 地址会自动进行协议转换来更好的支持媒体播放，默认在移动端转换为 HLS，PC 端转换为 FLV。

功能支持

四、Step1. 页面准备工作

在需要播放视频的页面（PC 或 H5）中引入初始化脚本。

<script src="https://xxx.com/player/tcplayerlite/release/v2.4.5/TcPlayer-2.4.5.js" charset="utf-8"></script>;

建议在使用播放器 SDK 的时候自行部署资源，单击下载播放器资源。

如果你部署的地址为 aaa.xxx.ccc，在合适的地方引入播放器脚这篇件：

<script src="aaa.xxx.ccc/TcPlayer-x.x.x.js"></script>

注意：直接用本地网页无法调试，Web 播放器无法处理该情况下的跨域问题。

五、Step2. 在 HTML 中放置容器

在需要展示播放器的页面位置加入播放器容器，即放一个 div 并命名，例如 id_test_video，视频画面都会在容器里渲染。对于容器的大小控制，你可以使用 div 的属性进行控制，示例代码如下：

<div id="id_test_video" style="width:100%; height:auto;"></div>

六、Step3. 对接视频播放

编写 Javascript 代码，作用是去指定的 URL 地址拉取音视频流，并将视频画面呈现到添加的容器内。

七、3.1 简单播放

如下是一个 直播格式的 URL 地址，使用 HLS（M3U8）协议，如果主播在直播中，则用 VLC 等播放器是可以直接打开该 URL 进行观看的：

http://2157.liveplay.myqcloud.com/2157_358535a.m3u8 // m3u8 播放地址


如果要在手机浏览器上播放该 URL 的视频，则 Javascript 代码如下：

var player = new TcPlayer('id_test_video', { "m3u8": "http://2157.liveplay.myqcloud.com/2157_358535a.m3u8", //请替换成实际可用的播放地址 "autoplay" : true, //iOS 下 safari 浏览器，以及大部分移动端浏览器是不开放视频自动播放这个能力的 "poster" : "http://www.test.com/myimage.jpg", "width" : '480',//视频的显示宽度，请尽量使用视频分辨率宽度 "height" : '320'//视频的显示高度，请尽量使用视频分辨率高度});

这段代码可以支持在 PC 及手机浏览器上播放 HLS（M3U8）协议的直播视频，虽然 HLS（M3U8）协议的视频兼容性不错，但部分 Android 手机依然不支持，其延迟较高，大约20秒以上的延迟。

八、3.2 实现更低延迟

var player = new TcPlayer('id_test_video', { "m3u8": "http://2157.liveplay.myqcloud.com/2157_358535a.m3u8", "flv": "http://2157.liveplay.myqcloud.com/live/2157_358535a.flv", //增加了一个 flv 的播放地址，用于PC平台的播放 请替换成实际可用的播放地址 "autoplay" : true, //iOS 下 safari 浏览器，以及大部分移动端浏览器是不开放视频自动播放这个能力的 "poster" : "http://www.test.com/myimage.jpg", "width" : '480',//视频的显示宽度，请尽量使用视频分辨率宽度 "height" : '320'//视频的显示高度，请尽量使用视频分辨率高度});

这段代码中增加了 FLV 的播放地址，Web 播放器如果发现当前的浏览器是 PC 浏览器，会主动选择 FLV 链路，从而实现更低的延迟。如果对延迟有更高的要求，可以使用 WebRTC 拉流地址，基于 WebRTC 的播放系统可以实现超低延迟（500ms），前提条件是拉流地址都是可以出流的，如果你使用腾讯云的视频直播服务，则无需考虑，因为腾讯云的直播频道默认支持 WebRTC、FLV 和 HLS（M3U8）播放协议。

九、无法播放怎么办？

如果你发现视频无法播放，可能存在如下原因：

·原因一：视频源有问题
如果是直播 URL，则需要检查主播是否已经停止推流，可以用浮窗提示观众：“主播已经离开”。请参见 直播推流。
如果是点播 URL，则需要检查要播放的文件是否还存在于服务器上（如播放地址是否已经从点播系统移除）。

·原因二：本地网页调试

·目前 TCPlayerLite 不支持本地网页调试（即通过 file://协议打开视频播放的网页），因为浏览器有跨域安全限制，所以在 Windows 系统上放置一个 test.html 文件来进行测试是无法播放的，需要将其上传到服务器上进行测试。而前端工程师可以通过反向代理的方式，对线上页面进行本地代理以实现本地调试，这是主流的本地调试方法。

·原因三：手机兼容问题
普通的手机浏览器只支持 HLS（M3U8）协议的播放，不支持 FLV ，最新版本的 QQ 浏览器支持 FLV 协议的播放。

十、Step4. 给播放器设置封面

设置封面涉及到 poster 属性，下面将详细介绍 poster 属性的使用方法。

注意：封面功能在部分移动端播放环境下可能失效，通常是由于移动端 webview 劫持视频播放造成的，需要 webview 支持 video 叠加元素或者放开劫持视频播放。相关详细说明请参见 常见问题。

十一、4.1 简单设置封面

poster 支持传入图片地址作为播放器的封面，在播放器区域内居中，并且以图片的实际分辨率进行显示。

"poster" : "http://www.test.com/myimage.jpg"

十二、4.2 设置封面样式

poster 支持传入一个对象，在对象中可以对封面的展现样式（style）和图片地址（src）进行设置。

style 支持的样式如下：

·default：居中并且以图片的实际分辨率进行显示。

·stretch：拉伸铺满播放器区域，图片可能会变形。

·cover：优先横向等比拉伸铺满播放器区域，图片某些部分可能无法显示在区域内。

"poster" : {"style":"stretch", "src":"http://www.test.com/myimage.jpg"}

十三、4.3 实现用例

使用 cover 方式显示封面。线上示例如下，在 PC 浏览器中右键单击查看页面源码即可查看页面的代码实现：
视频封面

十五、5.1 原理介绍

同腾讯视频，Web 播放器支持多清晰度：


播放器本身是没有能力去改变视频清晰度的，视频源只有一种清晰度，称之为原画，而原画视频的编码格式和封装格式多种，Web 端无法支持播放所有的视频格式，如点播支持以 H.264 为视频编码，MP4 和 FLV 为封装格式的视频。

多清晰度的实现依赖于视频云：

·对于直播，来自主播端的原始视频会在腾讯云进行实时转码，分出多路转码后的视频，每一路视频都有其对应的地址，例如“高清-HD”和“标清-SD”，地址格式如下：

http://2157.liveplay.myqcloud.com/2157_358535a.m3u8 // 原画http://2157.liveplay.myqcloud.com/2157_358535a_900.m3u8 // 高清http://2157.liveplay.myqcloud.com/2157_358535a_550.m3u8 // 标清

·对于点播，一个视频文件上传到腾讯云后，你可以对该视频文件进行转码，产生其它几种清晰度的视频，例如“高清-HD”和“标清-SD”，地址格式如下：

http://200002949.vod.myqcloud.com/200002949_b6ffc.f240.m3u8 // 原画，用转码后的超清替换http://200002949.vod.myqcloud.com/200002949_b6ffc.f230.av.m3u8 // 高清http://200002949.vod.myqcloud.com/200002949_b6ffc.f220.av.m3u8 // 标清

注意：上传后的原始视频是未经过腾讯云转码的，不能直接用于播放。

十六、5.2 代码实现

多清晰度支持的代码实现如下所示：

var player = new TcPlayer('id_test_video', { "m3u8" : "http://200002949.vod.myqcloud.com/200002949_b6ffc.f240.m3u8",//请替换成实际可用的播放地址 "m3u8_hd" : "http://200002949.vod.myqcloud.com/200002949_b6ffc.f230.av.m3u8", "m3u8_sd" : "http://200002949.vod.myqcloud.com/200002949_b6ffc.f220.av.m3u8", "autoplay" : true, //iOS 下 safari 浏览器，以及大部分移动端浏览器是不开放视频自动播放这个能力的 "poster" : "http://www.test.com/myimage.jpg",});

十七、5.3 实现用例

使用多种分辨率的设置及切换功能。线上示例如下，在 PC 浏览器中右键单击查看页面源码即可查看页面的代码实现：分辨率切换
正常情况将看到如下效果：


十八、Step6. 定制错误提示语

Web 播放器支持提示语定制。

十九、6.1 代码实现

如下是让播放器支持自定义提示语的核心代码，主要在 wording 属性上设置提示语。

var player = new TcPlayer('id_test_video', { "m3u8" : "http://200002949.vod.myqcloud.com/200002949_b6ffc.f0.m3u8",//请替换成实际可用的播放地址 "autoplay" : true, //iOS 下 safari 浏览器是不开放这个能力的 "poster" : "http://www.test.com/myimage.jpg", "wording": { 2032: "请求视频失败，请检查网络", 2048: "请求m3u8文件失败，可能是网络错误或者跨域问题" }});

20、6.2 实现用例

视频播放失败，同时使用自定义提示文案的功能。线上示例如下，在 PC 浏览器中右键单击查看页面源码即可查看页面的代码实现：

https://web.sdk.qcloud.com/player/tcplayerlite/tcplayer-error.html

注意：以上示例链接仅用于文档演示，请勿用于生产环境。

21、6.3 错误码表

注意：说明：

22、源码参考

如下是一个线上示例代码，在 PC 浏览器中右键单击查看页面源码即可查看页面的代码实现：播放示例。

注意：以上示例链接仅用于文档演示，请勿用于生产环境。

23、参数列表

播放器支持的所有参数，如下所示：

24、实例方法列表

播放器实例支持的方法，如下所示：

注意：以上方法必须是 TcPlayer 的实例化对象，且需要初始化完毕才可以调用（即 load 事件触发后）。

25、进阶攻略

下面介绍播放器 SDK 的进阶使用方法。

26、开启优先 H5 播放模式

TCPlayerLite 根据不同的播放环境，播放器会选择默认最合适的播放方案。

27、监听事件

TCPlayerLite 以 H5<video>的规范，对播放事件做了一定程度的转换，以实现播放事件命名的统一，TcPlayer 对原生事件进行了捕获和透传。

·H5 事件参考列表

·统一后的事件列表：

errortimeupdateloadloadedmetadataloadeddataprogressfullscreenplayplayingpauseendedseekingseekedresizevolumechangewebrtcstatupdatewebrtcwaitstartwebrtcwaitendwebrtcstop

在非自动播放的条件下，加载视频至待播放状态，移动端和 PC 触发的事件区别。

·移动端：

·PC：

注意：说明：

注意：以上是两种平台的差异，然而在移动端的各种设备和 App 之间同样存在差异。

事件监听函数返回的 msg 对象介绍：

应用案例：通过事件监听，可以进行播放失败重连，单击访问 在线案例。

28、案例展示

结合了 TcPlayer 和即时通信 IM 的腾讯云 Web 直播互动组件：体验地址。

29、更新日志

TCPlayerLite 在不断更新及完善中，下面是 TCPlayerLite 发布的主版本介绍。