抖音开放平台Logo
开发者文档
小程序
控制台
  • 开发教程与代码示例
  • 入门
  • 小程序框架
  • 小程序运行时
  • 自定义组件
  • 基础教程
  • 小程序登录
  • 用户登录态签名
  • 开发 web-view 组件
  • 开发 video 视频组件
  • 3分钟调通code2session
  • 在网络资源请求添加 referer 规则
  • 画布
  • 分包加载
  • 流加载
  • 小程序webhook
  • 多线程 Worker
  • 播放加密视频
  • 视频诊断工具
  • 实现转发和挂载
  • 获取页面节点信息
  • 响应显示区域变化
  • 敏感数据处理
  • 能力教程
  • 性能优化
  • 安全

    • 开发 video 视频组件

    收藏
    我的收藏

    提供多清晰度视频

    本文将带你深入学习 video 组件，内容包含多清晰度、常见的播放问题及处理、建议转码配置以及视频内容防盗。
    视频显示效果、声音效果，与用户带宽情况天然存在冲突，开发者的视频码率普遍较高，但用户带宽情况不一定能够满足播放要求，从而引发视频起播慢、卡顿等播放问题。以一个真实 1080P 视频为例，其码率为 3716 kbps，如果用户网速 300kb/s，那么粗估每 1 秒视频至少需要下载 1.55 秒，必然无法快速起播并保持流畅播放。
    建议开发者同时提供多清晰度视频，既能保证网络状态良好的用户可观看效果更好的视频，又能避免网络状态较差的用户遭遇播放问题。多清晰度视频功能预览如下：
    我们建议使用 video 属性 definition 来实现多清晰度功能，使用接口文档详见 definition-类型说明。
    <!--index.ttml-->
<video definition="{{definition}}" ... />
    // index.js
Page({
  data: {
    definition: {
      list: [
        {
          name: "480P",
          url: "https://test.com/480P.mp4",
        },
        {
          name: "720P",
          url: "https://test.com/720P.mp4",
        },
        {
          name: "1080P",
          url: "https://test.com/1080P.mp4",
        },
      ],
      defaultDefinition: "480P",
    },
  },
});
    您也可以自行实现多清晰度视频功能：
      1.添加切换清晰度按钮，按钮文案为“极速”、“流畅”、“清晰”、“高清”、“超清”和“4K”。
      2.点击切换清晰度按钮，展示清晰度列表选项，文案为“360P 极速”、“480P 流畅”、“720P 清晰”、“1080P 高清”、“2K 超清”和“4K”。
      3.点击清晰度列表选项，通过修改video组件的src属性来更换播放链接，并同步播放进度。
        同步播放进度，请使用 video 组件的initial-time属性。

    倍速播放

    在抖音 App 中，用户已经养成了长按视频画面可倍速播放的心智，在观看抖音小程序视频时会下意识地长按视频画面，若无倍速播放反馈，会有挫败感。同时，倍速播放也是抖音小程序用户反馈中的高频诉求。
    您可以这样实现倍速播放：
      1.在用户长按视频画面时，通过 VideoContext.playbackRate 修改倍速为2倍速，并显示“2x 快进中”。
      2.在用户取消长按时，通过 VideoContext.playbackRate 修改倍速为1倍速，并停止显示“2x 快进中。
    <!--index.ttml-->
<video
    bindlongtap="bindlongtap"
    bindtouchend="bindtouchend"
    .../>
    bindlongtap: function(e) {
  // 修改倍速
  this.data.videoContext.playbackRate(2.0)
  // 显示“2x 快进中”
  // 代码略
},
bindtouchend: function(e) {
  // 还原倍速
  this.data.videoContext.playbackRate(1.0)
  // 隐藏“2x 快进中”
  // 代码略
}
    您也可以为长按增加震动反馈，详见 tt.vibrateShort。

    常见播放问题及处理建议

    在使用 video 组件时，容易遇到视频无法播放、起播慢、卡顿和画面变形问题，本节将围绕这些常见问题提供原因定位判断方式，以及处理建议。

    视频无法播放

    可能原因
    判断方式
    处理建议
    无效的视频链接
      1.如果视频是 mp4 格式，可在电脑Chrome浏览器中查看是否可播放。
      2.如果视频是 m3u8 格式，可在 https://m3u8play.com/ 中查看是否可播放
      3.您也可以下载安装 VLC media player 来查看是否可播放。
      1.检查视频链接完整性。
      2.联系您的视频云服务商或 CDN 服务商。
    没有创 建video 组件或链接为空
    看似简单的原因，却是引发视频无法播放问题的主要原因。判断方式详见下文中的用户反馈截图信息。
      1.确保创建 video 组件的前置流程顺畅。
      2.避免创建 video 组件但不传入src，或传入其他不正确链接。
    不支持的视频封装、编码格式
      1.查看 video 组件的封装、编码格式支持范围文档。
      2.使用 ISOBMFF Box Structure Viewer 在线查看目标视频的封装、编码格式。以下是操作步骤：选择文件，点击 loadFile Overview 中的 MIME 字段会包含视频的封装、编码格式信息如video/mp4; codecs="avc1.64001f,mp4a.40.2"; profiles="isom,iso2,avc1,mp41"，其中的video/mp4表示封装格式为 mp4，其中的avc表示编码格式为H.264如video/mp4; codecs="hvc1.2.4.H153.b0,lpcm"; profiles="qt "，其中的video/mp4表示封装格式为 mp4，其中的hvc表示编码格式为 H.265。
      3.检查目标视频的封装、编码格式是否在 video 组件的支持范围之内。
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播）。
      2.可使用开源多媒体框架 FFmpeg 转换格式。
    CDN Referer 限制
      1.视频在抖音开发者工具和浏览器中可播放，但是在真机上无法播放。
      2.CDN的Referer配置为白名单类型，且抖音小程序Referer不在白名单列表内。
    将 tmaservice.developer.toutiao.com 添加到 CDN Referer 白名单列表。
    不支持的封装格式细节
      1.如果是m3u8格式视频，您可下载m3u8文本文件，搜索是否包含不支持的 EXT-X-DISCONTINUITY 标签。
      2.如果是m3u8格式视频，您可通过Postman等工具查看响应标头是否包含不支持的transfer-Encoding: chunked 信息。
      1.联系您的视频云服务商，避免 m3u8 格式视频包含不支持的 EXT-X-DISCONTINUITY 标签。
      2.联系您的视频云服务商，避免 m3u8 格式视频的响应标头包含的 transfer-Encoding: chunked 信息。
    不合理的视频码率、视频文件不适合流媒体播放
    判断方式详见下文中的1.2 视频起播慢、卡顿。
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播），降低码率并进行流媒体播放优化。
      2.可使用开源多媒体框架 FFmpeg，降低码率并进行流媒体播放优化。
    如已经排除上述原因，请按照如下步骤联系小程序平台处理。
      1.在无法播放的页面，等待 1~2 分钟，直到 video 组件上显示“网络异常，请检查网络设置”。
      2.点击页面右上角的反馈按钮，填写“补充描述”，完成反馈。
      3.通过抖音开放平台-社区发帖提问，或点击抖音开放平台右下角的在线咨询，描述问题，并告知“补充描述”内容。

    视频起播慢、卡顿

    可能原因
    判断方式
    处理建议
    不合理码率
    检查视频码率是否大于 1500 kbps 使用 ISOBMFF Box Structure Viewer 在线查看码率。以下是操作步骤：选择文件，点击 loadFile Overview 中的 Bitrate 字段会显示视频轨和音频轨码率。
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播），配置更低的码率，我们提供了转码配置建议，详见3. 转码配置。
      2.可使用开源多媒体框架 FFmpeg 转码处理。
    音视频轨未均匀交织
      1.检查音视频轨是否未均匀交织使用 ISOBMFF Box Structure Viewer 在线查看码率。以下是操作步骤：选择文件，点击 loadSample View，View type 选择 Sample Map，查看音频轨和视频轨是否均匀交织。
      2.均匀交织的正确示例。
      3.未均匀交织的错误示例。
    ​
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播）。
      2.可使用开源多媒体框架 FFmpeg 转码处理。
    moov 未倒置
      1.检查 moov 是否未倒置使用 ISOBMFF Box Structure Viewer 在线查看码率。以下是操作步骤：选择文件，点击 loadBox View，查看 Tree View 中 moov 和 mdat 的顺序，预期 moov 应该在 mdat 之前。
      2.moov 已倒置的正确示例。
      3.moov未倒置的错误示例。
    ​
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播）。
      2.可使用开源多媒体框架 FFmpeg 转换格式。

    视频画面变形

    可能原因
    判断方式
    处理建议
    视频源原因
      1.如果视频是 mp4 格式，可在电脑 Chrome 浏览器中播放，查看画面是否正常，如果不正常则为视频源原因。
      2.如果视频是 m3u8 格式，可在 https://m3u8play.com/ 中播放，查看画面是否正常，如果不正常则为视频源原因。
      3.您也可以下载安装 VLC media player 来查看画面是否正常，如果不正常则为视频源原因。
    使用画面正常的视频资源。
    使用错误的填充方式
      1.检查 Video 组件的 object-fit 属性设置，是否为 fill，且 Video 组件的宽高比与视频资源的宽高比不一致。
    将 object-fit 属性设置为 contain。
    不支持的 SAR 像素宽高比
      1.视频在上述其他播放器中播放，画面正常。
      2.在线使用 FFmepg 查看视频的 SAR 比例是否非 1:1 访问网页 https://freetoolonline.com/ffmpeg-online.html 点击Drag and drop files or click to select按钮，选择待诊断的视频文件，等待上传完成点击Execute按钮，等待输出查看输出中的SAR信息，例：Stream #0:0(und): Video: h264 (High) (avc1 / 0x31637661), yuv420p, 1280x720 [SAR 1:1 DAR 16:9], 628 kb/s, 30 fps, 30 tbr, 30k tbn, 60 tbc (default)。
      1.推荐使用视频云服务商的转码服务（如火山引擎-视频点播），将SAR调整为 1:1。
      2.可使用开源多媒体框架 FFmpeg 转码处理，将 SAR 调整为 1:1。

    用户反馈截图信息

    用户反馈时，会自动在页面截图的 video 组件显示区域打印播放信息，这些播放信息可帮助快速定位 video 无法播放问题。以下是截图示例。
    开发者处理用户反馈时，可查看截图中 video 组件显示区域的播放信息，根据播放信息判断问题原因并处理。
    以下是播放信息说明：
      1.当前所处的播放生命周期（status）：
      ◦创建 video 中（onCreate）
      ◦正在准备播放（onPrepare）
      ◦已准备好播放（onPrepared）
      ◦缓冲中（onBufferStart）
      ◦缓冲结束（onBufferEnd）
      ◦遇到报错（onError(code=XXX, msg=XXX)）
      2.组件状态是否为已隐藏（hidden）。
      3.组件宽高（width、height）。
      4.视频链接（source）。
    以下是建议的判断流程：

    建议转码配置

    如果您想只提供一种清晰度视频，且希望兼顾视频画质和用户带宽情况，可以参考下述转码配置。如果是宽高比为 9:16 的视频，转码后的视频分辨率为 540*960，码率为 820 kbps 左右，视频画质良好。
    视频转码配置：
    转码模式
    标准转码
    封装格式
    MP4或HLS
    HLS分片时长（如果封装格式为HLS）
    5 秒
    清晰度
    540P
    ​
    视频编码格式
    H.264
    画质档位
    标准
    CRF 质量等级
    23
    最大码率
    4000 kbps
    帧率
    跟随片源最大帧率 30
    音频编码格式
    AAC
    HE-AACv2
    关闭
    采样率
    44100 Hz
    音频码率
    128
    声道
    双
    音量均衡
    关闭

    防盗链

    视频文件加密

    抖音小程序支持 MPEG 通用加密（也称为 MPEG-CENC），您可以使用 FFmpeg 对视频文件进行加密，使用 video 组件播放时通过 encrypted-token 属性设置秘钥 key。这一功能可保证视频文件的网络传输安全，但您仍需要避免明文传输秘钥 key。以下是操作步骤：
      1.进入 FFmpeg官方网站安装 FFmpeg 开源框架。
      2.通过 ffmpeg 命令对视频进行加密。 encryption_scheme 加密方案，目前仅支持 cenc-aes-ctrencryption_key 加密密钥，32 位 hex 数据 encryption_kid 加密密钥标识，32 位 hex 数据。
    ffmpeg -i sample.mp4 -vcodec copy -acodec copy -encryption_scheme cenc-aes-ctr -encryption_key 76a6c65c5ea762046bd749a2e6****** -encryption_kid a7e61c373e219033c21091fa60****** encrypted.mp4
      3.在 video 组件 encrypted-token 属性中，配置视频对应的 decryption_key。
    <!--index.ttml-->
<video
    id="myVideo"
    src="https://xxx/encrypted.mp4"
    encrypted-token="76a6c65c5ea762046bd749a2e6******"
</video>
      4.成功播放加密视频。

    Referer 白名单

    Referer 是 HTTP 请求中的一个请求头，表示请求是来自哪个站点页面的。Referer 头部指示了源页面的 URL，包含协议、域名、端口、路径与查询参数，其中端口是可选的。
    Referer 头部的作用之一是防盗链，您可以为抖音小程序配置一个 Referer 白名单，只允许接受来自抖音小程序的请求。
    抖音小程序的 Referer 是<a href="http://tmaservice.developer.toutiao.com" target="_blank" rel="nofollow noreferrer">tmaservice.developer.toutiao.com</a>。

    防录屏

    禁止用户录屏

    抖音小程序在 Android 和 iOS 端都提供了禁止用户录屏的 API，即 tt.disableUserScreenRecord 和 tt.enableUserScreenRecord。开启禁止用户录屏功能后，用户的录屏视频不会包含小程序页面内容。
    以下是使用建议：
      1.在播放视频或打开包含 video 组件的页面时，通过调用tt.disableUserScreenRecor rd来禁止用户录屏。
      2.在结束视频播放或离开包含 video 组件的页面时，通过调用 tt.enableUserScreenRecord 来取消进行用户录屏。

    播放器暗水印

    目前播放器同时支持署名水印和暗水印。
    署名水印是用户可看到的水印，可自定义水印位置、内容和颜色，对盗录者有警示作用，对用户体验有一定影响，溯源信息有限。
    暗水印是用户看不见的水印，不会影响用户体验，溯源信息丰富。
    以下是暗水印的代码示例：
    <!--index.ttml-->
<video enable-dark-water-mark="{{true}}" .../>
    如在开启暗水印能力后出现盗录情况，可以拉平台客服咨询溯源。
    ​