基础库 1.0.0 开始支持本组件

视频组件，相关 API 请参考 tt.createVideoContext。Codelab 教程请参考video视频组件的正确使用姿势。

前提条件	无
业务背景	无
使用限制	无
注意事项	Bug：给 video 或其父节点绑定 catch* 事件，可能会导致 video 播放控件不可用； Tip：避免在退出全屏操作过程中更新数据； Tip：视频资源在浏览器和 IDE 中能正常播放，在真机上播放失败，可以先尝试将 tmaservice.developer.toutiao.com 添加到 CDN 白名单。
相关教程	无

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
src	string	无	否	要播放的视频资源地址。需要保证 src 和 definition 中有一个为必填，若同时设置了 src 和 definition，definition 优先级高于 src；更新 src 时，会对 src 做校验，需要保证设置的 src 以 'https://'、'ttfile://' 或 'file://' 开头，否则更新 src 会失败；不同的 APP 宿主以及不同的系统对视频格式的支持程度是不一样，请参考文档中支持格式； m3u8 格式视频不支持 EXT-X-DISCONTINUITY 标签。	1.0.0
autoplay	boolean	false	否	是否自动播放。	1.0.0
poster	string	无	否	视频封面的图片网络资源地址。	1.0.0
loop	boolean	false	否	是否循环播放。	1.47.0
show-fullscreen-btn	boolean	true	否	是否显示全屏按钮。	1.47.0
show-play-btn	boolean	true	否	是否显示播放、暂停、重播按钮，不包括视频封面的播放按钮。	1.47.0
controls	boolean	true	否	是否显示全部播放控件。	1.47.0
object-fit	enum	contain	否	当视频大小与 video 容器大小不一致时，视频的表现形式。 contain（包含） fill（填充） cover（覆盖）	1.47.0
play-btn-position	enum	center	否	播放按钮的位置。 center（视频中间） bottom（控制条上）	1.47.0
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。	2.3.0
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。	2.3.0
enable-progress-gesture	boolean	false	否	是否开启控制进度的手势，开启后表现详见手势响应-播放进度。	2.3.0
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停。	2.3.0
muted	boolean	false	否	是否静音播放。	2.4.0
show-mute-btn	boolean	false	否	是否显示静音控件，仅在全屏时显示。	2.4.0
show-playback-rate-btn	boolean	false	否	是否显示倍速控件，仅在全屏时显示。点击倍速控件后可选择倍速，可选值： 0.75/1.0/1.25/1.5/2。	2.5.0
direction	enum	-90	否	设置全屏时视频的方向。	2.13.0
enable-play-in-background	boolean	false	否	video 播放时宿主退出后台后开启小窗播放，iOS 14 及以上版本支持。开启时首次退出后台后给予弹窗提示用户授权，授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放。	2.16.0
signature	Signature	无	否	设置署名水印。	2.48.0
initial-time	number	0	否	指定视频的初始播放位置。	2.80.0
show-screen-lock-button	boolean	false	否	是否展示锁屏按钮，仅在全屏时展示，锁屏后会锁定播控/手势的操作。	2.80.0
definition	Definition	无	否	清晰度，设置清晰度列表和默认播放的清晰度。切换清晰度按钮仅在全屏时展示，属性说明详见文档下面的 Definition 类型说明。需要保证 src 和 definition 中有一个为必填，若同时设置了 src 和 definition，definition 优先级高于 src。	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
bindplay	function	无	否	当开始播放时触发 play 事件。	1.0.0
bindpause	function	无	否	当暂停播放时触发 pause 事件。	1.0.0
bindended	function	无	否	当播放到末尾时触发 ended 事件。	1.0.0
binderror	function	无	否	视频播放出错时触发 error 事件。	1.0.0
bindtimeupdate	function	无	否	播放进度变化时触发，返回当前播放时间点及视频总时长，单位：秒(s)。`event.detail = { currentTime, duration }`。	1.18.0
bindprogress	function	无	否	视频缓冲进度更新时触发，`event.detail = { buffered }`。其中 buffered 是百分比，取值是 [0, 100] 中的整数，如 buffered 为 50 表示当前视频缓冲了 50%。	2.65.0
bindfullscreenchange	function	无	否	视频进入和退出全屏时触发，`event.detail = { fullScreen, direction}`，其中 direction 仅在 fullScreen 字段为 true 时存在，有效值为 vertical 或 horizontal。	1.18.0
bindcontrolstoggle	function	无	否	切换播放控件显示/隐藏时触发。`event.detail = { show }`。	2.90.0
bindwaiting	function	无	否	视频出现缓冲时触发。	1.47.0
bindloadedmetadata	function	无	否	视频元数据加载完成时触发。`event.detail = {width, height, duration}`。	1.90.0
bindseekcomplete	function	无	否	seek 完成时触发。返回 seek 完成后的播放时间点，单位：秒(s)。`event.detail={position}`。	2.11.0
bindplaybackratechange	function	无	否	视频倍速改变完成时触发。返回改变后的倍速值。`event.detail={playbackRate}`。	2.11.0
bindmutechange	function	无	否	静音状态改变完成时触发。返回当前是否静音。`event.detail={isMuted}`。	2.11.0
bindcontroltap	function	无	否	点击控件时触发。返回当前点击的控件类型。`event.detail={controlType}`，取值见表 controlType 的合法值。	2.11.0
bindenterbackground	function	无	否	进入小窗播放时触发。	2.16.0
bindclosebackground	function	无	否	关闭小窗播放时触发。	2.16.0
bindleavebackground	function	无	否	离开小窗进入 app 事件时触发。	2.16.0
enable-dark-water-mark	boolean	false	否	是否开启界面暗水印功能，用于视频防盗录场景。暗水印解码效果需要根据实际情况而定。小程序使用了暗水印能力后出现的盗录场景，可以拉客服咨询。	2.98.0
encrypted-token	string	无	否	对视频内容的传输过程进行加密，通过 encrypted-token 设置通用加密（CENC）的解密 key，加密流程见 FFmpeg通用加密，IDE 暂不支持。	2.98.0
show-casting-button	boolean	false	否	是否显示投屏按钮/菜单，仅在全屏时展示（当前仅支持 Android，iOS 敬请期待）。	3.2.0
playback-rate-list	Array<number>	[0.75,1.0,1.25,1.5,2.0]	否	配置5个需要展示和可通过API切换的倍速选项。选项数量必须为5个，必选倍速1.0, 2.0，无重复取值，且取值都在合法值之列：0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2, 2.5, 2.75, 3.0。	1.0.0
bindplaybackratelistchange	function		否	当传入的 playback-rate-list 属性被修改时触发。不管设置成功还是失败，都预期返回一个最终被设置到界面上的 playbackRateList。	1.0.0

definition 参数说明

Definition

object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
list	DefinitionListItem[]	无	是	清晰度列表	2.80.0
defaultDefinition	string	无	否	默认播放的清晰度，可选值：'360P' / '480P' / '720P' / '1080P' / '2K' / '4K'。没有设置时，会以 list 列表中设置的最高清晰度作为默认值播放。	2.80.0

DefinitionListItem 类型说明

object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
name	string	无	是	url 对应的清晰度，可选值：'360P' / '480P' / '720P' / '1080P' / '2K' / '4K'。	2.80.0
url	string	无	是	对应清晰度的视频播放链接，需要以 'http://'、'https://'、'ttfile://' 或 'file://' 开头。	2.80.0

object-fit 的合法值

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

play-btn-position 的合法值

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

direction 的合法值

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

bindplaybackratelistchange 是一个回调函数，接收 object 类型的参数，属性如下：

属性名	类型	说明	最低支持版本
playbackRateList	Array<number>	最终被设置到界面上的 playbackRateList	1.0.0

错误码

errorCode

errMsg

errorType

说明

最低支持版本

137909

error code = -9999 或 domain:kTTVideoErrorDomainFetchingInfo, code:-9999

D

应用层传给点播SDK的URL参数为空或类型错误

建议检查api参数

1.0.0

137904

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-1414092869

U

用户中断，用户退出播放或seek

1.0.0

137907

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-5

D

内部错误(EIO)/起播阶段的网络错误

建议更换视频网址，或查看是否为用户网络差

1.0.0

137906

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499896

D

404，找不到，一般是流结束已久，url失效

建议更换视频网址

1.0.0

137901

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-101, internalCode:0, description:

F

小程序框架内部错误，有需要请拉客服咨询

收到该错误码上报，需要再结合日志做进一步归因。

1.0.0

137905

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499897

U

403，禁止访问

建议更换视频网址

1.0.0

137902

domain:kTTVideoErrorDomainFetchingInfo, code:-9994

D

http请求返回code不是200或请求play接口失败，常见于网络差的情况

检查网络

1.0.0

137903

error code = -499793

D

TCP请求网络超时

建议更换视频网址，或查看是否为用户网络差

1.0.0

137908

error code = -499894

D

HTTP_OTHER_4xx

建议更换视频网址

1.0.0

137910

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-113

D

播放器dns解析错误

建议更换视频网址

1.0.0

137911

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499745

F

小程序框架内部错误，有需要请拉客服咨询

实际错误码为ffmpeg：1094995529 建议排查CDN、视频转码、视频源

1.0.0

137912

error code = -499899

D

400 ，请求出错

建议更换视频网址

1.0.0

137913

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-13

D

linux系统错误码Permission denied

1.0.0

137914

error code = -1003

F

小程序框架内部错误，有需要请拉客服咨询

1.0.0

137915

error code = -1009

F

小程序框架内部错误，有需要请拉客服咨询

1.0.0

137916

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-1094995529

F

小程序框架内部错误，有需要请拉客服咨询

排查CDN问题、视频转码、视频源问题

1.0.0

137917

error code = -1020

F

小程序框架内部错误，有需要请拉客服咨询

1.0.0

137918

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-111

D

响应reponse为空

1.0.0

137919

error code = -499982

U

播放器内部卡顿超时，大多是网络原因

建议先检查网络环境，仍无效则重起播放器

1.0.0

137920

error code = -1001

D

请求超时

1.0.0

137921

error code = -499975

D

网络错误，连接失败

建议更换视频网址，或查看是否为用户网络差

1.0.0

137922

error code = -499799

D

tcp层解析域名失败

建议更换视频网址

1.0.0

137923

error code = -9996

D

服务端返回status状态不对，或返回的url为空，或视频文件无法下载

建议更换视频网址，或查看是否为用户网络差

1.0.0

137924

error code = -499893

D

http 5xx服务器错误

建议更换视频网址，或查看是否为用户网络差

1.0.0

137926

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-2

U

用户主动离开

无需处理

1.0.0

137927

error code = -1

U

用户主动离开

无需处理

1.0.0

137930

error code = -499960

D

视频数据有错

建议更换视频网址，或检查视频文件是否有错误

1.0.0

137931

error code = -499798

D

tcp层解析域名超时

建议更换视频网址

1.0.0

137932

error code = -499981

D

打开解码器失败

检查是否为支持的视频格式，或者视频文件是否有错误

1.0.0

137950

domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499963 ；error code = -9996; ....

F

小程序框架内部错误，有需要请拉客服咨询

1.0.0

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

手势响应

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

亮度与音量

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

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

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

播放进度

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

后台小窗播放

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

支持格式

抖音支持的视频封装格式和编码格式如下所示。其中封装格式建议使用mp4，编码格式建议优先使用h265并兜底使用h264，可通过tt.canIUseVideoFormat判断当前设备是否支持h265。使用建议格式可获得更好播放性能。

封装格式

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

编码格式

格式	iOS	Android
h264（AVC）	√	√
h265（HEVC）	√	√
h263	X	√
mpeg4	X	√
mjpeg	√	X

常见问题（FAQ）

Q1：播放视频时，APP 为何明显卡顿或出现闪退？

A：请先检查是否在页面中同时渲染多个视频组件。由于视频播放会占用比较多的资源，建议不要同时渲染超过3个以上的视频，如有需要，可以先用图片或其他内容替代，等到需要播放时，再渲染视频组件。

Q2：video 是否支持配置 referer 请求头规则？

A：从基础库 3.16.0 开始，支持开发者按 url 和 domain 维度配置添加 referer 请求头的规则，具体见：网络资源请求添加referer规则。

Q3：Android 上为什么会出现无法在视频上覆盖其他元素？

A：Android 上在内核环境没有准备好时（内核覆盖率约 99%），无法使用同层渲染的 video，会使用兜底方案的 video，此时可能出现视频错位，同时也无法在 video 上覆盖其他元素，可以用 tt.canIPutStuffOverComponent 检查是否是此场景。iOS 上不会出现这个问题。

Q4：为什么通过组件属性设置了显示控件，但是控件没有显示出来？

A：video 组件过小时不会显示控件（width < 250 || height < 140 时)。

Q5：video 支持设置 border-radius 吗？

A：真机上的 video 从基础库 2.87.0 开始支持 border-radius。

Q6：控制台 -> 反馈中心中反馈截图视频位置出现的水印是什么？

A：这里的水印内容是视频相关的信息，主要用于辅助排查视频问题，分析思路可参考用户反馈截图信息。

Q7：为什么播放m3u8格式视频时拖动播放进度条会一直处于加载状态？

A：请确保您的视频服务器支持视频分片HTTP Range分段下载。如短期内无法支持，请联系平台处理。

开发者文档

video 视频
收藏
我的收藏

属性说明

definition 参数说明

Definition

DefinitionListItem 类型说明

object-fit 的合法值

play-btn-position 的合法值

direction 的合法值

错误码

扫码体验

代码示例

手势响应

亮度与音量

播放进度

后台小窗播放

支持格式

封装格式

编码格式

常见问题（FAQ）

Q1：播放视频时，APP 为何明显卡顿或出现闪退？

Q2：video 是否支持配置 referer 请求头规则？

Q3：Android 上为什么会出现无法在视频上覆盖其他元素？

Q4：为什么通过组件属性设置了显示控件，但是控件没有显示出来？

Q5：video 支持设置 border-radius 吗？

Q6：控制台 -> 反馈中心中反馈截图视频位置出现的水印是什么？

Q7：为什么播放m3u8格式视频时拖动播放进度条会一直处于加载状态？

video 视频收藏我的收藏

属性说明

definition 参数说明

Definition

DefinitionListItem 类型说明

object-fit 的合法值

play-btn-position 的合法值

direction 的合法值

错误码

扫码体验

代码示例

手势响应

亮度与音量

播放进度

后台小窗播放

支持格式

封装格式

编码格式

常见问题（FAQ）

Q1：播放视频时，APP 为何明显卡顿或出现闪退？

Q2：video 是否支持配置 referer 请求头规则？

Q3：Android 上为什么会出现无法在视频上覆盖其他元素？

Q4：为什么通过组件属性设置了显示控件，但是控件没有显示出来？

Q5：video 支持设置 border-radius 吗？

Q6：控制台 -> 反馈中心中反馈截图视频位置出现的水印是什么？

Q7：为什么播放m3u8格式视频时拖动播放进度条会一直处于加载状态？

video 视频
收藏
我的收藏