抖音开放平台Logo
开发者文档
小程序
控制台
  • 组件列表
  • 介绍
  • 基础内容
  • 视图容器
  • 表单
  • 导航
  • 媒体
  • 画布
  • 地图
  • 开放能力
  • 行业开放
  • 消息推送客服
  • 原生组件

    • video 视频
    收藏
    我的收藏

    基础库 1.0.0 开始支持本组件

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

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

    属性说明

    属性名类型默认值必填说明最低支持版本
    srcstring无否
    • 要播放的视频资源地址。需要保证 src 和 definition 中有一个为必填，若同时设置了 src 和 definition，definition 优先级高于 src；
    • 更新 src 时，会对 src 做校验，需要保证设置的 src 以 'https://'、'ttfile://' 或 'file://' 开头，否则更新 src 会失败；
    • 不同的 APP 宿主以及不同的系统对视频格式的支持程度是不一样，请参考文档中支持格式；
    • m3u8 格式视频不支持 EXT-X-DISCONTINUITY 标签。
    		1.0.0
    autoplaybooleanfalse否
    是否自动播放。
    		1.0.0
    posterstring无否
    视频封面的图片网络资源地址。
    		1.0.0
    loopbooleanfalse否
    是否循环播放。
    		1.47.0
    show-fullscreen-btnbooleantrue否
    是否显示全屏按钮。
    		1.47.0
    show-play-btnbooleantrue否
    是否显示播放、暂停、重播按钮，不包括视频封面的播放按钮。
    		1.47.0
    controlsbooleantrue否
    是否显示全部播放控件。
    		1.47.0
    object-fitenumcontain否
    当视频大小与 video 容器大小不一致时，视频的表现形式。
    • contain（包含）
    • fill（填充）
    • cover（覆盖）
    		1.47.0
    play-btn-positionenumcenter否
    播放按钮的位置。
    • center（视频中间）
    • bottom（控制条上）
    		1.47.0
    vslide-gesturebooleanfalse否
    在非全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。
    		2.3.0
    vslide-gesture-in-fullscreenbooleantrue否
    在全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量。
    		2.3.0
    enable-progress-gesturebooleanfalse否
    是否开启控制进度的手势，开启后表现详见手势响应-播放进度。
    		2.3.0
    enable-play-gesturebooleanfalse否
    是否开启播放手势，即双击切换播放/暂停。
    		2.3.0
    mutedbooleanfalse否
    是否静音播放。
    		2.4.0
    show-mute-btnbooleanfalse否
    是否显示静音控件，仅在全屏时显示。
    		2.4.0
    show-playback-rate-btnbooleanfalse否
    是否显示倍速控件，仅在全屏时显示。点击倍速控件后可选择倍速，可选值： 0.75/1.0/1.25/1.5/2。
    		2.5.0
    directionenum-90否

    设置全屏时视频的方向。

    		2.13.0
    enable-play-in-backgroundbooleanfalse否
    video 播放时宿主退出后台后开启小窗播放，iOS 14 及以上版本支持。开启时首次退出后台后给予弹窗提示用户授权，授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放。
    		2.16.0
    signatureSignature无否

    设置署名水印。

    		2.48.0
    initial-timenumber0否
    指定视频的初始播放位置。
    		2.80.0
    show-screen-lock-buttonbooleanfalse否
    是否展示锁屏按钮，仅在全屏时展示，锁屏后会锁定播控/手势的操作。
    		2.80.0
    definitionDefinition无否

    清晰度，设置清晰度列表和默认播放的清晰度。切换清晰度按钮仅在全屏时展示，属性说明详见 文档下面的 Definition 类型说明。需要保证 src 和 definition 中有一个为必填，若同时设置了 src 和 definition，definition 优先级高于 src。

    		2.80.0
    show-progressbooleantrue否
    是否展示中间的播放进度条。
    		2.90.0
    show-bottom-progressbooleantrue否
    是否展示底部的播放进度条。
    		2.90.0
    poster-sizestringcontain否
    视频的封面图片大小与 video 容器大小不一致时，封面图片的表现形式。
    • contain（包含）
    • fill（填充）
    • cover（覆盖）
    		2.90.0
    duration-limitnumber否
    限制视频的最大可播放时长，用于试看等场景。
    		2.90.0
    bindplayfunction无否
    当开始播放时触发 play 事件。
    		1.0.0
    bindpausefunction无否
    当暂停播放时触发 pause 事件。
    		1.0.0
    bindendedfunction无否
    当播放到末尾时触发 ended 事件。
    		1.0.0
    binderrorfunction无否
    视频播放出错时触发 error 事件。
    		1.0.0
    bindtimeupdatefunction无否
    播放进度变化时触发，返回当前播放时间点及视频总时长，单位：秒(s)。`event.detail = { currentTime, duration }`。
    		1.18.0
    bindprogressfunction无否
    视频缓冲进度更新时触发，`event.detail = { buffered }`。其中 buffered 是百分比，取值是 [0, 100] 中的整数，如 buffered 为 50 表示当前视频缓冲了 50%。
    		2.65.0
    bindfullscreenchangefunction无否
    视频进入和退出全屏时触发，`event.detail = { fullScreen, direction}`，其中 direction 仅在 fullScreen 字段为 true 时存在，有效值为 vertical 或 horizontal。
    		1.18.0
    bindcontrolstogglefunction无否
    切换播放控件显示/隐藏时触发。`event.detail = { show }`。
    		2.90.0
    bindwaitingfunction无否
    视频出现缓冲时触发。
    		1.47.0
    bindloadedmetadatafunction无否
    视频元数据加载完成时触发。`event.detail = {width, height, duration}`。
    		1.90.0
    bindseekcompletefunction无否
    seek 完成时触发。返回 seek 完成后的播放时间点，单位：秒(s)。`event.detail={position}`。
    		2.11.0
    bindplaybackratechangefunction无否
    视频倍速改变完成时触发。返回改变后的倍速值。`event.detail={playbackRate}`。
    		2.11.0
    bindmutechangefunction无否
    静音状态改变完成时触发。返回当前是否静音。`event.detail={isMuted}`。
    		2.11.0
    bindcontroltapfunction无否
    点击控件时触发。返回当前点击的控件类型。`event.detail={controlType}`，取值见表 controlType 的合法值。
    		2.11.0
    bindenterbackgroundfunction无否
    进入小窗播放时触发。
    		2.16.0
    bindclosebackgroundfunction无否
    关闭小窗播放时触发。
    		2.16.0
    bindleavebackgroundfunction无否
    离开小窗进入 app 事件时触发。
    		2.16.0
    enable-dark-water-markbooleanfalse否

    是否开启界面暗水印功能，用于视频防盗录场景。暗水印解码效果需要根据实际情况而定。小程序使用了暗水印能力后出现的盗录场景，可以拉客服咨询。

    		2.98.0
    encrypted-tokenstring无否

    对视频内容的传输过程进行加密，通过 encrypted-token 设置通用加密（CENC）的解密 key，加密流程见 FFmpeg通用加密，IDE 暂不支持。

    		2.98.0
    show-casting-buttonbooleanfalse否

    是否显示投屏按钮/菜单，仅在全屏时展示（当前仅支持 Android，iOS 敬请期待）。

    		3.2.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

    错误码

    errorCodeerrMsgerrorType说明最低支持版本
    137909error code = -9999 或 domain:kTTVideoErrorDomainFetchingInfo, code:-9999D

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

    建议检查api参数

    		1.0.0
    137904domain:kTTVideoErrorDomainVideoOwnPlayer, code:-1414092869U

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

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

    		1.0.0
    137907domain:kTTVideoErrorDomainVideoOwnPlayer, code:-5D

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

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

    		1.0.0
    137906domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499896D

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

    建议更换视频网址

    		1.0.0
    137901domain:kTTVideoErrorDomainVideoOwnPlayer, code:-101, internalCode:0, description:F
    小程序框架内部错误，有需要请拉客服咨询

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

    		1.0.0
    137905domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499897U

    403，禁止访问

    建议更换视频网址

    		1.0.0
    137902domain:kTTVideoErrorDomainFetchingInfo, code:-9994D

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

    检查网络

    		1.0.0
    137903error code = -499793D

    TCP请求网络超时

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

    		1.0.0
    137908error code = -499894D

    HTTP_OTHER_4xx

    建议更换视频网址

    		1.0.0
    137910domain:kTTVideoErrorDomainVideoOwnPlayer, code:-113D

    播放器dns解析错误

    建议更换视频网址

    		1.0.0
    137911domain:kTTVideoErrorDomainVideoOwnPlayer, code:-499745F
    小程序框架内部错误，有需要请拉客服咨询

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

    		1.0.0
    137912error code = -499899D

    400 ，请求出错

    建议更换视频网址

    		1.0.0
    137913domain:kTTVideoErrorDomainVideoOwnPlayer, code:-13D

    linux系统错误码Permission denied

    		1.0.0
    137914error code = -1003F
    小程序框架内部错误，有需要请拉客服咨询
    		1.0.0
    137915error code = -1009F
    小程序框架内部错误，有需要请拉客服咨询
    		1.0.0
    137916domain:kTTVideoErrorDomainVideoOwnPlayer, code:-1094995529F
    小程序框架内部错误，有需要请拉客服咨询

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

    		1.0.0
    137917error code = -1020F
    小程序框架内部错误，有需要请拉客服咨询
    		1.0.0
    137918domain:kTTVideoErrorDomainVideoOwnPlayer, code:-111D

    响应reponse为空

    		1.0.0
    137919error code = -499982U

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

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

    		1.0.0
    137920error code = -1001D

    请求超时

    		1.0.0
    137921error code = -499975D

    网络错误，连接失败

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

    		1.0.0
    137922error code = -499799D

    tcp层解析域名失败

    建议更换视频网址

    		1.0.0
    137923error code = -9996D

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

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

    		1.0.0
    137924error code = -499893D

    http 5xx服务器错误

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

    		1.0.0
    137926domain:kTTVideoErrorDomainVideoOwnPlayer, code:-2U

    用户主动离开

    无需处理

    		1.0.0
    137927error code = -1U

    用户主动离开

    无需处理

    		1.0.0
    137930error code = -499960D

    视频数据有错

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

    		1.0.0
    137931error code = -499798D

    tcp层解析域名超时

    建议更换视频网址

    		1.0.0
    137932error code = -499981D

    打开解码器失败

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

    		1.0.0
    137950domain: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分段下载。如短期内无法支持，请联系平台处理。​
    ​
    ​