抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 组件概述
  • 基础内容
  • 视图容器
  • 表单
  • 导航
  • 媒体
  • image 图片
  • video 视频
  • live-player 实时视频播放器
  • live-preview 直播预览流组件
  • camera 相机
  • rtc-room组件
  • 画布
  • 地图
  • 开放能力
  • 行业开放
  • 原生组件
  • 拓展组件
  • 小程序智能体
  • 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
    playback-rate-listArray<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
    bindplaybackratelistchangefunction

    当传入的 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 类型的参数,属性如下:

    属性名类型说明最低支持版本
    playbackRateListArray<number>

    最终被设置到界面上的 playbackRateList

    1.0.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分段下载。如短期内无法支持,请联系平台处理。