Web

最近更新时间:2024-09-05 10:49:01

我的收藏
本文档是介绍适用于直播和点播播放的 Web 播放器( TCPlayer )的相关参数以及 API。本文档适合有一定 Javascript 语言基础的开发人员阅读。

初始化参数

播放器初始化需要传入两个参数,第一个为播放器容器 ID,第二个为功能参数对象。
var player = TCPlayer('player-container-id', options);

options 参数列表

options 对象可配置的参数如下表:
名称
类型
默认值
说明
appID
String
通过 fileID 播放点播媒体文件时必选,为对应腾讯云账号的 appID
fileID
String
通过 fileID 播放点播媒体文件时必选,为点播媒体文件的 ID
psign
String
播放器签名,通过 fileID 播放时必传,详情参见 播放器签名
licenseUrl
String
播放器 License 地址,查看 播放器 License
sources
Array
播放器播放地址,格式:[{ src: '//path/to/video.mp4', type: 'video/mp4' }]
width
String/Number
播放器区域宽度,单位像素,按需设置,可通过 CSS 控制播放器尺寸。
height
String/Number
播放器区域高度,单位像素,按需设置,可通过 CSS 控制播放器尺寸。
controls
Boolean
true
是否显示播放器的控制栏。
poster
String
设置封面图片完整地址(如果上传的视频已生成封面图,优先使用生成的封面图,详细请参见 云点播 - 管理视频)。
autoplay
Boolean
false
是否自动播放。
playbackRates
Array
[0.5,1,1.25,1.5,2]
设置变速播放倍率选项,仅 HTML5 播放模式有效。
loop
Boolean
false
是否循环播放。
muted
Boolean
false
是否静音播放。
preload
String
auto
是否需要预加载,有3个属性"auto","meta"和"none" ,移动端由于系统限制,设置 auto 无效。
swf
String
Flash 播放器 swf 文件的 URL
posterImage
Boolean
true
是否显示封面。
bigPlayButton
Boolean
true
是否显示居中的播放按钮(浏览器劫持嵌入的播放按钮无法去除)。
language
String
"zh-CN"
设置语言,可选值为 "zh-CN"/"en"
languages
Object
设置多语言词典。
controlBar
Object
设置控制栏属性的参数组合,具体参见 controlBar 参数列表
reportable
Boolean
true
设置是否开启数据上报。
fakeFullscreen
Boolean
false
设置开启伪全屏,通过样式控制来实现全屏效果。
plugins
Object
设置插件功能属性的参数组合,具体参见 plugins 插件参数列表
hlsConfig
Object
hls.js 的启动配置,详细内容请参见官方文档 hls.js
webrtcConfig
Object
webrtc 的启动配置,具体参见 webrtcConfig 参数列表
xp2pConfig
Object
P2P 的启动配置,具体参见 xp2pConfig 参数列表。 P2P 功能详情请参见 X-P2P
注意:
controls、playbackRates、loop、preload、posterImage 这些参数在浏览器劫持播放的状态下将无效。
浏览器劫持视频播放问题参见 常见问题说明

controlBar 参数列表

controlBar 参数可以配置播放器控制栏的功能,支持的属性如下表:
名称
类型
默认值
说明
playToggle
Boolean
true
是否显示播放、暂停切换按钮。
progressControl
Boolean
true
是否显示播放进度条。
volumePanel
Boolean
true
是否显示音量控制。
currentTimeDisplay
Boolean
true
是否显示视频当前时间。
durationDisplay
Boolean
true
是否显示视频时长。
timeDivider
Boolean
true
是否显示时间分隔符。
playbackRateMenuButton
Boolean
true
是否显示播放速率选择按钮。
fullscreenToggle
Boolean
true
是否显示全屏按钮。
QualitySwitcherMenuButton
Boolean
true
是否显示清晰度切换菜单。
注意:
controlBar 参数在浏览器劫持播放的状态下将无效。
浏览器劫持视频播放问题参见 常见问题说明

plugins 插件参数列表

plugins 参数可以配置播放器插件的功能,支持的属性有:
名称
类型
默认值
说明
ContinuePlay
Object
控制续播功能,支持的属性如下:
auto:Boolean 是否在播放时自动续播。
text:String 提示文案。
btnText:String 按钮文案。
VttThumbnail
Object
控制缩略图显示,支持的属性如下:
vttUrl:String vtt 文件绝对地址,必传。
basePath:String 图片路径,非必须,不传时使用 vttUrl 的 path。
imgUrl:String 图片绝对地址,非必须。
ProgressMarker
Boolean
控制进度条显示。
DynamicWatermark
Object
控制动态水印显示,支持文字和图片,支持的属性为:
type:String 水印类型为文字或图片,取值为 text | image,默认 text,非必传。
content:String 文字水印内容,必传。
speed:Number 水印移动速度,取值范围 0-1, 默认值 0.2,非必传。
opacity:Number 文字水印透明度,取值范围 0-1,非必传。
fontSize:String 文字字体大小,默认12px,非必传。
color: String 文字颜色,非必传。
left:String, 文字位置,支持单位为百分比和 px,该字段设置时,speed 字段无效,非必传。
top、right、bottom:说明同 left。
width:String 图片水印宽度,非必传。
height:String 图片水印高度,非必传 。
ContextMenu
Object
可选值如下:
mirror:Boolean 控制是否支持镜像显示。
statistic:Boolean 控制是否支持显示数据面板。
levelSwitch:Object 控制切换清晰度时的文案提示。
 {
  open: Boolean 是否开启提示
  switchingText: String, 开始切换清晰度时的提示文案
  switchedText: String, 切换成功时的提示文案
  switchErrorText: String, 切换失败时的提示文案
 }
PlayList
Object
设置播放列表,支持的属性如下:
{
// 要播放的视频信息集合
data: [{
fileID: String,
appID: String,
duration: Number, // 视频时长
text: String, // 视频名称
psign: String, // 播放器签名
img: String, // 封面图
}],
title: String, // 列表标题
loop: Boolean, // 是否循环播放
}

VR
Object
高级版 License 支持,详情参见 Web 高级功能 - VR 播放插件(TCPlayerVRPlugin)
SafeCheck
Object
高级版 License 支持,详情参见 Web 高级功能 - 安全检查插件(TCPlayerSafeCheckPlugin)

webrtcConfig 参数列表

webrtcConfig 参数来控制播放 webrtc 过程中的行为表现,支持的属性如下表:
名称
类型
默认值
说明
connectRetryCount
Number
3
SDK 与服务器重连次数
connectRetryDelay
Number
1
SDK 与服务器重连延时
receiveVideo
Boolean
true
是否拉取视频流
receiveAudio
Boolean
true
是否拉取音频流
showLog
Boolean
false
是否在控制台打印日志
receiveSEI
Boolean
false
是否接收 SEI 信息

xp2pConfig 参数列表

使用 X-P2P 前,需要申请开通,请移步 X-P2P 单击申请,申请后我们会有专门的产品支持人员联系您。
更多详细资料,请参考 X-P2P 产品文档
公共参数
名称
类型
默认值
说明
useXP2P
Boolean
false
是否开启 XP2P
format
String
告知 P2P 需要支持的媒体协议,请根据当前播放的视频格式填写,可选值如下:
flv
hls
webrtc
tencentCloudAppId
Number
在腾讯云账号的 APPID (控制台查看路径:账号中心 > 账号信息 > 基本信息 > APPID)
xp2pAppId
String
X-P2P 分配的 ID,由我们邮件提供
xp2pAppKey
String
X-P2P 分配的 Key,由我们邮件提供
xp2pPackage
String
X-P2P 分配的 Package,由我们邮件提供
flv 协议额外参数
名称
类型
默认值
说明
bizId
String
由我们邮件提供
xp2pPlayDomain
String
flv 协议的拉流域名,由我们邮件提供
authMode
String
鉴权模式,由我们邮件提供
debug
Boolean
false
debug 开关
hls 协议额外参数
名称
类型
默认值
说明
videoType
String
VOD
当前播放的 HLS 是直播还是点播,请准确填写,可选值如下:
LIVE
VOD
channelId
String
自动生成
可以主动为当前资源生成一个 ID,如果不填,则默认内部自动生成。生成规则参见如下 HLS 资源 ID 生成规则
channelIdWithHost
Boolean
true
默认为 true,可选配置,通常不需要修改这个配置。详细解释参见如下 HLS 资源 ID 生成规则
channelIdWithSearch
Boolean
false
默认为 false,可选配置,通常不需要修改这个配置。详细解释参见如下 HLS 资源 ID 生成规则

HLS 资源 ID 生成规则

资源 ID 是 P2P 分享的单位,相同的资源 ID 的节点才能互相 P2P 分享。不同视频必须确保资源 ID 不同,否则会串流。
1.1 主动传入
可以通过设置参数channelId字段,主动为当前视频指定一个资源 ID,必须保证能唯一标识这个文件,避免串流。
1.2 默认生成
如果没有传入channelId字段,sdk 会默认为每一个 url 生成一个 ID,相同 ID 的会互相 P2P 分享,ID 生成规则如下:
(默认) 截取 host 和 path 部分生成 MD5。
例如:https://a.b.com/p1/p2/p3.m3u8?m=1&n=2,则 ID = MD5('a.b.com/p1/p2/p3.m3u8')
1.3 传入参数控制默认生成规则
(可选,默认为 true ) 通过传入channelIdWithHost参数,true 表示 ID 包含 host 部分。
(可选,默认为 false ) 通过传入channelIdWithSearch参数,false 表示包含 search 部分。
例如:https://a.b.com/p1/p2/p3.m3u8?m=1&n=2
如果传入 { channelIdWithHost: true, channelIdWithSearch: true } 则 ID = MD5('a.b.com/p1/p2/p3.m3u8?m=1&n=2')
如果传入 { channelIdWithHost: false, channelIdWithSearch: false } 则 ID = MD5('/p1/p2/p3.m3u8')
说明:
可以根据自己业务 url 生成规则,自行选择搭配,目的是确保不能互相 P2P 的视频 url,生成不同的资源 ID,可以互通的 url,生成相同的资源 ID。
1.4 多码率 M3U8 说明
如果播放的视频是多码率 M3U8,我们内部会保证播放不同码率的节点不会互相 P2P。
X-P2P 协议支持
音视频协议
用途
PC 浏览器
Android
iOS
FLV
直播
支持
chrome 55+ 
firefox 65+  
safari 11+
支持
chrome 55+ 
firefox 65+ 
微信浏览器
不支持
HLS
直播,点播
支持
chrome 55+ 
firefox 65+  
safari 11+
支持
chrome 55+ 
firefox 65+  
微信浏览器
不支持
WebRTC
直播
部分支持
Chrome 94+ 
edge 94+
部分支持
Chrome 94+ 
edge 94+
不支持

对象方法

初始化播放器返回对象的方法列表:
名称
参数及类型
返回值及类型
说明
src()
(String)
设置播放地址。
loadVideoByID()
(Object)
通过 fileID 播放时,可通过这个方法切换视频,参数为由fileID、appID、psign 组成的对象。
ready(function)
(Function)
设置播放器初始化完成后的回调。
play()
播放以及恢复播放。
pause()
暂停播放。
unload()
停止播放,会断流。
currentTime(seconds)
(Number)
(Number)
获取当前播放时间点,或者设置播放时间点,该时间点不能超过视频时长。
duration()
(Number)
获取视频时长。
volume(percent)
(Number)[0,1][可选]
(Number)/设置时无返回
获取或设置播放器音量。
muted()
(Boolean)
(Boolean)
获取或设置播放器是否静音
playbackRate()
(Number)[0, 1]
(Number)
获取或设置播放倍速
poster(src)
(String)
(String)/设置时无返回
获取或设置播放器封面。
requestFullscreen()
进入全屏模式。
exitFullscreen()
退出全屏模式。
isFullscreen()
Boolean
返回是否进入了全屏模式。
on(type,listener)
(String, Function)
监听事件。
one(type,listener)
(String, Function)
监听事件,事件处理函数最多只执行1次。
off(type,listener)
(String, Function)
解绑事件监听。
buffered()
TimeRanges
返回视频缓冲区间。
bufferedPercent()
值范围[0,1]
返回缓冲长度占视频时长的百分比。
width()
(Number)[可选]
(Number)/设置时无返回
获取或设置播放器区域宽度,如果通过 CSS 设置播放器尺寸,该方法将无效。
height()
(Number)[可选]
(Number)/设置时无返回
获取或设置播放器区域高度,如果通过 CSS 设置播放器尺寸,该方法将无效。
videoWidth()
(Number)
获取视频分辨率的宽度。
videoHeight()
(Number)
获取视频分辨率的高度。
dispose()
销毁播放器。
注意
对象方法不能同步调用,需要在相应的事件(如 loadedmetadata)触发后才可以调用,除了 ready、on、one 以及 off。

事件

播放器可以通过初始化返回的对象进行事件监听,示例:
var player = TCPlayer('player-container-id', options);
// player.on(type, function);
player.on('error', function(error) {
// 做一些处理
});
其中 type 为事件类型,支持的事件有:
名称
介绍
play
已经开始播放,调用 play() 方法或者设置了 autoplay 为 true 且生效时触发,这时 paused 属性为 false。
playing
因缓冲而暂停或停止后恢复播放时触发,paused 属性为 false 。通常用这个事件来标记视频真正播放,play 事件只是开始播放,画面并没有开始渲染。
loadstart
开始加载数据时触发。
durationchange
视频的时长数据发生变化时触发。
loadedmetadata
已加载视频的 metadata。
loadeddata
当前帧的数据已加载,但没有足够的数据来播放视频的下一帧时,触发该事件。
progress
在获取到媒体数据时触发。
canplay
当播放器能够开始播放视频时触发。
canplaythrough
当播放器预计能够在不停下来进行缓冲的情况下持续播放指定的视频时触发。
error
视频播放出现错误时触发。
pause
暂停时触发。
blocked
自动播放被浏览器阻止时触发。(原 2005 回调事件统一合并到 blocked 事件中)
ratechange
播放速率变更时触发。
seeked
搜寻指定播放位置结束时触发。
seeking
搜寻指定播放位置开始时触发。
timeupdate
当前播放位置有变更,可以理解为 currentTime 有变更。
volumechange
设置音量或者 muted 属性值变更时触发。
waiting
播放停止,下一帧内容不可用时触发。
ended
视频播放已结束时触发。此时 currentTime 值等于媒体资源最大值。
resolutionswitching
清晰度切换进行中。
resolutionswitched
清晰度切换完毕。
fullscreenchange
全屏状态切换时触发。
webrtcevent
播放 webrtc 时的事件集合。
webrtcstats
播放 webrtc 时的统计数据。
webrtcfallback
播放 webrtc 时触发降级

WebrtcEvent 列表

播放器可以通过 webrtcevent 获取播放 webrtc 过程中的所有事件,示例:
var player = TCPlayer('player-container-id', options);
player.on('webrtcevent', function(event) {
// 从回调参数 event 中获取事件状态码及相关数据
});
webrtcevent 状态码如下
状态码
回调参数
介绍
1001
开始拉流
1002
已经连接服务器
1003
视频播放开始
1004
停止拉流,结束视频播放
1005
连接服务器失败,已启动自动重连恢复
1006
获取流数据为空
1007
localSdp
开始请求信令服务器
1008
remoteSdp
请求信令服务器成功
1009
拉流卡顿等待缓冲中
1010
拉流卡顿结束恢复播放

错误码

当播放器触发 error 事件时,监听函数会返回错误码,其中3位数以上的错误码为媒体数据接口错误码。错误码列表:
名称
描述
-1
播放器没有检测到可用的视频地址。
-2
获取视频数据超时。
1
视频数据加载过程中被中断。
可能原因:
网络中断。
浏览器异常中断。
解决方案:
查看浏览器控制台网络请求信息,确认网络请求是否正常。
重新进行播放流程。
2
由于网络问题造成加载视频失败。
可能原因:网络中断。
解决方案:
查看浏览器控制台网络请求信息,确认网络请求是否正常。
重新进行播放流程。
3
视频解码时发生错误。
可能原因:视频数据异常,解码器解码失败。
解决方案:
尝试重新转码再进行播放,排除由于转码流程引入的问题。
确认原始视频是否正常。
请联系技术客服并提供播放参数进行定位排查。
4
视频因格式不支持或者服务器或网络的问题无法加载。
可能原因:
获取不到视频数据,CDN 资源不存在或者没有返回视频数据。
当前播放环境不支持播放该视频格式。
解决方案:
查看浏览器控制台网络请求信息,确认视频数据请求是否正常。
确认是否按照使用文档加载了对应视频格式的播放脚本。
确认当前浏览器和页面环境是否支持将要播放的视频格式。
请联系技术客服并提供播放参数进行定位排查。
5
视频解密时发生错误。
可能原因:
解密用的密钥不正确。
请求密钥接口返回异常。
当前播放环境不支持视频解密功能。
解决方案:
确认密钥是否正确,以及密钥接口是否返回正常。
请联系技术客服并提供播放参数进行定位排查。
10
点播媒体数据接口请求超时。在获取媒体数据时,播放器重试3次后仍没有任何响应,会抛出该错误。
可能原因:
当前网络环境无法连接到媒体数据接口,或者媒体数据接口被劫持。
媒体数据接口异常。
解决方案:
尝试打开我们提供的 Demo 页面看是否可以正常播放。
请联系技术客服并提供播放参数进行定位排查。
11
点播媒体数据接口没有返回数据。在获取媒体数据时,播放器重试3次后仍没有数据返回,会抛出该错误。
可能原因:
当前网络环境无法连接到媒体数据接口,或者媒体数据接口被劫持。
媒体数据接口异常。
解决方案:
尝试打开我们提供的 Demo 页面看是否可以正常播放。
请联系技术客服并提供播放参数进行定位排查。
12
点播媒体数据接口返回异常数据。在获取媒体数据时,播放器重试3次后仍返回无法解析的数据,会抛出该错误。
可能原因:
当前网络环境无法连接到媒体数据接口,或者媒体数据接口被劫持。
播放参数有误,媒体数据接口无法处理。
媒体数据接口异常。
解决方案:
尝试打开我们提供的 Demo 页面看是否可以正常播放。
请联系技术客服并提供播放参数进行定位排查。
13
播放器没有检测到可以在当前播放器播放的视频数据,请对该视频进行转码操作。
14
HTML5 + hls.js 模式下播放 hls 出现网络异常,异常详情可在 event.source 中查看,详细介绍请看 hls.js 的官方文档 Network Errors
15
HTML5 + hls.js 模式下播放 hls 出现多媒体异常,异常详情可在 event.source 中查看,详细介绍请看 hls.js 的官方文档 Media Errors
16
HTML5 + hls.js 模式下播放 hls 出现多路复用异常,异常详情可在 event.source 中查看,详细介绍请看 hls.js 的官方文档 Mux Errors
17
HTML5 + hls.js 模式下播放 hls 出现其他异常,异常详情可在 event.source 中查看,详细介绍请看 hls.js 的官方文档 Other Errors
1013
播放器签名缺少 contentInfo 字段
10008
媒体数据服务没有找到对应播放参数的媒体数据,请确认请求参数 appID fileID 是否正确,以及对应的媒体数据是否已经被删除。
-2002
快直播拉流接口后台返回报错(例如流不存在、鉴权失败等)
-2006
快直播多分辨率平滑切换接口请求失败