本文档是介绍适用于直播和点播播放的 Web 播放器（ TCPlayer ）的相关参数以及 API。本文档适合有一定 Javascript 语言基础的开发人员阅读。
初始化参数
播放器初始化需要传入两个参数，第一个为播放器容器 ID，第二个为功能参数对象。
var player = TCPlayer('player-container-id', options);
options 参数列表
options 对象可配置的参数如下表：
| 名称 | 类型 | 默认值 | 说明 |
| appID | String | 无 | 通过 fileID 播放点播媒体文件时必选，为对应腾讯云账号的 appID |
| fileID | String | 无 | 通过 fileID 播放点播媒体文件时必选，为点播媒体文件的 ID |
| 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 | 是否在控制台打印日志。 |
xp2pConfig 参数列表
使用 X-P2P 前，需要申请开通，请移步 X-P2P 单击申请，申请后我们会有专门的产品支持人员联系您。更多详细资料，请参考 X-P2P 产品文档。公共参数
| 名称 | 类型 | 默认值 | 说明 |
| useXP2P | Boolean | false | 是否开启 XP2P |
| format | String | 无 | 告知 P2P 需要支持的媒体协议，请根据当前播放的视频格式填写，可选值如下： flvhlswebrtc |
| 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 是直播还是点播，请准确填写，可选值如下：LIVEVOD |
| 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() | 无 | 无 | 暂停播放。 |
| 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 | 自动播放被浏览器阻止时触发。 |
| 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。 |
| 10008 | 媒体数据服务没有找到对应播放参数的媒体数据，请确认请求参数 appID fileID 是否正确，以及对应的媒体数据是否已经被删除。 |
| -2002 | 快直播拉流接口后台返回报错（例如流不存在、鉴权失败等） |
| -2006 | 快直播多分辨率平滑切换接口请求失败 |
云点播官网1折活动，限时活动，即将结束，速速收藏
同尘科技为腾讯云授权服务中心。
购买腾讯云产品享受折上折，更有现金返利。同意关联立享优惠
转转请注明出处：https://www.yunxiaoer.com/144021.html