tencent cloud

文档反馈

最后更新时间:2024-10-23 11:07:10
    本文档是介绍适用于直播和点播播放的 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 参数列表
    注意:
    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
    是否在控制台打印日志

    

    对象方法

    初始化播放器返回对象的方法列表:
    名称
    参数及类型
    返回值及类型
    说明
    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
    1013
    播放器签名缺少 contentInfo 字段
    10008
    媒体数据服务没有找到对应播放参数的媒体数据,请确认请求参数 appID fileID 是否正确,以及对应的媒体数据是否已经被删除。
    -2002
    快直播拉流接口后台返回报错(例如流不存在、鉴权失败等)
    -2006
    快直播多分辨率平滑切换接口请求失败
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持