video-player

我的收藏

基础库 2.77.0 开始支持本组件。

视频组件。

使用限制

在使用插件中的组件和 API 前，需要对行业插件有一个基本了解，可以参考文档：行业插件介绍；

版本校验

video-player 只在抖音 23.8 及以上版本支持，使用前可通过 tt.canIUse 校验是否可用。若不支持可使用旧版 video 组件进行播放或提示用户升级抖音。

tt.canIUse('video-player')

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
album-id	string	无	是	原片id	行业插件
episode-id	string	无	是	剧集id	行业插件
cloud-type	number	无	是	使用cdn类型，1: 抖音云 ~~2: 三方云。~~ 可用 tt.canIUse('video-player.cloudType') 判断是否支持该属性。	行业插件
version	string	无	是	废弃字段。为了兼容老版本，请传 1 。	行业插件
autoplay	boolean	false	否	是否自动播放。	2.74.0
poster	string	无	否	视频封面的图片网络资源地址。	2.74.0
loop	boolean	false	否	是否循环播放。	2.74.0
show-fullscreen-btn	boolean	true	否	是否显示全屏按钮。	2.74.0
show-play-btn	boolean	true	否	是否显示播放、暂停、重播按钮，不包括视频封面的播放按钮。	2.74.0
controls	boolean	true	否	是否显示全部播放控件。	2.74.0
object-fit	string	contain	否	当视频大小与 video 容器大小不一致时，视频的表现形式。 •contain（包含） •fill（填充） •cover（覆盖）	2.74.0
play-btn-position	string	center	否	播放按钮的位置。 •center（视频中间） •bottom（控制条上）	2.74.0
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。	2.74.0
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。	2.74.0
enable-progress-gesture	boolean	false	否	是否开启控制进度的手势，开启后表现详见手势响应-播放进度。	2.74.0
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停。	2.74.0
muted	boolean	false	否	是否静音播放。	2.74.0
show-mute-btn	boolean	false	否	是否显示静音控件，仅在全屏时显示。	2.74.0
show-playback-rate-btn	boolean	false	否	是否显示倍速控件，仅在全屏时显示。点击倍速控件后可选择倍速，可选值： 0.75/1.0/1.25/1.5/2。	2.74.0
direction	number	-90	否	设置全屏时视频的方向，详见 direction 的合法值。	2.74.0
enable-play-in-background	boolean	false	否	video 播放时宿主退出后台后开启小窗播放，iOS 14 及以上版本支持。开启时首次退出后台后给予弹窗提示用户授权，授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放。	2.74.0
signature	Signature	无	否	设置署名水印，属性说明详见 Signature 类型说明。	2.74.0
initial-time	number	0	否	指定视频的初始播放位置。	2.80.0
show-screen-lock-button	boolean	false	否	是否展示锁屏按钮，仅在全屏时展示，锁屏后会锁定播控/手势的操作。	2.80.0
show-progress	boolean	true	否	是否展示中间的播放进度条。	2.90.0
show-bottom-progress	boolean	true	否	是否展示底部的播放进度条。	2.90.0
poster-size	string	contain	否	视频的封面图片大小与 video 容器大小不一致时，封面图片的表现形式。 •contain（包含） •fill（填充） •cover（覆盖）	2.90.0
duration-limit	number		否	限制视频的最大可播放时长，用于试看等场景。	2.90.0
enable-dark-water-mark	boolean	false	否	是否开启界面暗水印功能，用于视频防盗录场景。暗水印解码效果需要根据实际情况而定。小程序使用了暗水印能力后出现的盗录场景，可以拉客服咨询。	2.98.0
encrypted-token	string	无	否	目前暂不支持对视频内容的传输过程进行加密，通过 encrypted-token 设置通用加密（CENC）的解密 key，加密流程见 FFmpeg通用加密。	2.98.0
bindplay	EventHandle	无	否	当开始播放时触发 play 事件。	2.74.0
bindpause	EventHandle	无	否	当暂停播放时触发 pause 事件。	2.74.0
bindended	EventHandle	无	否	当播放到末尾时触发 ended 事件。	2.74.0
binderror	EventHandle	无	否	视频播放出错时触发 error 事件。	2.74.0
bindtimeupdate	EventHandle	无	否	播放进度变化时触发，返回当前播放时间点及视频总时长，单位：秒(s)。event.detail = { currentTime, duration }。	2.74.0
bindprogress	EventHandle	无	否	视频缓冲进度更新时触发，event.detail = { buffered }。其中 buffered 是百分比，取值是 [0, 100] 中的整数，如 buffered 为 50 表示当前视频缓冲了 50%。	2.74.0
bindfullscreenchange	EventHandle	无	否	视频进入和退出全屏时触发，event.detail = { fullScreen, direction}，其中 direction 仅在 fullScreen 字段为 true 时存在，有效值为 vertical 或 horizontal。	2.74.0
bindcontrolstoggle	EventHandle	无	否	切换播放控件显示/隐藏时触发。event.detail = { show }。	2.90.0
bindwaiting	EventHandle	无	否	视频出现缓冲时触发。	2.74.0
bindloadedmetadata	EventHandle	无	否	视频元数据加载完成时触发。event.detail = {width, height, duration}。	2.74.0
bindseekcomplete	EventHandle	无	否	seek 完成时触发。返回 seek 完成后的播放时间点，单位：秒(s)。event.detail={position}。	2.74.0
bindplaybackratechange	EventHandle	无	否	视频倍速改变完成时触发。返回改变后的倍速值。event.detail={playbackRate}。	2.74.0
bindmutechange	EventHandle	无	否	静音状态改变完成时触发。返回当前是否静音。event.detail={isMuted}。	2.74.0
bindcontroltap	EventHandle	无	否	点击控件时触发。返回当前点击的控件类型。event.detail={controlType}，取值见表 controlType 的合法值。	2.74.0
bindenterbackground	EventHandle	无	否	进入小窗播放时触发。	2.74.0
bindclosebackground	EventHandle	无	否	关闭小窗播放时触发。	2.74.0
bindleavebackground	EventHandle	无	否	离开小窗进入 app 事件时触发。	2.74.0
bindgetsource	EventHandle	无	否	获取资源完成后触发。可在这个时机后用 api 播放时。可用 tt.canIUse('video-player.bindgetsource') 校验是否支持该事件。	行业插件

Signature 类型说明

object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
enable	boolean	true	否	是否显示署名水印	2.74.0
content	string	无	是	署名水印内容	2.74.0
position	number	0	否	署名水印位置： •0（右上） •1（右下） •2（左下） •3（左上）	2.74.0
color	Color	#FFFFFF	否	署名水印颜色，只支持 HEX 格式。	2.74.0

object-fit 的合法值

值	说明	最低支持版本
contain	包含。内容将会在填充内容框的时候保持其宽高比例缩放，因此如果宽高比与内容框的宽高比不匹配，将会有黑边。	2.74.0
fill	填充。如果内容的宽高比与内容框的不匹配，该对象将被拉伸以适应内容框。	2.74.0
cover	覆盖。内容在保持其宽高比的同时填充整个内容框。如果内容的宽高比与内容框不匹配，该对象将被裁剪以适应内容框。	2.74.0

play-btn-position 的合法值

值	说明	最低支持版本
center	视频中间	2.74.0
bottom	控制条上	2.74.0

direction 的合法值

值	说明	最低支持版本
0	正常竖向	2.74.0
90	屏幕逆时针 90 度	2.74.0
-90	屏幕顺时针 90 度	2.74.0

controlType 的合法值

值	说明	最低支持版本
play	播放控件 / 重播控件 (不包括点击视频初始状态的播放按钮)	2.74.0
pause	暂停控件	2.74.0
fullscreen	全屏控件	2.74.0
mute	静音控件	2.74.0
playbackRate	倍速控件（不包括倍速选择面板）	2.74.0
progress	进度控件，在刚开始拖动进度条时触发	2.74.0

手势响应

指定响应手势属性后，video 支持以下行为表现。

亮度与音量

开启亮度与音量手势后，以视频组件横向中心点为分界线，行为见下表：

滑动区域	表现	行为
左侧	调节亮度	上滑增大，下滑减小
右侧	调节音量	上滑增大，下滑减小

指示控件消失时机：松手 1 秒无操作消失。

播放进度

开启进度手势后，左右滑动屏幕，调节播放进度（右滑增大、左滑减小）。指示控件消失时机：松手后时间提示立即消失。

后台小窗播放

关键特征	描述
小窗时机	宿主退出后台（支持移动小窗到任意位置）
退后台场景	跳转到其他 app、点击 home 键退到后台、打开最近任务列表
不包含场景	点击小程序关闭按钮
小窗优先级	多个 video 开启后台小窗播放时，后台小窗的 video 以播放次序优先，autoplay 情况播放次序不确定。

bindgetsource 说明

bindgetsource 表示 video-player 组件内部资源获取完成。如果使用 VideoContext 播放，需在这个时机后播放，否则可能出现播放失败。

可用 tt.canIUse('video-player.bindgetsource') 校验是否支持该事件，如果不支持需作降级处理。

支持格式

抖音支持的视频封装格式和编码格式如下所示。

封装格式

格式	iOS	Android
mp4	√	√
mpd	√	√
mov	√	√
m4v	X	X
3gp	X	X
avi	√	√
m3u8	√	√
flv	√	√
webm	X	X
mpegts	X	√
hls	√	√
dash	√	√

编码格式

格式	iOS	Android
h264	√	√
h265	√	√
h263	X	√
mpeg4	X	√
mjpeg	√	X

代码示例

index.ttml

<video-player
    album-id="{{aid}}" 
    episode-id="{{eid}}"
    autoplay
    bindplay="playhandler"
    ...
></video-player>

index.js

Page({
    playhandler(){
        console.log('play')
    }
})

index.json

{
    "usingComponents": {
        "video-player":"ttf57583c86a3aace011://video-player"
    },
    "navigationBarTitleText":"播放页面"
}

Q & A

为什么调用 tt.canIUse('video-player')返回 false

A：优先检查抖音短剧插件是否申请。其次检查版本问题，video-player 只在抖音、抖极、抖火 23.8 及以上版本支持，若不支持可使用老版 video 组件进行播放或提示用户升级抖音开放平台。

首次配置短剧插件以后出现图中报错

A：重启抖音开发者工具

出现 "domain:kTTVideoErrorDomainFetchingInfo, code:-9999, internalCode:0, description:apistring empty" 或者 "Empty src attribute" 问题

A：如果使用 tt.createVideoContext 播放视频，需要在 bindgetsource 回调中播放。

bindgetsource 不触发

A：优先使用 tt.canIUse('video-player.bindgetsource') 验证bindgetsource是否可用

•

如果返回 true 但仍不触发，请检查绑定的属性命名或类型是否错误：

◦

如：cloud-type 类型为 number ，属性命名问题主要包含（album-id、episode-id）。

•

返回 false，请检查小程序是否已成功配置短剧插件权限。

bindtap 等事件不触发

A：video-player 暂不支持 bindtap 等通用事件，需要在 video-player 标签内加一个 view ，将view通过css调整与video-player重叠，此时该view组件层级在播放组件上层。在 view 上绑定 bindtap 即可触发。

设置了autoplay 属性，初始化播放组件时会显示视频加载失败，然后才开始播放。

A：参考bindgetsource事件回调。

视频播放出现error code = -xxxxx,domain = kTTVideoErrorDomainOwnPlayerxxxx 这类错误。

A：查看抖音云（抖音开放平台）域名状态是否正常。SSL 证书是否过期。

•

域名正常且SSL证书未过期

•

检查是否曾经有过欠费充正的情况。该情况需要重启（停用->启用）抖音云域名。

部分Android机型出现部分事件没有回调的情况

A：检查「行业插件权限」是否配置成功。

•

已经配置成功，将不触发事件回调的Android手机重启抖音后等待两分钟，然后再冷启动。

•

没有配置成功。

部分视频在Android和iOS播放宽高比例出现异常，视频被拉伸等

A：尝试在 video-player 添加 object-fit: fill 属性。

组件渲染失败，没有渲染出来，出现 n.type 空指针

A：检查是否按照文档上方添加了短剧插件权限。

视频播放有声音没画面，进度条也在前进。

A：使用真机调试或者升级 IDE 最新版本。

tt.createVideoContext 传入第二个参数无效

A：需要传入 video-player 的 this ，可通过 ref 拿到。

IOS 17 激励广告播放后，有声音但黑屏

A：iOS 系统升级导致，临时解决方案：在激励广告播放完毕后，用一个 settimeout 延时 500ms 去播放。

video-player组件播放无画面有声音，黑屏/白屏

A：检查是否使用百分比布局，是否有添加蒙层的逻辑。

•

自查是否是蒙层导致

•

检查给video-player的宽高是否是动态设置的

◦

是：确认设置的宽高是否有正确。

◦

否：话题群内提问。

出现错误码10401，错误信息 MEDIA ELEMENT ERROR:Format error

A：使用真机播放。

vue 使用 watch 监听后通过 API 控制 video-player 播放不成功

A：watch 的触发时机比 bindgetsource 要早，需要在 bindgetsource 触发后再通过 api 去播放视频

vue3 中如果遇到 video-player 组件被 uniapp 识别成了自定义组件，会自动转换压缩组件属性

A：解决方案：按uni-app官网提供的原生混合式接入该组件，相对稳定参考文档：https://uniapp.dcloud.net.cn/tutorial/miniprogram-subject.html

uni-app接入时是vue3，aid和eid需要等待数据请求时候才能取到，该场景出现下图中报错，但是不影响播放

A：原生组件混合式接入是给组件本身加上tt:if 是在使用原生组件的文件中加入以下属性

Bug & Tip

•

Bug：给 video 或其父节点绑定 catch* 事件，可能会导致 video 播放控件不可用；

•

Bug：给 video-player 组件设置百分比宽高，不会生效，可用 vw、vh 代替；

•

Tip：不同的 App 宿主以及不同的系统对视频格式的支持程度是不一样，请参考文档中的详细说明；

•

Tip：相关 API 请参考 tt.createVideoContext，若传入第二个参数无效，需要传入 video-player 的 this，通过 ref 获取。