文档中心

视频点播

Web 播放器 SDK

进阶功能

本文为您介绍如何实现 VePlayer 提供的进阶功能。

播放 HLS 标准加密视频

VePlayer 可播放由视频点播媒体处理服务生成的 HLS 标准加密视频，以满足用户对版权视频安全播放的需求。

兼容性说明

系统/浏览器	说明
PC Chrome	支持 34 以上版本。
PC Edge	部分支持 Windows 10 及以上。
移动端 iOS	部分支持 iOS 10 及以上系统。注意不支持 iOS 11.2 - 11.4 的系统。
移动端 Android	部分支持 Android 5 及以上系统。注意不支持播放器被劫持环境，如 UC 浏览器、QQ 浏览器以及部分手机厂家自带的浏览器（例如，VIVO）。

已知限制

VePlayer 播放 HLS 标准加密视频存在以下已知限制：

对于移动端 Android 系统，不支持在 UC 浏览器、QQ 浏览器以及部分手机厂商（如 VIVO）自带浏览器等播放器被劫持环境中使用。
对于移动端 iOS 系统，不支持 11.2 - 11.4 的版本（国内影响范围 0.65% 以内）。

对于不支持的浏览器环境，建议您进行风险评估，减少在这类环境下加密视频内容的投放或引导用户跳转至 App 端播放。

前提条件

通过视频点播媒体处理服务转码输出 HLS 标准加密视频。详见 HLS 标准加密。
应用服务端生成并下发 HLS 标准加密 Token 给应用客户端用于解密。视频点播服务端 SDK 提供接口用于签发 HLS 标准加密 Token，详见以下文档：

实现方式

VePlayer 支持通过 Vid 和 DirectUrl 两种模式播放 HLS 标准加密视频，具体说明如下：

Vid 模式

DirectUrl 模式

通过 Vid 模式播放时，您需要设置 getVideoByToken 参数传入 playAuthToken 和 keyToken。详细参数介绍请见 IPlayAuthTokenConfig。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  getVideoByToken: {
    playAuthToken: 'playAuthToken', // 从应用服务端获取的临时播放 Token
    keyToken: 'keyToken' // 从应用服务端获取的 HLS 标准加密 Token
  }
});

通过 DirectUrl 模式播放时，除了视频地址 url，还需设置 EncryptHlsPlugin 参数传入 keyToken。详细参数介绍请见 IEncryptHlsPluginConfig。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  url: 'hls的加密视频地址',
  EncryptHlsPlugin: {
    keyToken: '解密用的keyToken', // 从应用服务端获取的 HLS 标准加密 Token
  }
})

切换视频

如想在不销毁播放器的情况下更换视频源，可调用播放器实例的 playNext 方法。Vid 和 DirectUrl 两种模式均支持通过这种方式切换视频。

Vid 模式

DirectUrl 模式

Vid 模式下切换视频的示例代码如下：

playerSdk.playNext({
  getVideoByToken: {
    playAuthToken: 'new playAuthToken', // 新的 playAuthToken
    keyToken: 'new keyToken' // 新的 keyToken
  }
});

DirectUrl 模式下切换视频的示例代码如下：

playerSdk.playNext({
   url: 'new url', // 新的 HLS 加密视频播放地址
  EncryptHlsPlugin: {
    keyToken: 'new keyToken' // 新的 keyToken
  }
});

播放私有加密视频（新版）

兼容性说明

Web 播放器 SDK 支持播放 HLS、MP4 和 DASH 格式的私有加密视频。具体兼容性说明如下表所示。

系统/浏览器	说明
PC Chrome	支持 34 以上版本的 HLS、MP4、DASH 的格式/协议。
PC Edge	支持 Windows 10 及以上系统的 HLS、MP4、DASH 的格式/协议。
移动端 iOS	支持 iOS 10 及以上版本系统，请注意不支持 iOS 11.2 至 11.4 版本的系统。仅兼容 HLS 协议。因 iOS 系统浏览器缺乏 MSE 等必要的 API，故无法支持 MP4 格式及 DASH 协议。
移动端 Android	支持 Android 5 及以上版本的系统，支持 HLS、MP4、DASH 格式/协议。需注意，在播放器被劫持的环境下该功能无法正常使用，这类环境包括但不限于 UC 浏览器、QQ 浏览器，以及部分手机厂商自带的浏览器（如 VIVO 手机自带浏览器）。

注意

不支持线上 HTTP 环境，但不影响在本地 localhost 及 127.0.0.1 环境下进行调试。

前提条件

播放前，请确保您已通过视频点播转码服务输出私有加密视频，详见火山引擎私有加密（新版）。

Vid 模式播放

在 Web 播放器 SDK 的 Vid 模式下，整体的解密播放流程如下：

生成 UnionInfo 和 DrmKek：调用播放器 SDK 的 generateEncryptInfo 接口生成 sessionId、drmKeK 和 unionInfo，示例代码如下：
```
const unionId = 'user_xxxx'; // 设备唯一 ID
const format = 'hls'; // 播放私有加密视频格式，取值支持 hls、mp4、dash
const {drmKeK，unionInfo，sessionId} = await VePlayer.generateEncryptInfo(unionId， format);
```
- 入参：
  - unionId：设备唯一标识符，用于确保密钥与设备一一对应，从而提高安全性。
  - format：所需播放视频的格式。若需播放多种格式的视频，则需多次调用此方法。
- 出参：
  - drmKeK：已混淆的加密公钥，用于后续步骤生成临时播放 Token。
  - unionInfo：设备唯一信息，用于后续步骤生成临时播放 Token。
  - sessionId：私有加密会话标识符，用于后续初始化播放器。
说明
generateEncryptInfo 方法仅需调用一次。调用该方法后，直至播放器完成初始化之前，请勿刷新或跳转页面。
请求临时播放 Token：携带上一步所生成的 drmKeK 和 unionInfo，向业务的 Web 应用服务端发起请求，以生成临时播放 Token。应用服务端通过视频点播服务端 SDK 本地签发临时播放 Token，然后下发给客户端。服务端在生成 Token 时，需将 FileType 设为 private_evideo，JSPlayer 设为 1，UnionInfo 设为播放器 SDK 生成的 unionInfo，DrmKEK 设为播放器 SDK 生成的 drmKeK。具体示例代码，请见以下文档：

创建播放器：参考以下示例代码初始化播放器。需将 encryptSessionId 为步骤 1 中 generateEncryptInfo 方法返回的 sessionId，drmType 设为 private_encrypt_upgrade。

const playerSdk = new VePlayer({
    id: 'mse',
    lang: 'zh',
    width: 640,
    height: 360,
    defaultDefinition: '720p',
    drmType: 'private_encrypt_upgrade', // 加密类型为私有加密（新版）
    encryptSessionId: sessionId, // generateEncryptInfo 方法返回的 sessionId
    getVideoByToken: {
      playAuthToken: 'playAuthToken with unionInfo and KEK', // 应用服务端下发的临时播放 Token，包含 unionInfo 和 drmKeK 信息
    },
});

请求播放信息：播放器 SDK 自发向点播服务端发起请求以获取视频信息。点播服务端会对播放密钥进行多次加密处理，从而最大程度地提高密钥的安全性。最终，点播服务端会将视频地址和经过加密的播放密钥返回给播放器 SDK。
请求加密视频内容：播放器 SDK 内部通过 PlayUrl 向点播 CDN 请求加密视频内容。
解密播放：播放器 SDK 基于 sessionId 与加密后的播放密钥，解析出真实密钥（此过程于沙盒环境中执行，极难被探测、调试和篡改），最终使用该密钥对视频进行解密并播放。

（可选）切换视频：调用 palyNext 方法并传入新视频的临时播放 Token。

playerSdk.playNext({
  getVideoByToken: {
    playAuthToken: token, // 新的临时播放 Token
  },
});

DirectUrl 模式播放

在 Web 播放器 SDK 的 DirectUrl 模式下，整体的解密播放流程如下：

生成 UnionInfo 和 DrmKek：调用播放器 SDK 的 generateEncryptInfo 接口生成 sessionId、drmKeK 和 unionInfo，示例代码如下：
```
const unionId = 'user_xxxx'; // 设备唯一 ID
const format = 'hls'; // 播放私有加密视频的格式，取值支持 hls、mp4、dash
const {drmKeK，unionInfo，sessionId} = await VePlayer.generateEncryptInfo(unionId， format);
```
- 入参：
  - unionId：设备唯一标识符，用于确保密钥与设备一一对应，从而提高安全性。
  - format：所需播放视频的格式。若需播放多种格式的视频，则需多次调用此方法。
- 出参：
  - drmKeK：已混淆的加密公钥。
  - unionInfo：设备唯一信息。
  - sessionId：私有加密会话标识符，用于后续初始化播放器。
说明
generateEncryptInfo 方法仅需调用一次。调用该方法后，直至播放器完成初始化之前，请勿刷新或跳转页面。
请求视频地址和播放密钥：携带上一步生成的 drmKeK 和 unionInfo，向业务的 Web 应用服务端发起请求。应用服务端通过视频点播服务端 SDK 调用 GetPlayInfo 接口获取视频播放地址及播放密钥。请求参数中：
- FileType 设为 private_evideo
- JSPlayer 设为 1
- UnionInfo 设为播放器 SDK 生成的 unionInfo
- DrmKEK 设为播放器 SDK 生成的 drmKeK
  点播服务端在接收到请求后，会对播放密钥进行多次加密处理，从而最大程度地提高密钥的安全性。最终，点播服务端会将视频地址以及加密后的播放密钥返回给业务的 Web 应用服务端，即返回参数中的 PlayAuthId（密钥 ID）和 PlayAuth（加密后的密钥）。
说明
具体示例代码，请见以下文档：
创建播放器：参考以下示例代码初始化播放器。关注以下参数：
- encryptSessionId 为步骤 1 中 generateEncryptInfo 方法返回的 sessionId
- drmType 设为 private_encrypt_upgrade。
- playAuth 和 PlayAuthId 设为步骤 2 中获得的密钥 ID 和加密后的密钥。
```
const playerSdk = new VePlayer({
    id: 'mse',
    lang: 'zh',
    width: 640,
    height: 360,
    streamType: 'hls',
    drmType: 'private_encrypt_upgrade', // 加密类型为私有加密（新版）
    encryptSessionId: sessionId, // generateEncryptInfo 方法返回的 sessionId
    url: 'xxx.demo.com/1.m3u8',
    playAuth: 'nLwS81+KFNpqkBPAW4sXxmmJIZmZ',
    playAuthId: 'xsdsdsdsd',
});
```
说明
若设置多个清晰度的播放源，实例化参数 playList 中的每项均需包含对应的 playAuth 和 playAuthId。
请求加密视频内容：播放器 SDK 内部通过 PlayUrl 向点播 CDN 请求加密视频内容。
解密播放：播放器 SDK 基于 sessionId 与加密后的播放密钥，解析出真实密钥（此过程于沙盒环境中执行，极难被探测、调试和篡改），最终使用该密钥对视频进行解密并播放。

（可选）切换视频：调用 palyNext 方法并传入新视频的 playAuth 和 playAuthId。

playerSdk.playNext({
  url: 'newUrl',
  playAuth: 'new playAuth',
  playAuthId: 'new playAuthId'
});

播放 DASH 视频

SDK 支持播放 BASH（经火山引擎优化的升级版 DASH 协议）视频流。应用服务端下发指定 BASH 格式的 PlayAuthToken，即可快速实现 BASH 视频的播放。如果是指定为加密的 BASH 视频，也能按照以下示例代码快速实现 DASH 格式的加密视频播放。

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  streamType: 'dash',
  getVideoByToken: {
    playAuthToken: '指定DASH格式且为加密视频的playAuthToken'
  }
});

面对一些灵活的需求场景时，您可自行获取 BASH 播放信息，并设置 VePlayer 的 BASH 播放配置。具体参数介绍请见 IDashPluginConfig。示例代码如下：

const Service = window.VePlayer.Service;

const playAuthToken = '指定DASH格式且为加密视频的playAuthToken';
Service.url(playAuthToken, '//vod.volcengineapi.com').then((res) => {
  // 业务侧处理 BASH 的相关配置
  const playerSdk = new VePlayer({
    id: 'mse',
    lang: 'zh',
    width: 800,
    height: 500,
    DASHPlugin: {
      vid: res.Vid,
      playInfoType: 'TOP',
      getLicenseUrl: '//i.snssdk.com/video/drm/v1/play_licenses',
      definitionText: { '360p': '流畅 360p', '480p': '清晰 480p', '720p': '高清 720p', '1080p': '超高清 1080p' },
      defaultDefinition: '360p',
      preloadTime: 180,
      defaultFormat: 'dash',
      dashOpts: { Data: res }
    }
  });
});

播放 H.265 视频

H.265 编码格式支持更高的压缩效率，相同的清晰度下，能够节省码率 40%，在保证画质的条件下，达到节省带宽流量的目的。VePlayer 支持播放 H.265 视频，能够为您节省流量。

兼容性说明

说明

移动端不推荐使用 DASH 进行播放，更推荐兼容性比较好的 HLS 和 MP4 格式。

系统/浏览器	说明
PC Chrome	支持 34 以上版本。
PC Edge	支持 Windows 10 及以上。
PC Safari	支持 Safari 13 及以上。
移动端 iOS	仅支持 iOS 11 及以上。注意播放 HLS 视频时，封装格式必须是 fMP4。如需通过视频点播转码服务生成 fMP4 的 HLS 视频，请提交工单联系技术支持。
移动端 Android	部分支持 Android 5 及以上。注意不支持播放器被劫持环境，如 UC 浏览器、QQ 浏览器。

开启 H.265 兼容模式

在不支持 H.265 的浏览器环境下设置 enableH265Degrade 为 true，开启 H.265 兼容模式进行适配播放。示例代码如下：

注意

该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。

const playerSdk = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    url: 'xx265.mp4',
    enableH265Degrade: true, // 开启 H.265 兼容模式
    codec: 'h265' // 视频编码格式
});

说明

如果开启了 H.265 兼容模式，且以 URL 形式播放，推荐提供视频的编码格式 codec，否则 VePlayer 会拉取码流进行编码格式自动检测，这将会消耗一定流量（约 300 kb），并延缓起播速度（约 0.5 秒）。

多码率自适应播放

多码率自适应播放是指给用户提供“自动”档位，在此档位下，VePlayer 会采用基于 HTTP 的自适应码率（ABR，Adaptive Bit-Rate）策略，选择最适合当前用户带宽环境和终端设备的码流播放，从而提升播放体验。您可以再将转码生成的自适应码流传递给 VePlayer，从而实现视频播放时根据网络环境自适应切换视频清晰度的功能。

注意

该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。

效果展示

VePlayer 会在清晰度列表中展示“自动”档位。用户切换到该档位时，VePlayer 开启多码率自适应播放，并实时展示当前真实档位。

兼容性说明

VePlayer 支持 HLS、DASH 和 MP4 格式的多码率自适应播放，具体兼容性说明如下表所示：

类别	平台	HLS	DASH	MP4
桌面端	Windows	Chrome > 57 Opera > 44 FireFox > 52 Edge > 16
桌面端	macOS	Chrome > 57 Safari > 11 FireFox > 52 Opera > 44 Edge > 16
移动端	iOS	Chrome > 57 Safari > 11	不支持	不支持
移动端	Android	Chrome > 57 Edge > 16 不支持手机自带浏览器，如小米手机自带浏览器。

前提条件

若您需要实现 Vid 模式下 HLS 和 DASH 视频的多码率播放，可通过视频点播自适应码流转码模板生成自适应码流文件。完整介绍请见自适应码流转码和播放。

播放 HLS 自适应码流

DirectUrl 模式：初始化 VePlayer 时，通过 playList 参数传入由视频点播媒体处理服务生成的子流及主流信息，并通过 autoBitrateOpts 参数配置多码率自适应播放。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  autoplay: true,
  streamType: 'hls',
  playList: [
    {
      // 子流 1 地址
      url: 'https://example.com/af2534***/*****1/stream2.m3u8',
      definition: '480p',
      bitrate: 274117,
      width: 854,
      height: 480,
      duration: 2665.698,
    },
    {
      // 子流 2 地址
      url: 'https://example.com/af2534***/*****1/stream2.m3u8',
      definition: '720p',
      bitrate: 502452,
      width: 1280,
      height: 720,
      duration: 2665.698,
    },
    {
      // 子流 3 地址
      url: 'https://example.com/af2534***/*****1/stream3.m3u8',
      definition: '1080p',
      bitrate: 502446,
      width: 1280,
      height: 720,
      duration: 2665.698,
    },
    {
      // master m3u8 主流地址
      url: 'https://example.com/af2534***/*****1/master.m3u8',
      definition: 'auto',
    },
  ],
  // 配置多码率自适应播放
  autoBitrateOpts: {
    enable: true, // 是否开启 ABR 功能。默认为 false
    startWithAuto: true, // 是否以自动档位起播。默认为 false
    showRealDefinition: true, // 自动档位是否展示真实清晰度，如 “自动（360p）”
    autoDefinitionText: '自动', // 自动档位显示文案。选填，不传则匹配 languages 的配置。
    definitionTextKey: 'DEFINITION_AUTO_DESC', // 自动档位国际化文案 key, 默认为 DEFINITION_AUTO
  },
  languages: {
    zh: {
      // 自动档位中文文案
      DEFINITION_AUTO_DESC: '自动',
    },
    en: {
      // 自动档位英文文案
      DEFINITION_AUTO_DESC: 'Auto',
    },
  },
});

Vid 模式：应用服务端生成临时播放 Token 时，将 Definition 设为 auto，将 Format 设为 hls，即可播放由视频点播媒体处理服务生成的自适应码流文件。您还可通过 autoBitrateOpts 参数配置多码率自适应播放。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  autoplay: true,
  getVideoByToken: {
    playAuthToken: 'playAuthTokenWhichDefinitionIsAuto',  // 
    needPoster: true,
  },
  // 配置多码率自适应播放
  autoBitrateOpts: {
    enable: true, // 是否开启 ABR 功能。默认为 false
    startWithAuto: true, // 是否以自动档位起播。默认为 false
    showRealDefinition: true, // 自动档位是否展示真实清晰度，如 “自动（360p）”
    autoDefinitionText: '自动', // 自动档位显示文案。选填，不传则匹配 languages 的配置。
    definitionTextKey: 'DEFINITION_AUTO_DESC', // 自动档位国际化文案 key, 默认为 DEFINITION_AUTO
  },
  languages: {
    zh: {
      DEFINITION_AUTO_DESC: '自动',
    },
    en: {
      DEFINITION_AUTO_DESC: 'Auto',
    },
  }
});

播放 DASH 自适应码流

对于 DASH 协议，VePlayer 仅支持 Vid 模式下的多码率自适应播放。在应用服务端生成临时播放 Token 时将 Definition 设为 auto，将 Format 设为 dash，即可播放由视频点播媒体处理服务生成的自适应码流文件。您还可通过 autoBitrateOpts 参数配置多码率自适应播放。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  autoplay: true,
  getVideoByToken: {
    playAuthToken: 'playAuthTokenWhichDefinitionIsAuto',
    needPoster: true,
  },
  // 配置多码率自适应播放
  autoBitrateOpts: {
    enable: true, // 是否开启 ABR 功能。默认为 false
    startWithAuto: true, // 是否以自动档位起播。默认为 false
    showRealDefinition: true, // 自动档位是否展示真实清晰度，如 “自动（360p）”
    autoDefinitionText: '自动', // 自动档位显示文案。选填，不传则匹配 languages 的配置。
    definitionTextKey: 'DEFINITION_AUTO_DESC', // 自动档位国际化文案 key, 默认为 DEFINITION_AUTO
  },
  languages: {
    zh: {
      DEFINITION_AUTO_DESC: '自动',
    },
    en: {
      DEFINITION_AUTO_DESC: 'Auto',
    },
  }
});

播放 MP4 自适应码流

视频点播自适应码流转码模板当前仅支持 HLS 和 DASH 协议。因此对于 MP4 协议，您需要自行准备播放源。您需要确保各个码率的视频之间做到 IDR 帧对齐，即确保转码输出的视频除了清晰度存在差别，其他参数均保持一致。

说明

IDR 帧（Instantaneous Decoding Refresh Picture）是一种特殊的 I 帧，它能够立即刷新图像，防止错误传播。与普通的 I 帧不同的是，IDR 帧之后的所有帧都不能引用该 IDR 帧之前的帧内容。这样做可以方便控制编码和解码流程，同时也能够实现视频的随机访问功能。在视频播放过程中，播放器通常会选择最接近指定位置的 IDR 帧进行播放，以避免复杂的反向解析过程。在多码率转码时，如果指定 IDR 帧对齐，可以保持输出视频的 IDR 帧在时间点和内容上的精确同步，从而实现多码率视频平滑切换，避免卡顿现象的出现。

DirectUrl 模式：初始化 VePlayer 时，通过 playList 参数传入多码率视频地址，并通过 autoBitrateOpts 参数配置多码率自适应播放。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  autoplay: true,
  playList: [
    {
      url: 'https://example.com/af2534***/*****1/stream2.mp4',
      definition: '480p',
      bitrate: 274117,
      width: 854,
      height: 480,
      duration: 2665.698,
    },
    {
      url: 'https://example.com/af2534***/*****1/stream2.mp4',
      definition: '720p',
      bitrate: 502452,
      width: 1280,
      height: 720,
      duration: 2665.698,
    },
    {
      url: 'https://example.com/af2534***/*****1/stream3.mp4',
      definition: '1080p',
      bitrate: 502446,
      width: 1280,
      height: 720,
      duration: 2665.698,
    },
  ],
  // 配置多码率自适应播放
  autoBitrateOpts: {
    enable: true, // 是否开启 ABR 功能。默认为 false
    startWithAuto: true, // 是否以自动档位起播。默认为 false
    showRealDefinition: true, // 自动档位是否展示真实清晰度，如 “自动（360p）”
    autoDefinitionText: '自动', // 自动档位显示文案。选填，不传则匹配 languages 的配置。
    definitionTextKey: 'DEFINITION_AUTO_DESC', // 自动档位国际化文案 key, 默认为 DEFINITION_AUTO
  },
  languages: {
    zh: {
      // 自动档中文文案
      DEFINITION_AUTO_DESC: '自动',
    },
    en: {
      // 自动档英文文案
      DEFINITION_AUTO_DESC: 'Auto',
    },
  },
});

Vid 模式：在应用服务端生成临时播放 Token 时，确保下发的视频之间做到 IDR 帧对齐。示例代码如下：

const playerSdk = new VePlayer({
    id: 'video',
    autoplay: true,
    getVideoByToken: {
      playAuthToken: 'playAuthTokenWhichDefinitionIsAuto',
      needPoster: true,
    },
    // 配置多码率自适应播放
    autoBitrateOpts: {
        enable: true, // 是否开启 ABR 功能。默认为 false
        startWithAuto: true, // 是否以自动档位起播。默认为 false
        showRealDefinition: true, // 自动档位是否展示真实清晰度，如 “自动（360p）”
        autoDefinitionText: '自动', // 自动档位显示文案。选填，不传则匹配 languages 的配置。
        definitionTextKey: 'DEFINITION_AUTO_DESC', // 自动档位国际化文案 key, 默认为 DEFINITION_AUTO
    },
    languages: {
        zh: {
          DEFINITION_AUTO_DESC: '自动',
        },
        en: {
          DEFINITION_AUTO_DESC: 'Auto',
        },
    }
});

事件监听

自动档位对应的清晰度发生变化时，SDK 会触发 'ABR_AUTO_DESC_CHANGE' 事件。

动态 Buffer

注意

该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。

默认情况下，VePlayer 针对 MP4 的 MSE 播放和 DASH 播放，设定了不同的最小 Buffer 时长，MP4 为 10 秒，DASH 为 50 秒。当剩余 Buffer 时长小于最小 Buffer 时长时，VePlayer 会开始加载新的视频数据。在此基础上，为了抵御网络抖动对播放体验造成的影响，并减少带宽成本浪费，VePlayer 支持动态 Buffer。动态 Buffer 是指在播放过程中，根据网络状况动态调整剩余 Buffer 时长，以提高播放体验并减少带宽成本浪费。通过动态调整剩余 Buffer 时长，VePlayer 可以在网络状况较差时保持较高的 Buffer 水位，以减少因缓存不足导致的播放体验问题；而在网络状况较好时，可以维持较低的 Buffer 水位，以减少对带宽的浪费。这样可以有效提高视频播放的流畅性和稳定性，同时优化网络资源利用。常规 Buffer 加载和动态 Buffer 加载的区别如下图所示：

按如下示例代码开启动态 Buffer 功能。您需要设置视频时长 duration，并通过 adaptRange 参数配置动态 Buffer 功能。您还需按照视频的格式及视频时长设置一个合理的高低水位（minCacheDuration和maxCacheDuration）。

new VePlayer({
   id: 'video',
   url: 'https://example.com/af2534***/*****1/stream.mp4',
   // 开启 MP4 MSE 播放
   enableMp4MSE: true,
   duration: 132,
   // 配置动态 Buffer
   adaptRange: {
      enable: true, // 开启动态 Buffer 功能
      // 低水位，单位为秒
      minCacheDuration: 12,
      // 高水位，单位为秒
      maxCacheDuration: 30,
   }
})

您可按照如下推荐值根据不同视频时长和不同视频格式设置高低水位：

视频时长	MP4	DASH
0-3 分	minCacheDuration: 6 秒 maxCacheDuration: 15 秒	minCacheDuration: 6 秒 maxCacheDuration: 15 秒
3 分-30 分	minCacheDuration: 10 秒 maxCacheDuration: 28 秒	minCacheDuration: 15 秒 maxCacheDuration: 30 秒
其它情况	minCacheDuration: 12 秒 maxCacheDuration: 30 秒	minCacheDuration: 30 秒 maxCacheDuration: 60 秒

预加载

VePlayer 提供视频资源预加载功能，支持手动执行预加载和 Feed 流视频播放场景下自动执行预加载，降低首帧耗时，优化起播体验。

注意

该功能仅高级版支持。请确保您已购买高级版的 License，详见播放器 License。

效果展示

视频起播阶段无需请求数据，直接使用预加载缓冲数据进行起播，效果如下图所示。

兼容性说明

封装格式：当前仅支持 MP4 格式。
播放模式：当前仅支持 DirectUrl 模式，暂不支持 Vid 模式。
播放环境：需要浏览器支持 MSE，适用于 PC、Android、iOS（仅支持 iOS 17.1 以上系统）。

工作原理

初始化预加载模块

调用 prepare 初始化预加载模块：

VePlayer.prepare({
  appId: number; // 应用 ID，您可在视频点播控制台应用管理页面获取
  strategies: {
     preload: boolean | IPreloadConfig; // 开启预加载高级能力，可设置 boolean 值直接使用默认配置，可以配置预加载初始参数
  }
})

说明

详细参数说明请见 IPreloadConfig。

手动执行预加载

手动模式下，您需要提前设置预加载资源列表。实例化播放器时如果该视频资源目标时长已加载完成，则直接使用预加载缓存数据起播，播放阶段从缓存数据往后继续下载新数据。

设置预加载模式为手动模式：
```
VePlayer.setPreloadScene(0)
```
设置预加载资源列表：
```
VePlayer.setPreloadList(list: IPreloadStream[])
```
说明
- 手动模式下播放器会将预加载资源全部添加至预加载任务队列。
- 播放器不会对已经在播放中的视频执行预加载。
- 详细参数说明请见 IPreloadStream。

使用预加载数据：

创建播放器实例：

new VePlayer({
    playList: [ IPreloadStream ], // 当前播放视频信息
    vid: 'xxxvid', // 视频唯一 ID
    enableMp4MSE: true, // 开启 MP4 MSE 模式播放
})

切换播放视频：

playerSdk.playNext({
   playList: [ IPreloadStream ], // 当前播放视频信息
   vid: 'xxxvid', // // 视频唯一 ID
})

自动执行预加载

VePlayer 针对 Feed 流视频播放场景提供自动预加载功能。设置待预加载资源列表后，播放器会根据当前播放视频的 ID 自动检索待预加载视频列表，将当前视频的前 prevCount 个和后 nextCount 个视频添加到预加载任务队列，并根据当前视频状态动态执行预加载操作。

设置预加载模式为自动模式并设置 prevCount 和 nextCount：

VePlayer.setPreloadScene(1,{
  prevCount: 1, // 加载当前播放视频前 1 个视频
  nextCount: 2, // 加载当前播放视频后 2 个视频
})

设置待预加载资源列表：

// 设置待预加载列表，根据当前播放视频的 ID，检索待预加载视频列表，将当前视频前 prevCount 个和后 nextCount 个加入预加载任务队列，根据当前视频状态执行预加载。
VePlayer.setPreloadList(list: IPreloadStream[])

说明

播放器不会对已经在播放中的视频执行预加载。
详细参数说明请见 IPreloadStream。

使用预加载数据：

创建播放器实例：

new VePlayer({
    playList: [ IPreloadStream ], // 当前播放视频信息
    vid: 'xxxvid', // 视频唯一 ID
    enableMp4MSE: true, // 开启 MP4 MSE 模式播放
})

切换视频：

playerSdk.playNext({
   playList: [ IPreloadStream ],// 当前播放视频信息
   vid: 'xxxvid', // // 视频唯一id
})

说明

创建播放器实例和切换视频时，播放器会根据 vid、playList 检索当前视频是否存在已预加载数据。如果存在已预加载数据，将直接使用该数据，并触发一次预加载任务检测。

播放私有加密视频（旧版）

火山引擎视频点播的私有加密方案采用火山引擎自研加密算法，安全级别高，能够便捷、高效、安全地保护您的音视频版权。

兼容性说明

VePlayer 支持播放 HLS、MP4 和 DASH 格式的私有加密视频。具体兼容性说明如下表所示。

系统/浏览器	说明
PC Chrome	支持 34 以上版本的 HLS、MP4、DASH 的格式/协议。
PC Edge	支持 Windows 10 及以上系统的 HLS、MP4、DASH 的格式/协议。
移动端 iOS	部分支持 iOS 10 及以上系统，仅支持 HLS 协议。注意不支持 iOS 11.2 ～ 11.4 的系统。由于 iOS 系统的浏览器缺少 MSE 等必要 API，无法支持 MP4 和 DASH 格式/协议。
移动端 Android	部分支持 Android 5 及以上系统，支持 HLS、MP4、DASH 的格式/协议。注意不支持播放器被劫持环境，如 UC 浏览器、QQ 浏览器以及部分手机厂家自带的浏览器（例如，VIVO）。

前提条件

通过视频点播媒体处理服务转码输出私有加密视频，详见火山引擎私有加密。
应用服务端生成并下发私有加密 Token 给应用客户端用于解密。视频点播服务端 SDK 提供接口用于签发私有加密 Token，详见以下文档：

实现方式

VePlayer 仅支持通过 Vid 模式播放私有加密视频。您需要在实例化播放器时传入 unionId、 getVideoByToken.playAuthToken 和 getVideoByToken.getDrmAuthToken 参数。具体参数说明，请见 IPlayerConfig。示例代码如下：

const playerSdk = new VePlayer({
    id: 'mse',
    width: 640,
    height: 360,
    // 唯一 ID。您自行设置，需要保证每一个用户的 unionId 是唯一的，没有其他格式限制。SDK 会使用这个 unionId 生成用于二次加密密钥的 unionInfo，有效时长为 30 秒
    unionId: 'veplayer_demo',
    getVideoByToken: {
      // 从应用服务端获取的临时播放 Tokeb
      playAuthToken: '加密视频的 playAuthToken',
      // 从应用服务端获取私有加密 Token 回调
      // SDK 内部自行通过 playAuthToken 从视频点播服务获取到 playAuthId
      getDrmAuthToken: (playAuthIds, vid, unionInfo) => {
        // SDK 内部携带 playAuthId、vid、unionInfo 向应用服务端请求获取私有加密 Token
        const request = window.fetch(`http://video-service.demo.com/api/GetDrmKeyToken/?kid=${encodeURIComponent(playAuthIds)}&vid=${vid}&uid=${unionInfo}`);
        return request.then(res => res.json()).then(data => data.result);
      }
    },
  });

注意

播放私有加密视频时，如需切换视频，您需要重新创建播放器。

最近更新时间：2025.08.25 14:49:33

这个页面对您有帮助吗？

有用

无用

视频点播

播放 HLS 标准加密视频 #

兼容性说明 #

已知限制 #

前提条件 #

实现方式 #

切换视频 #

播放私有加密视频（新版） #

兼容性说明 #

前提条件 #

Vid 模式播放 #

DirectUrl 模式播放 #

播放 DASH 视频 #

播放 H.265 视频 #

兼容性说明 #

开启 H.265 兼容模式 #

多码率自适应播放 #

效果展示 #

兼容性说明 #

前提条件 #

播放 HLS 自适应码流 #

播放 DASH 自适应码流 #

播放 MP4 自适应码流 #

事件监听 #

动态 Buffer #

预加载 #

效果展示 #

兼容性说明 #

工作原理 #

初始化预加载模块 #

手动执行预加载 #

自动执行预加载 #

相关 API #

播放私有加密视频（旧版） #

兼容性说明 #

前提条件 #

实现方式 #

#

播放 HLS 标准加密视频

兼容性说明

已知限制

前提条件

实现方式

切换视频

播放私有加密视频（新版）

兼容性说明

前提条件

Vid 模式播放

DirectUrl 模式播放

播放 DASH 视频

播放 H.265 视频

兼容性说明

开启 H.265 兼容模式

多码率自适应播放

效果展示

兼容性说明

前提条件

播放 HLS 自适应码流

播放 DASH 自适应码流

播放 MP4 自适应码流

事件监听

动态 Buffer

预加载

效果展示

兼容性说明

工作原理

初始化预加载模块

手动执行预加载

自动执行预加载

相关 API

播放私有加密视频（旧版）

兼容性说明

前提条件

实现方式