Web点播播放器1.0——腾讯sdk网页点播播放器

https://www.qcloud.com/document/product/267/5706

功能介绍

本文档是介绍腾讯云视频点播服务的网页播放器（Web SDK）的使用说明，它可帮助腾讯云客户直接使用经过验证的视频播放能力，通过灵活的接口，快速同自有Web应用集成，以实现桌面应用播放功能。同时本SDK还提供在WEB端上传视频的能力。

该SDK所播放的文件受限于全局防盗链功能定义。详细内容请查看官网FAQ安全功能相关说明。

该文档面向考虑使用腾讯云视频点播播放器Web SDK进行开发并具备Javascript语言基础的开发人员。

能力支持

播放格式

WEB SDK播放视频格式支持：

播放格式	PC浏览器环境	手机浏览器环境
HLS（m3u8）	支持	支持
MP4	支持	支持
FLV	不支持	不支持

Android 系统兼容性问题
不像iPhone上只有一个Safari浏览器，Android上的系统标配浏览器有非常多的实现版本，所以Android手机浏览器的兼容是一个业界难题，故此表格中所示的手机浏览器格式支持情况比不适用于所有Android手机。

上传格式

SDK上传视频格式支持：

标准格式	详细格式
微软格式	WMV，WM，ASF，ASX
REAL格式	RM, RMVB，RA，RAM
MPEG格式	MPG，MPEG，MPE，VOB，DAT
其他格式	MOV，3GP，MP4，MP4V，M4V，MKV，AVI，FLV，F4V

点播平台的转码服务
由于MP4和HLS（m3u8）是目前在PC浏览器和手机浏览器上支持程度相对较好的格式，所以腾讯云的视频点播平台最终会把上传的视频发布为 MP4和HLS（m3u8）格式。

平台兼容

为手机浏览器和PC浏览器写两套代码是非常吃力的事情，但如果您使用本款播放器，同一段代码可以自动实现PC浏览器和手机浏览器的自适应切换，播放器内部会自动区分平台使用最优的播放方案。例如：PC平台优先使用Flash 播放器以适应多种视频格式的情况，而手机浏览器上会使用HTML5技术实现视频播放。

准备工作

step1 :开通服务

首先您需要注册一个腾讯云账号，然后开通点播服务。

step2 :上传文件

点播服务开通之后，进入点播视频管理就可以上传新的视频文件了，因为我们本篇文档主要介绍播放器的使用，所以这样做是为了让您先有个自己的在线视频地址。如果您没有开通点播服务，这个页面是进不去的。

step3 :获取ID

上传完视频之后，您就可以视频管理页面查到文件的id了，这个是播放器播放视频的最基本信息，与此同时，本款播放器有质量统计功能，在使用之前需要先确认APPID，您的APPID也可以在视频管理页面查看到。

下图中的两个ID，左边一个是视频文件的ID，另一个就是您的APPID了。

step4 :页面准备

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

<script src="//qzonestyle.gtimg.cn/open/qcloud/video/h5/h5connect.js" charset="utf-8"></script>;

本地文件限制
本地文件是不能用这款播放器播放的，因为有跨域问题，播放器一定要挂IP或者域名访问，这也是为什么需要您先上传一个视频文件获取在线播放地址的原因。

添加播放器

经过下面两个简单的步骤，您就可以在您的网页上添加一个视频播放器了。

step 1 :添加播放器容器

在需要展示播放器的页面位置加入播放器容器，例如：在index.html中加入如下代码（容器id以及宽高都可以自定义）

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

step 2 :创建Player 对象

接下来在页面引入的Javascript脚本中，创建一个播放器对象，这时将使用播放器的构造函数

var player = new qcVideo.Player("id_video_container", {
    "file_id": "1465197896261041838",
    "app_id": "125132611",
    "width":640,
    "height":480
});

该构造函数将会生成一个播放器对象，并且根据file_id和app_id找到对应的视频进行播放，您可以使用播放器对象player 对播放器进行控制。播放器对象的参数选项下方API方法总览有详细介绍。

完整实例代码

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0"/>
    <title>点播</title>
</head>
<body>
<div id="id_video_container" style="width:100%; height:auto;"></div>
<script src="//qzonestyle.gtimg.cn/open/qcloud/video/h5/h5connect.js" charset="utf-8"></script>
<script type="text/javascript">
    (function () {
        var player = new qcVideo.Player("id_video_container", {
            "file_id": "1465197896261041838",
            "app_id": "125132611",
            "width":640,
            "height":480
        });
    })()
</script>
</body>
</html>

API方法总览

1.构造函数

qcVideo.Player(id, option, listener);

id: String ; 必选参数 ;
页面放置播放器的容器ID，可以自由定义。

option: Object ; 必选选参数 ;
播放器的参数设置选项，具体选项有:

参数	类型	默认值	参数说明
file_id	String	无	用视频ID播放方式为必选参数，为该点播文件的唯一标识
app_id	String	无	条件同上为必选参数，同一个账户下的视频，该参数是相同的
width	Number	无	必选，例如：640，设置播放器宽度，单位为像素
height	Number	无	必选，例如：480，设置播放器高度，单位为像素
auto_play	Number	0	是否自动播放，0: 不自动，1: 自动播放备注：该选项只对PC平台Flash播放器生效
disable_full_screen	Number	0	是否允许全屏播放，0: 支持全屏播放，1: 禁用全屏播放备注：该选项只对PC平台Flash播放器生效
disable_drag	Number	0	是否允许拖动时间轴，0: 允许拖拽，1: 禁止拖拽备注：该选项只对PC平台Flash播放器生效
stretch_full	Number	0	是否等比拉伸视频至铺满播放器0: 不拉伸,1: 拉伸全屏备注：该选项只对PC平台Flash播放器生效
stop_time	Number	无	试看功能，例如设置：60，60秒后停止播放，并且触发“playStatus”事件
remember	Number	0	是否开启续播功能，0：关闭，1：开启，开启后将会记录这个视频上一次未看完的时间点，下一次继续播放。备注：该选项只对PC平台Flash播放器生效
playbackRate	Number	1	变速播放，例如设置2表示2倍速度播放，0.5表示慢正常速度一倍播放。备注：该选项暂时只对H5播放器生效
hide_h5_setting	Boolean	false	是否隐藏H5的设置按钮，true：隐藏，false：不隐藏
hide_h5_error	Boolean	false	是否隐藏H5的错误提示，备注：该选项暂时只对H5播放器生效
WMode	String	window	Window模式不支持其他页面元素覆盖在flash播放器上面，如需要可以修改为opaque 或其他flash wmode的参数值。备注：该选项只对PC平台Flash播放器生效
stretch_patch	Boolean	false	设置为true时，支持将开始、暂停、结束时的图片贴片铺满播放器。
definition	Number	无	可以指定播放视频的清晰度，首先需要视频拥有改清晰度可选值有： 10、20、30、40、210、220、230、240，具体对应哪种视频可以参考third_video的参数说明。
videos	Array	无	开启防盗链后，可以通过设置videos的可访问的视频地址，支持播放器播放；清晰度类型通过url与后台查出的url前缀匹配得到。详情请查看防盗链功能使用指南例如：[“http://xxx.myqcloud.com/xxxyy\_f220.m3u8?sign=xxx”， ... ]
third_video	Object	无	该选项只用于视频文件播放地址的情形参数例子：{ ‘duration’: 20 , //视频时长(单位秒)，可选参数，没有传的情况下在视频加载MetaData后自动更新视频时长。注意：如果是播放mp4，这个时长数据是必须的 ‘urls’ : { //(至少包含一个地址，注意对应视频格式) 　　　10 : “mp4手机视频地址”, 　　　20 :“mp4标清视频地址”, 　　　30 : “mp4高清视频地址”, 　　　40 : “mp4超清视频地址”, 　　　210 : “hls手机视频地址”, 　　　220 : “hls标清视频地址”, 　　　230 :“hls高清视频地址”, 　　　240 : “hls超清视频地址” 　　} } 备注：如果在 Chrome 等PC浏览器中模拟移动设备，需要有 mp4 视频地址才可以播放。

listener : Object ; 可选参数 ; 播放状态变化回调函数列表

函数名称	类型	说明
fullScreen	function	全屏/退出全屏时触发，回调函数的参数 isFullScreen:Boolean 返回值： true全屏 ; false 退出全屏例子：`function(isFullScreen){ ... }` 备注：该事件只对PC平台Flash播放器生效
playStatus	function	播放状态变更时触发，回调函数的参数 status：String 返回值：ready: “播放器已准备就绪”,seeking:”搜索”, suspended:”暂停”, playing:”播放中” , playEnd:”播放结束” , stop: “试看结束触发” , error: “h5播放出现错误时触发” 例子：function(status, msg){ ... }
dragPlay	function	拖动播放位置变化时触发； second：Number 返回值：拖动播放的位置（单位秒）例子： `function(second){ ... }` 备注：该事件只对PC平台Flash播放器生效

2.获取参数和状态

构造函数返回的播放器对象具有以下获取参数和状态的方法

方法名	返回值	说明
getVolume	Number，取值范围（0 到 1）	获取当前音量
getDuration	Number，单位秒	获取当前视频总时长
getCurrentTime	Number，单位秒	获取当前播放位置
isSeeking	Boolean ; true 为”加载中”	当前播放状态是否 “加载中”
isSuspended	Boolean ; true 为”暂停中”	当前播放状态是否 “暂停中”
isPlaying	Boolean ; true 为”播放中”	当前播放状态是否 “播放中”
isPlayEnd	Boolean ; true 为”播放结束”	当前播放状态是否 “播放结束”
getWidth	Number(int)	获取当前播放器宽度
getHeight	Number(int)	获取当前播放器高度
getClarity	Number(int) ( 1:”手机”, 2:“标清”, 3:“高清”, 4:“超清”)	获取当前视频的清晰度
getAllClaritys	Array<int> ( 1:”手机”, 2:“标清”, 3:“高清”, 4:“超清”)	获取当前视频全部的清晰度

3.设置和动作

构造函数返回的播放器对象具有以下设置方法

方法	说明
resize(width,height)	参数：width :int；height :int 功能：设置当前播放器宽度高度返回：无
play(second)	参数：second：int单位秒功能：开始播放，可以设置开始播放指定时间点返回：Int 返回码备注：在传视频地址播放的情况下，second只能传空值或者0
pause()	功能：暂停当前播放的视频返回：Int 返回码
resume()	功能：恢复播放视频返回：Int 返回码
setClarity(clarity)	参数：clarity：int 清晰度取值范围（1：”手机”,2：”标清”,3：”高清”,4：”超清”）功能：更换视频清晰度返回：Int 返回码注意：clarity指定的清晰度，请确保当前视频具备该清晰度，否则将按播放器默认规则选择一个清晰度播放
changeVideo(opt)	参数： opt Object ; 包含将要播放的视频的基本信息，和构造函数第二个参数基本一致，具体参考构造函数说明; 功能：动态更换视频返回：Int 返回码
addBarrage(barrage)	参数：barrage：Array 弹幕信息 [{ "type":"content", //消息类型 ,content:普通文本 (必选) "content":"hello world", //文本消息 (必选) "time":"1.101",//单位秒，表示距离当前调用添加字幕的时间多久后，开始显示该条字幕 (必选) "style": "C64B03;35",// 分号分割，第一项颜色值，第二项字体大小 (可选) "postion":"center" //固定位置 center: 居中，bottom: 底部， up: 顶上 (可选) }, ... ] 功能：添加弹幕返回：Int 返回码备注：弹幕仅在前端实现，后台功能请自行开发。该功能只在PC Flash播放器中生效
closeBarrage()	功能：关闭弹幕，关闭后重新调用addBarrage可开启弹幕。返回：Int 返回码备注：弹幕仅在前端实现，后台功能请自行开发。该功能只在PC Flash播放器中生效

这些设置方法的统一返回码是：

错误码	含义
200	操作成功
0	播放器未完全初始化
-1	动态更换失败视频，缺少必要参数
-2	未知操作命令
-3	播放时间超出有效播放范围

视频文件上传功能

用户可以使用点播Web SDK上传视频，以帮助腾讯云视频用户通过Web上传视频文件。

该SDK当前支持HTML5上传（不支持HTML5的浏览器暂不支持上传）

具体操作方法请阅：http://video.qcloud.com/sdk/upload.html

问题排查

错误码列表

SDK使用过程中出现的异常code对照表，如遇到未在列表中的异常code，请联系我们的客服，客服会安排工程师进行解决。

Code	说明
1003	密码错误
10000	请求超时(拉取播放器配置信息与视频信息超时，请检查网络重试，超时时间为10s)
10001	数据解析失败(拉取播放器配置信息与视频信息获取到的数据解析失败，可能是网络问题或者服务器异常)
10002	连接超时，请稍后再试(拉取播放器配置信息与视频信息失败，可能是网络问题或者服务器异常)
10008	APPID或 File ID错误
11044	缺少APPID
11045	缺少File ID
11046	缺少密码

常见问题

为什么H5播放视频拉伸变形了？

解答：H5并不具备拉伸视频的能力，请检查播放器的容器宽高是否设置正确
QQ浏览器显示下载视频，怎么屏蔽？

解答：手机QQ浏览器的内核限制，JS无法干预，同样在UC等浏览器的内核也提供了自动嗅探视频提供下载的功能。需要联系浏览器开发商进行关闭。
QQ浏览器下无法在盖住视频

解答：浏览器接管了H5的视频播放功能，X5内核视频播放使用了自研的播放器，考虑用户体验，浏览器使用了统一的播放界面。相关信息参考QQ浏览器文档说明
在调用isPlaying()等方法时没有获取到正确的状态信息

解答：在移动端的某些浏览器和webview中，播放视频会被浏览器自带的内核接管，sdk将无法获得正确的播放状态。
设置了自动播放，但在移动端无法自动播放？

解答：目前大部分手机浏览器由于数据流量等原因，默认不自动加载媒体文件，播放视频时需要用户触发操作。
iOS系统下视频自动全屏播放

解答：iOS系统由于webkit设置原因，默认视频全屏播放，如果您的视频需要在APP内实现内联播放，可以设置webkit-playsinline属性。目前iOS10以下版本的Safari无法禁止视频自动全屏。
为什么在 PC Chrome 中Flash播放器会有两个播放按钮？

解答：从Chrome 42版本开始将不再自动播放Flash, 只对主要的Flash内容进行自动播放，其它的Flash内容将被暂停播放，除非用户决定去手动点开它。

posted @ 2017-07-31 11:01 STN_LCD 阅读(2579) 评论(0) 编辑收藏举报

刷新页面返回顶部