文档中心

视频点播

Web 播放器 SDK

基础功能

VePlayer 通过 HTML5 的 <video/> 标签实现视频播放，能满足视频播放的常用功能需求。本文为您介绍如何实现 VePlayer 提供的基础功能。

接口调用

VePlayer 的基础功能由播放器内核的属性或接口实现。

获取播放器内核的示例代码如下：
```
const playerSdk = new VePlayer({
   id: 'video',
   width: 800,
   height: 500,
   url: 'xx.mp4'
 });

 playerSdk.on('ready', () => {
   // 获取播放器内核
  const player = playerSdk.player;
  console.log('player core', player);
 })
```
说明
- 播放器内核创建是一个异步过程，直接在播放器实例化后获取内核是无法直接拿到的，因为内核的创建尚未完成。您可以在 SDK 触发事件（例如 ready 事件）后通过 SDK 实例的 player 属性获取播放器内核。
- 播放器内核的属性和接口的详细描述，请见播放器内核。

获取播放器内核的属性。以获取当前播放时间为例，示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  url: 'xx.mp4'
});

// ...
// 获取当前播放时间
const currentTime = playerSdk.player.currentTime;

调用播放器内核的方法。以调用播放方法为例，示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  url: 'xx.mp4'
});

// ...
// 手动调用播放
const btn = document.getElementById('play_btn');
btn.addEventListener('click', (e) => {
  playerSdk.player.play();
})

Vid 模式播放

适用于播放已上传至火山引擎视频点播服务的视频。通过视频的 Vid 和其对应的临时播放凭证 PlayAuthToken 来指定播放内容。

获取临时播放 Token

您需要在应用服务端通过 Vid 生成临时播放 Token。临时播放 Token 除了包含视频 ID 等信息，还可以通过参数指定视频分辨率、转码类型、封装格式等信息。具体介绍请见通过临时播放 Token 播放。

说明

获取的视频默认是非加密 MP4 视频。如果 playAuthToken 没有指定格式、分辨率等信息，可以在 reqParams 中通过 Format 和 Definition 来透传参数，可传参数详见获取播放地址。

配置参数

在实例化 VePlayer 时，设置 getVideoByToken 参数传入 Vid 播放配置。详细的参数说明请见 IPlayAuthTokenConfig。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  // Vid 播放配置
  getVideoByToken: {
    playAuthToken: '临时playAuthToken', // 从服务端获取
    definitionMap: {
      'original': {
        definition: 'ori',
        definitionTextKey: 'ORI'
      },
      '360p': {
        definition: 'ld',
        definitionTextKey: 'LD'
      },
      '480p': {
        definition: 'sd',
        definitionTextKey: 'SD'
      },
      '720p': {
        definition: 'hd',
        definitionTextKey: 'HD'
      }
    }
  },
  languages: {
    'zh': {
      ORI: '原画',
      LD: '流畅',
      SD: '标清',
      HD: '高清'
    }
  }
});

VePlayer 会从视频点播服务自行获取视频播放地址，默认以符合条件的第一个地址作为播放地址，并自动设置清晰度列表。
如果您需要自行处理视频信息，可以在播放器实例化之前，调用 VePlayer 提供的 Service 方法，获取视频播放地址。示例代码如下：

const Service = window.VePlayer.Service;

const playAuthToken = '临时playAuthToken'; // 需要从服务端获取
Service.url(playAuthToken, '//vod.volcengineapi.com').then((res) => {
  // 业务侧处理视频信息
  const player = new VePlayer({
    id: 'mse',
    width: 800,
    height: 500,
    url: res.PlayInfoList[0].MainPlayUrl,
  });
}).catch((e) => {
  console.log(e);
});

切换视频

如果需要切换视频源，可以传入新的临时播放 Token 进行切换。示例代码如下：

playerSdk.switchAuthToken({
    playAuthToken: 'new playAuthToken'
});

自动更新临时播放 Token

临时播放 Token 具有一定的有效时间，建议仅在需要播放时获取使用。如果临时播放 Token 过期，视频将无法起播。VePlayer 提供 onTokenExpired 事件，以便您实现 Token 过期时自动更新。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  getVideoByToken: {
    playAuthToken: 'video_playAuthToken'
  },
  onTokenExpired: () => {
    return new Promise(resolve => {
      // 调用接口获取新的临时播放 Token
      getNewToken().then(res => {
        resolve({
          playAuthToken: 'new playAuthToken' // 新的临时播放 Token
        })
      })
    });
  }
});

说明

onTokenExpired 要求返回为 IPlayAuthTokenConfig 类型的 Promise 异步函数。

获取播放状态

通过 playerSdk.player.state 获取播放器当前所处的播放状态。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  url: 'xx.mp4'
});

// 获取播放状态
const playerState = playerSdk.player.state;

播放状态枚举值的详细说明如下表所示。

名称	数值	描述
ERROR	0	播放出现错误。
INITIAL	1	初始化。
READY	2	配置、事件、插件等均已经完成初始化、绑定和实例化。
ATTACHING	3	进入媒体对象挂载阶段。
ATTACHED	4	媒体对象已经挂载到了 DOM 中。
NOTALLOW	5	播放被阻止。
RUNNING	6	已经成功起播进入播放流程。
ENDED	7	播放结束。
DESTROYED	8	播放器内核实例已被销毁。

监听播放器报错信息

注意

强烈建议对视频播放地址所使用的域名配置跨域访问，以方便 SDK 分析播放错误。

从 1.10.0 版本起，播放器遇到无法继续播放的错误时，会展示播放错误 UI，包含错误描述、错误码、基于浏览器的设备 ID、播放时间，如下图所示：

此外，控制台还会展示更详细的错误信息，如下图所示：

说明

有时一次播放会多次触发错误，请以第一次错误信息打印为准。

您也可通过监听 error 事件获取错误信息，示例代码如下：

const playerSdk = new VePlayer({
    // ...
});

interface IVeError {
  playerVersion: string; // 播放器版本
  currentTime: number; // 错误发生时视频的播放时间
  duration: number; // 视频时长
  ended: boolean; // 是否播放完成
  readyState: number; // 视频准备状态
  networkState: number; // 网络状态
  src: string; // 视频地址
  errorType: VE_ERROR_TYPE_MAP; // 错误类型
  errorCode: number; // 错误码
  httpCode?: number; // 播放地址 http code
  message: string;  // 错误信息
  mediaError?: MediaError; // media 元素的错误对象
  originError?: string; // 原始错误堆栈
  host: string; // 视频地址域名
  veErrorCode?: number; // 错误码（自 1.10.0 起新增）
  veErrorType?: string; // 错误类型（自 1.10.0 起新增）
  veErrorMessage?: string; // 错误信息（自 1.10.0 起新增）
  displayMessage?: string;  // 播放器 UI 展示的错误信息
  videoInfo: {
    isMSE?: number; // 是否 MSE
    vtype?: string; // 视频格式
    drmEncryptType?: string; // 加密类型
    vid?: string; // 视频 vid
  };
  ext: unknown; // 扩展信息
  ex?: string; // 其他信息
}

// 监听播放器报错信息
playerSdk.on(VePlayer.Events.ERROR, (err: IVeError) => {
  console.error('player error: ', err);
});

说明

veErrorCode 错误码的具体含义及相应的建议处理方式详见 Web 端错误码。

如果仍无法确定错误原因及处理方式，请按照以下步骤进一步排查问题：

在播放错误 UI 界面上复制设备 ID。设备 ID 即为您在播放器实例化配置中的 vodLogOpts.line_user_id 字段。如果未配置该字段，系统将自动生成一个随机 ID。
前往视频点播控制台单点追查页面，输入设备 ID，检索与该设备相关的播放详情。具体请见单点追查。
若仍无法定位问题，请截取错误 UI 和浏览器控制台的错误信息打印，然后提交工单联系火山引擎技术支持团队。

设置音量

设置音量包括音量大小调节和静音设置。VePlayer 默认 UI 中自带音量设置插件，您可自行调节音量或者设置静音。如果自定义 UI，可以使用以下方法：

设置音量的示例代码如下：

// 配置音量，实例化时传入 volume 参数
const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  volume: 0.2,
  url: 'xx.mp4'
});  

// 设置音量，实例的 player 进行设置
playerSdk.player.volume = 0.2;

设置静音的示例代码如下：
```
playerSdk.player.muted = true;
```

倍速播放

VePlayer 默认显示播放速度设置插件，提供 0.5x、0.75x、1x、1.25x、1.75x、2x 的播放速度选项。用户可根据需要调节播放速度。如果您需要设置为其他速度，可参考以下示例代码。

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  url: 'xx.mp4'
});  

// 播放倍速设置
playerSdk.player.playbackRate = 3;

获取当前播放速度的示例代码如下：

const playbackRate = playerSdk.player.playbackRate;

切换清晰度

VePlayer 提供清晰度切换插件，支持用户自行切换不同清晰度的视频。具体效果如下图所示：

显示多个清晰度

为实现清晰度切换功能，您需要准备同一视频的不同清晰度版本。您可以通过视频点播媒体处理功能获取同一视频的不同清晰度版本，具体操作请见音视频转码。
不同的播放模式下，显示清晰度切换插件的实现方式有所不同。

Vid 模式

DirectUrl 模式

如果您使用 Vid+PlayAuthToken 方式播放，则只需设置 playAuthToken，不限定清晰度、Definition 对应签发参数，并确保控制台中有对应各个清晰度的转码产物，VePlayer 会自动展示清晰度切换插件。如果您需要自定义各清晰度对应的文案，可传入 definitionMap。示例代码如下：

const playerSdk = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    getVideoByToken: {
        playAuthToken: 'yourplayAuthToken',
        definitionMap: {
            'original': '原画',
            '360p': '流畅',
            '480p': '标清',
            '720p': '高清',
            '1080p': '蓝光',
        },
    },
});

如果您使用 URL 方式播放，需设置 playList 列表。列表中每一项均包含播放地址 url 和对应的清晰度文案 definition。示例代码如下：

const playerSdk = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    playList: [
        {
            url: 'xx480.mp4',
            definition: '标清'
        },
        {
            url: 'xx720.mp4',
            definition: '高清'
        },
        {
            url: 'xx1080.mp4',
            definition: '超清'
        }
    ]
});

显示单个清晰度

在以下仅有单个清晰度视频的场景中，VePlayer 默认不会显示清晰度切换插件：

实例化参数中只设置了 url 地址。
playList 中只设置了一路流。
Vid 模式播放时服务端只返回了一路流。

如果您仍然期望显示清晰度切换插件，可将实例化参数 alwaysShowDefinition 设为 true 。此外，如果您还需自定义该清晰度对应的文案，不同的播放模式下，实现方式有所不同。示例代码如下：

Vid 模式

DirectUrl 模式

使用 Vid+PlayAuthToken 方式播放的示例代码如下：

const playerSdk = new VePlayer({
    id: 'video',
    width: 640,
    height: 360,
    // 设置单个清晰度时也显示清晰度切换插件
    alwaysShowDefinition: true,
    getVideoByToken: {
        playAuthToken: 'yourplayAuthToken',
        definitionMap: {
        '480p': {
          definitionTextKey: 'HD'
        },
      },
      languages: {
        'zh': {
          // 自定义 HD 对应的文案
          HD: '超清',
        },
      },
    },
});

使用 DirectUrl 方式播放的示例代码如下：

const playerSdk = new VePlayer({
    id: 'video',
    url: "playback_url",
    width: 640,
    height: 360,
    // 设置单个清晰度时也显示清晰度切换插件
    alwaysShowDefinition: true,
    // 自定义清晰度文案
    definitionText: '超清',
    // 多语言场景下，可通过设置 definitionTextKey 来自定义清晰度文案
    // definitionTextKey: 'HD',
    // languages: {
    //  'zh': {
        // 自定义 HD 对应的文案
    //    HD: '超清',
    //  },
    // },
});

循环播放

播放器参数 loop 设置为 true，即可开启循环播放。示例代码如下：

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  loop: true,
  url: 'xx.mp4'
});

自动播放

自动播放是指在用户没有主动交互（如鼠标点击、手指触摸）的情况下，通过 autoplay 配置、JavaScript 代码调用 play() 方法，或者定时器、Promise 回调、事件监听等方式，在页面加载完成后自动启动视频播放的功能。这种功能允许视频在页面加载后立即开始播放，而无需用户手动点击播放按钮。

由于浏览器策略的限制，自动播放并非总能成功。浏览器从用户角度考虑，认为网页或应用程序没有警告自动发出噪音可能会令人讨厌、不便或令人反感，因此通常仅允许在特定情况下进行自动播放。

自动播放的配置和条件

VePlayer 提供 autoplay、autoplayMuted、enableDegradeMuteAutoplay 和 enableUserActionAutoplay 四个自动播放相关的配置，详见 IPlayerConfig。但是自动播放能否成功，在不同浏览器环境中还需要满足以下条件。

PC 端自动播放

根据最新的 PC 端浏览器策略，允许自动播放至少需要满足以下任意条件：

具体请见 Google Chrome 和的自动播放策略。

音频被静音或其音量设置为 0。
以下条件允许自动播放：
- 用户和网页已有交互行为（包括点击、触摸、按下某个键等等）。
  交互行为的回调中执行 play() 的上下文中必须能跟踪到真实的用户交互行为。伪造的用户交互行为不被接受。
- 网站已被列入白名单，如果浏览器确定用户经常与媒体互动，就会被列入允许自动播放的白名单，有时也支持用户自行设置。
  - Chrome 通过 Media Engagement Index (MEI) 自动对网站是否允许自动播放进行评分。
    说明
    您可以在 chrome://media-engagement/ 查看网站的 MEI 评分。因为各个用户的浏览器评分不一致，所以会出现同一个网站有的用户能自动播放，有的不能，但随着用户与网站交互增多，评分会随之升高，也就允许自动播放了。一些访问量较大的视频网站，例如腾讯视频、bilibili、YouTube，因为网站访问者与其交互较多且大多数允许自动播放，会被 Chrome 的算法自动加入自动播放白名单，详见 Autoplay Pre-Seeding in Chrome。
  - Safari 通过偏好设置 > 网站 > 自动播放或地址栏右键对该网站设置是否允许自动播放。
顶部框架可以将自动播放权限委派给其 iframe，以允许自动播放声音。

H5 和移动端 WebView 上自动播放

H5 和移动端 WebView 上默认禁止有声音的自动播放。您可以选择自动静音播放，示例代码如下：

const playerSdk = new VePlayer({
  // ...
  autoplay: true,
  autoplayMuted: true,
  // enableDegradeMuteAutoplay: true, // 开启自动降级静音播放，即有声音播放不支持时自动降级到静音自动播放
});

说明

需要注意在以下情况中，自动静音播放也不能生效：

iOS 端低电模式下，即使添加上 WebView 自动播放参数、或者是默认静音也都无法自动播放，因为播放视频被系统认定为耗能行为。
由于安卓微信 WebView 的自动播放策略调整，在安卓微信下，禁止任何方式的自动播放。

如果是在业务方可控的 WebView 上运行网站应用，还需开启 WebView 自动播放相关配置以实现自动播放。

Android 设置 setMediaPlaybackRequiresUserGesture。示例代码如下：
```
myWebView.getSettings().setMediaPlaybackRequiresUserGesture(false);
```
iOS WKWebView 设置 mediaTypesRequiringUserActionForPlayback。示例代码如下：
```
[self.webView mediaTypesRequiringUserActionForPlayback:NO];   
```

判断自动播放是否成功

您可以通过以下方式判断自动播放是否成功。

通过 API 返回结果判断

通过 JavaScript 代码调用 play() 方法实现自动播放不一定能成功。通常来说可以根据 play() 返回的 Promise 操作结果来判断是否成功：

成功时会返回状态为 resolve 的 Promise 结果。
失败时则返回携有 NotAllowedError 错误且状态为 rejected 的 Promise 结果。

示例代码如下：

let startPlayPromise = playerSdk.player.play();

if (startPlayPromise !== undefined) {
  startPlayPromise.catch(error => {
    if (error.name === "NotAllowedError") {
      // TODO Do something when not autoplay success
    } else {
      // Handle a load or playback error
    }
  }).then(() => {
    // Start whatever you need to do only after playback
    // has begun.
  });
}

通过监听自动播放失败事件

您可以监听 Web 播放器 SDK 的以下事件来判断自动播放是否被阻止：

autoplay_was_prevented: 自动播放被阻止。
autoplay_failed: 自动播放失败。

示例代码如下：

const playerSdk = new VePlayer({
  // ...
  autoplay: true,
});
playerSdk.on('autoplay_was_prevented', () => {
  // TODO something
  console.log('自动播放被阻止');
});

如果是默认静音自动播放，非用户行为下设置播放器 muted 属性为 true 时（playerSdk.player.muted = true），在不支持有声音自动播放的浏览器环境下，浏览器会强制视频暂停。

播放源过期自刷新

您从视频点播服务获取的视频播放地址默认开启了URL 鉴权功能。在视频播放过程中，可能因为视频地址未及时使用、用户进行 Seek 播放或循环播放等操作，视频地址过期，导致视频无法继续观看。VePlayer 提供相应的事件监听视频播放地址是否过期，并支持配置自动刷新视频播放地址。通过这样的配置，即使视频播放地址过期，VePlayer 也能自动重新获取有效的播放地址，使用户能够继续观看视频。

监听播放源是否过期

方式一：通过时间戳比较过期监听

您需自行指定该播放源的过期时间戳。播放器会轮询地将播放器所在的客户端时间与过期时间戳进行比较。过期前 60 秒时，SDK 会触发 Events.MEDIA_EXPIRED 事件，提示地址即将过期。

Vid 模式

DirectUrl 模式

Vid 模式播放时，播放器会自动获取每个地址的过期时间戳。因此，您仅需在实例化播放器时，将 enableUrlExpireCheck 参数设为true，开启地址过期检测。示例代码如下：

const playerSdk = new VePlayer({
        id: 'video-container',
        getVideoByToken: {
          playAuthToken: 'playAuthTokenxxxx'
        },
        // 开启地址过期检测
        enableUrlExpireCheck: true,
        vodLogOpts: {
            vtype: 'MP4',
            tag: '普通视频',
            line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
            line_user_id: 'veplayer_web_demo'
        }
});

playerSdk.on(VePlayer.Events.MEDIA_EXPIRED, (err) => {
      console.log('地址过期', err);
})

DirectUrl 模式下，您的应用服务端向 Web 端下发地址时，需要下发地址的过期时间戳。

说明

如果您的应用服务端是通过 GetPlayInfo 接口从视频点播服务获取的视频播放地址，您需要将各个地址的 MainUrlExpire 作为过期时间戳下发到 Web 端。

在实例化播放器时，您需要：

将 enableUrlExpireCheck 参数设为 true 开启过期检测。
将 urlExpireTimestamp 设为该地址的过期时间戳。

示例代码如下：

const playerSdk = new VePlayer({
        id: 'video-container',
        // 将 URL 和 <YOUR_AUTH_KEY> 替换为实际有效的签名播放地址；urlExpireTimestamp 与实际地址的过期时间保持一致
        url: 'https://voddemo.demo.com/453b1f794dfa49f4819b5d923658411a?auth_key=<YOUR_AUTH_KEY>',
        // 开启地址过期检测
        enableUrlExpireCheck: true,
        // 设置过期时间戳
        urlExpireTimestamp: 1724135102,
        vodLogOpts: {
            vtype: 'MP4',
            tag: '普通视频',
            line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
            line_user_id: 'veplayer_web_demo'
        }
    });

playerSdk.on(VePlayer.Events.MEDIA_EXPIRED, (err) => {
      console.log('地址过期了 ', err);
})

如果该视频存在多个清晰度，每个清晰度所对应的过期时间戳不同，您可在播放列表配置项 playList 中针对每个地址单独设置过期时间戳 urlExpireTimestamp。示例代码如下：

const playerSdk = new VePlayer({
        id: 'video-container',
        // 开启地址过期检测
        enableUrlExpireCheck: true,
        playList: [
            {
              url: 'https://voddemo.demo.com/e826c993a2444058915fb494c4fcdabb?a=0&auth_key=1817600800-8882fc603afb49edbb2665e62c95c69b-0-32390643c8637e4d3e46e87a684d5a4b&br=660&bt=660&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=3&er=0&l=20220708180015010204028132080F0005&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApZzg6ZzkzZTxoN2QzNGY3NWdfZy9gMHFrYTBgLS1kYy9zc2IwNS4wM2NhYjZhMi4wNTY6Yw%3D%3D&vl=&vr=',
              definition: '1080p',
              // 设置过期时间戳
              urlExpireTimestamp: 1817600800,
            },
            {
              url: 'https://voddemo.demo.com/453b1f794dfa49f4819b5d923658411a?auth_key=1717582800-830c08a311bb49fab40dbaa90ebd4db3-0-1b61cbd491235c69d89a694bd51a1027',
              definition: '720p',
              // 设置过期时间戳
              urlExpireTimestamp: 1717582800,
            },
        ],
        vodLogOpts: {
            vtype: 'MP4',
            tag: '普通视频',
            line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
            line_user_id: 'veplayer_web_demo'
        }
    });

playerSdk.on(VePlayer.Events.MEDIA_EXPIRED, (err) => {
      console.log('地址过期', err);
})

方式二：通过播放错误监听

在视频播放地址过期时间未知的情况下，如果地址过期，播放器会触发网络类错误。为了确认该错误是否由地址过期引起，播放器会主动对地址的有效性进行校验。一旦确认地址过期，播放器会触发地址过期事件，告知视频资源已过期。
为了确保该功能正常运行，视频播放地址所使用的域名需要配置了 HTTP 返回 CORS 跨域头。您可以通过视频点播控制台进行配置 HTTP 响应头。推荐设置以下配置：

响应头名称	响应头值
Access-Control-Allow-Origin	`*` 或者包含业务方 Web 页面的 Origin
Access-Control-Allow-Methods	`*` 或者包含 `GET,HEAD,OPTIONS`
Access-Control-Expose-Headers	`*` 或者包含 Range

刷新播放源

您可以通过以下两种方式实现播放源过期后刷新播放源。

监听到过期事件后主动更新播放源

您可以监听过期事件 Events.MEDIA_EXPIRED。在监听回调中，进行以下操作：

从应用服务端获取新的播放源数据。播放源数据可以是视频播放地址 url、播放列表 playList 或者 vid 和 playAuthToken，还需包含新地址的过期时间戳 urlExpireTimestamp。
调用 SDK 提供的 updateMediaSource 方法将新的播放源数据传入 SDK。

示例代码如下：

const playerSdk = new VePlayer({
  id: 'video-container',
  url: 'https://veplayer.demo.com/453b1f794dfa49f4819b5d923658411a?auth_key=1717547753-UCQrGayCc9-xiong-c1b5966b82630cd45eefaa0f73b9137a',
  enableUrlExpireCheck: true,
  urlExpireTimestamp: 1717547753,
  vodLogOpts: {
    vtype: 'MP4',
    tag: '普通视频',
    line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
    line_user_id: 'veplayer_web_demo',
  },
});

// 监听过期事件
playerSdk.on(VePlayer.Events.MEDIA_EXPIRED, err => {
  console.log('地址过期了 ', err);
  // 从业务服务端重新获取新的视频播放地址及地址过期时间戳
  appServer.getPlayUrl().then((res) => {
    playerSdk.updateMediaSource({
      url: res.url,
      urlExpireTimestamp: res.urlExpireTimestamp,
    });
  })
});

设置过期回调自动刷新播放源

您可以在实例化播放器时设置 onMediaExpired 回调函数。该回调函数应返回一个包含播放源信息的数据对象，可以是视频播放地址 url、播放列表 playList 或者 vid 和 playAuthToken。此外，数据对象还需要包含新地址的过期时间戳 urlExpireTimestamp。当 Events.MEDIA_EXPIRED 事件触发后，播放器会自动调用 onMediaExpired 回调函数，并将其返回的结果作为 updateMediaSource 方法的输入，从而自动更新播放源。示例代码如下：

const playerSdk = new VePlayer({
        id: 'video-container',
        url: 'https://veplayer.demo.com/d174bc4b9b32482582d3a07816a2104a/main.m3u8?auth_key=1718253922-987655e64a9f4c0dbf568f6397bd6232-0-5c0fa62ad9bcbee2c024b55824350d43',
        enableUrlExpireCheck: true,
        urlExpireTimestamp: 1618246275,
        onMediaExpired: async () => {
          // 从业务服务端重新获取新的视频地址及地址过期时间戳
          const res = await appServer.getPlayUrl();
          return {
            url: res.url,
            urlExpireTimestamp: res.urlExpireTimestamp,
          };
        },
        vodLogOpts: {
            vtype: 'MP4',
            tag: '普通视频',
            line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
            line_user_id: 'veplayer_web_demo'
        }
});

playerSdk.on(VePlayer.Events.MEDIA_EXPIRED, (err) => {
      console.log('地址过期了 ', err);
})

以 `<source />` 元素设置播放源

VePlayer 支持在 HTML <video /> 元素中使用 <source /> 元素设置多种格式的视频源，以兼容不同的浏览器环境。

注意

以 <source/> 元素设置的地址不支持 MSE（媒体源扩展）播放场景，例如 PC 上播放 HLS 视频或安卓上播放 HLS 加密视频。

为了设置多种格式的视频源，您只需以数组的形式描述 URL。每个数组项应包含视频播放地址 src 和视频容器格式类型 type。其中，type 描述的通常是视频格式的 MIME 类型，只支持浏览器直接支持播放的视频格式。以下是常见容器格式及对应的 MIME 类型和文件扩展名：

容器格式名称	音频		视频
容器格式名称	MIME 类型	扩展名	MIME 类型	扩展名
3GP	audio/3gpp	.3gp	video/3gpp	.3gp
ADTS（音频数据传输流）	audio/aac	.aac	—	—
FLAC	audio/flac	.flac	—	—
MPEG-1 / MPEG-2（MPG 或 MPEG）	audio/mpeg	.mpg .mpeg	video/mpeg	.mpg .mpeg
MPEG-1 / MPEG-2（MPG 或 MPEG）	audio/mp3	.mp3	video/mpeg	.mpg .mpeg
MPEG-4 (MP4)	audio/mp4	.mp4 .m4a	video/mp4	.mp4 .m4v .m4p
Ogg	audio/ogg	.oga .ogg	video/ogg	.ogv .ogg
QuickTime Movie (MOV)	—	—	video/quicktime	.mov
WAV（波形音频文件）	audio/wav	.wav	—	—
WebM	audio/webm	.webm	video/webm	.webm

示例代码如下：

const playerSdk = new VePlayer({
  id: 'video-container',
  url: [
    {
      // MOV 格式，苹果设备支持
      src: 'https://voddemo-play.volcvod.com/source_video.MOV',
      type: 'video/quicktime'
    },
    {
      src: 'https://voddemo-play.volcvod.com/source_video.mp4',
      type: 'video/mp4',
    },
  ],
  vodLogOpts: {
    vtype: 'MP4',
    tag: '普通视频',
    line_app_id: 123456, // 示例值，请替换为视频点播控制台“应用管理”中的实际 App ID
    line_user_id: 'veplayer_web_demo'
  }
});

说明

您可通过 SDK 实例的 src 属性获取到当前播放所实际使用的 source 对应的视频地址。

视频旋转

设置 rotate 配置使用的旋转插件。用户点击旋转按钮后，视频会旋转 90 度。

const playerSdk = new VePlayer({
  id: 'video',
  width: 800,
  height: 500,
  url: 'xx.mp4',
  // 视频旋转按钮配置项，默认值：{ innerRotate: false, clockwise: false }
  rotate: {
    innerRotate: true, //只旋转内部 video
    clockwise: false // 旋转方向是否为顺时针
  }
});

注意

当 innerRotate 为 false 时，播放器的宽高需要与视频的分辨率一致。

进度条预览缩略图

VePlayer 支持用户在拖拽进度条时通过查看缩略图快速预览指定时间点的视频内容。在 PC 端，用户可通过鼠标悬停在目标时间点上实现预览，在 H5 端则可通过手势左右滑动到目标时间点。VePlayer 利用服务端提供的雪碧图作为缩略图资源，根据用户交互获取的时间点，动态展示最接近该时间点的缩略图。雪碧图是由多帧截图拼接而成的大图，具有以下优点：

图片体积小：将多个小图合并成一张大图，可以减小图片文件大小。
请求次数少：通过图片整合，减少用户对服务器的请求次数，提升页面加载速度。

以下为一张雪碧图示例。该雪碧图中共包含 13 张缩略图。

基于上述雪碧图的进度条缩略图预览效果如下：

PC 端	H5 端

说明

点击在线体验试用进度条预览缩略图功能，并查看示例代码。
缩略图预览的时间精度取决于截图时间间隔，间隔越小，精度越高，但雪碧图大小也会增大，图片加载速度变慢，因此开发者需要权衡取舍。

前提条件

通过视频点播媒体处理服务生成雪碧图，详细操作请见雪碧图。

实现方式

Vid 播放模式和 DirectUrl 播放模式均支持展示雪碧图，实现方式有所不同，具体说明如下。

Vid 模式

DirectUrl 模式

实例化播放器时，将 getVideoByToken.needThumbs 设为 true 即可开启进度条预览缩略图功能。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  // Vid 播放配置
  getVideoByToken: {
    playAuthToken: '临时playAuthToken', // 需要从服务端获取
    ....
    needThumbs: true
  }
});

您需要获取每张雪碧图中缩略小图的宽度、高度、行数和列数以及缩略小图总数及每个雪碧图的 URL 地址，参考如下代码示例设置给播放器：

var playerSdk = new VePlayer({
        id: 'mse',
        url: "https://www.demo.bytedance.com/adhasgd7****syh9.mp4", // 视频地址
        width: 640,
        height: 360,
        // 本示例中，一共从视频中截取 38 张缩略图。
        // 截取的缩略图越多，进度条预览越精确，图片越大加载越慢，需要您根据业务需求自行判断。
        // 每张雪碧大图最多可包含 10*10 = 100 张缩略小图，所以仅需 1 张雪碧大图。
        thumbnail: {
            // 缩略小图总张数
            pic_num: 38,
            // 缩略图宽
            width: 240,
            // 缩略图高
            height: 136,
            // 雪碧大图中每列包含的缩略小图数量
            col: 10,
            // 雪碧大图中每行包含的缩略小图数量
            row: 10,
            // 雪碧图 URL 地址
            urls: ["http://www.demo.bytedance.com/tos-cn-v-d67d0e/7ea3f6dbc4a049***e9f96d106c7b_1659088327~tplv-noop.image?x-expires=1690624695&x-signature=q7VjLGZMLehRr***IgfvIfwMY%3D"]
        }
    });

进度条标记

进度条标记指在进度条上明显地标记时间段，通常用于突出重要的故事节点。在长视频场景，有助于给用户提供视频时间结构的信息提醒。效果如下：

初始化时您可通过 progressDot 参数将标记点的数据以数组的方式设置给播放器，示例代码如下：

var playerSdk = new VePlayer({
    id: 'video',
    url: "https://www.demo.com/adhasgd7****syh9.mp4",
    progressDot: [
        {
            id: '1', // 标记点唯一 ID，用于操作更新标记点
            time: 30, // 标记点开始时间点，单位为秒
            text: '高能预警', // 标记点自定义文案，H5 端不支持显示该文案
            duration: 2, // 标记点持续时长，单位为秒
            style: { // 标记点自定义样式
                background: 'rgb(60, 126, 255)'
            }
        },
        {
            id: '2',
            time: 60,
            text: '精彩片段',
            duration: 20,
            style: {
                background: '#FFF'
            }
        },
        {
            id: '3',
            time: 142,
            text: 'example text',
            duration: 2,
            style: {
                background: 'red'
            }
        },
    ],
});

初始化后，您可以参考以下示例代码创建、更新、删除、查找标记点：

创建标记点：

playerSdk.getPlugin('progresspreview').createDot({
  time: 100,
  duration: 20,
  id: '4',
  text: 'new dot text',
  style: {
    background: '#fbbc08'
  }
})

根据 ID 查找标记点：

const dot = playerSdk.getPlugin('progresspreview').findDot('1');

根据 ID 更新标记点：

playerSdk.getPlugin('progresspreview').updateDot({
  id: '1',
  time: 20,
  duration: 20,
  text: 'update text',
  style: {
    background: '#35a853'
  }
})

按 ID 删除标记点：

playerSdk.getPlugin('progresspreview').deleteDot('1');

删除所有标记点：

playerSdk.getPlugin('progresspreview').deleteAllDots();

更新所有标记点：

playerSdk.getPlugin('progresspreview').updateAllDots([
    {
      time: 100,
      duration: 20,
      id: '7',
      text: 'update text',
      style: {
        background: '#35a853'
      }
    },
    {
      time: 60,
      id: '8',
      text: '高能预警！！！',
      duration: 10,
      style: {
        background: '#FFFFFF'
      }
    },
  ])

查看视频信息

播放器入参中传入 enableMenu 并设为 true，可在播放器上右键查看视频信息。示例代码如下：

const playerSdk = new VePlayer({
    id: 'mse',
    width: 600,
    height: 400,
    enableMenu: true,
    getVideoByToken: {
        playAuthToken: 'playAuthToken',
    },
});

效果如下图：

MP4 MSE 播放模式

MP4 视频播放时，在不优化视频 MOOV box 结构且不进行视频转码的情况下，通常起播较慢。VePlayer 支持以 MSE 形式播放 MP4 视频，该模式起播更快，支持缓存播放，从而节省流量，示例代码如下所示。

const playerSdk = new VePlayer({
    id: 'video',
    width: 800,
    height: 500,
    url: 'xx265.mp4',
    enableMp4MSE: true
});

说明

MSE 播放模式需要确认 mp4 地址，支持当前页面域名跨域请求，并且支持 range 请求，可以通过提交工单的方式配置跨域。

音乐播放器模式

VePlayer 支持音乐播放器模式，具有音乐封面、音乐列表、循环播放、码率切换等功能。效果如下图所示。

如需开启音乐播放器模式，您需在实例化 VePlayer 时，将 isMusic 参数设为 true。此外，您还可以配置音乐播放器。不同的播放模式下，配置方式有所不同。

Vid 模式

DirectUrl 模式

Vid 播放模式下，可通过 music 参数配置音乐播放器。具体参数说明请见 IMusicConfig。示例代码如下：

const playerSdk = new VePlayer({
    id: "music",
    width: 640,
    height: 90,
    isMusic: true,
    title: "Final Touch/Hidden Agenda",
    poster: "https://s1.ax1x.com/2023/01/05/pSAQx78.jpg",
    getVideoByToken: {
      playAuthToken: 'eyJHZXRQbGF5SW******aWVzIiwiVG9rZW5WZXJzaW9uIjoiVjIifQ==',
      definitionMap: {
        'highest': {
          definition: 'Highest quality',
          definitionTextKey: 'highest'
        },
        higher: {
          definition: 'Higher quality',
          definitionTextKey: 'higher'
        },
        medium: {
          definition: 'Medium quality',
          definitionTextKey: 'medium'
        },
      },
    },
    languages: {
      zh: {
        medium: '普通音质',
        higher: '高音质',
        highest: '无损音质',
      },
      en: {
        medium: 'Normal',
        higher: 'Higher',
        highest: 'Lossless',
      }
    }
  });

DirectUrl 播放模式下，配置音乐播放器模式的示例代码如下：

const playerSdk = new VePlayer({
    id: "music",
    width: 640,
    height: 90,
    isMusic: true,
    music: {
      timeScale: 10,
      mode: 'random',
      list: [
        {
          src: "http://voddemo-play.volcvod.com/oAY***t3KVQbUFYt?auth_key=1767535549-1da3a9f79dc145418c***b6f02d1c925aa",
          title: "Final Touch/Hidden Agenda",
          vid: "v0ddfag10001cerdcarelau57rco03c0",
          poster: "https://s1.ax1x.com/2023/01/05/pSAQx78.jpg",
        },
        {
          src: "http://voddemo-play.volcvod.com/Solitude.mp3?auth_key=1767535452-d24740adae50477eba***16adc8b8df4d97d4",
          title: "Solitude",
          vid: "v02dfag10001cerdcarelauag2njv000",
          poster: "https://s1.ax1x.com/2023/01/05/pSAlSAS.jpg",
        },
        {
          src: "http://voddemo-play.volcvod.com/oASg***WdZjLtvD0Og2TFaXmQQ?auth_key=1767353155-b920aaf***3a896d164a3b6f7ba03d",
          title: "Merry Christmas Mr. Lawrence",
          vid: "Merry Christmas Mr. Lawrence",
          poster: "https://y.qq.com/music/photo_new/T002R300x300M000002NSlUO1Isxd3_2.jpg?max_age=2592000",
        }
      ]
    },
  });

音乐播放器模式的相关属性如下表所示。

属性	是否可读	是否可写	描述	示例
musicMode	是	是	当前播放模式 order：顺序播放 sloop：单曲循环 loop：列表循环 random：随机播放	`playerSdk.musicMode = 'order'; //顺序播放`
musicTimeScale	是	是	快进快退时间跨度	`playerSdk.musicTimeScale = 10; // 设置时间跨度为10s`
musicList	是	是	音乐播放列表	`playerSdk.musicList = [ { title: '歌曲1', vid: 'music1', src: 'https://demo.com/music1.mp3'}, { title: '歌曲2', vid: 'music2', src: 'https://demo.com/music2.mp3'} ]; // 设置播放列表`

属性

是否可读

是否可写

描述

示例

musicMode

是

当前播放模式

order：顺序播放
sloop：单曲循环
loop：列表循环
random：随机播放

playerSdk.musicMode = 'order'; //顺序播放

musicTimeScale

是

快进快退时间跨度

playerSdk.musicTimeScale = 10; // 设置时间跨度为10s

musicList

是

音乐播放列表

playerSdk.musicList = [
  { title: '歌曲1', vid: 'music1', src: 'https://demo.com/music1.mp3'},
  { title: '歌曲2', vid: 'music2', src: 'https://demo.com/music2.mp3'}
]; // 设置播放列表

音乐播放器模式的相关方法如下表所示。

方法	描述	参数	返回	示例
musicAdd	向播放列表中加入歌曲	对象，具体可参考 IMusicListItem `src`：音乐地址 `vid`：音乐唯一 ID `poster`：音乐封面 `title`：音乐标题	无	`playerSdk.musicAdd({ src:'https://demo.com/music.mp3', title:'demo_music', vid: 'demo_music', poster: 'https://demo.com/poster.jpg' });`
musicRemove	从播放列表中移除歌曲	歌曲列表中要删除歌曲对应的 Vid	无	`playerSdk.musicRemove('music_list_2');`
musicRandom	随机获取播放列表中某一首歌曲	无	歌曲信息，具体可参考 IMusicListItem	`playerSdk.musicRandom();`
musicNext	播放下一首歌曲	无	无	`playerSdk.musicNext();`
musicPrev	播放上一首歌曲	无	无	`playerSdk.musicPrev();`
musicSetIndex	选择第 n 首歌曲	Number 类型	无	`playerSdk.musicSetIndex(2);`
musicForward	歌曲快进timeScale秒	无	无	`playerSdk.musicForward();`
musicBackward	歌曲后退 timeScale 秒	无	无	`playerSdk.musicBackward();`
musicSetAbCycle	设置 AB 循环	对象，具体可参考 IABCycle `start`：AB 循环段开始时间 `end`：AB 循环段结束时间 `loop`：AB 段是否循环	无	`playerSdk.musicSetAbCycle({ start: 3, end: 30, loop: true, });`
musicRemoveAbCycle	移除 AB 循环	无	无	`playerSdk.musicRemoveAbCycle();`

弹幕及蒙版弹幕

VePlayer 支持弹幕功能，提供弹幕样式设置面板及相关 API，可实现弹幕展示不重叠、不追击的效果。效果如下图所示：

此外，VePlayer 还支持蒙版弹幕，视频中出现人物时，弹幕文字会从人体后方穿过，呈现裸眼 3D 的视觉效果。效果如下图所示：

注意

Web 播放器 SDK 仅支持由火山引擎视频点播媒体处理服务生成的蒙版弹幕文件。

前提条件

在使用蒙版弹幕功能前，请确保您已完成以下工作：

生成蒙版弹幕文件：通过视频点播媒体处理服务为视频生成蒙版弹幕文件。

配置域名跨域访问 (CORS)：为确保播放器能成功获取蒙版文件，您必须为您使用的点播域名配置 HTTP 响应头，以允许跨域访问。下表列出您需要配置的 HTTP 响应头：

响应头名称	响应头值
Access-Control-Allow-Origin	指定允许的跨域请求的来源。取值可为 `*` 或您的网站域名，例如您的网站为 `https://www.example.volcengine.com`，则参数取值为 `https://www.example.volcengine.com`。
Access-Control-Allow-Methods	指定允许的跨域请求方法。取值为 `*` 或包含 `GET,HEAD,OPTIONS`。
Access-Control-Expose-Headers	指定跨域请求可以包含的 HTTP 请求头。取值为 `*` 或者包含 `Range`。

获取蒙版文件地址：根据您的播放方式，选择对应的获取方法。
- Vid 模式：在您的应用服务端为客户端签发 PlayAuthToken 时，必须额外签入 "NeedBarrageMask": true 字段。播放器将基于此 Token 自动获取蒙版文件地址。
- DirectUrl 模式：您需要 GetPlayInfo 接口，并将请求参数 NeedBarrageMask 设置为 1，从响应参数 BarrageMaskInfo 中获取蒙版文件的地址。

实现方式

说明

弹幕的配置参数介绍详见 IDanmuConfig。

DirectUrl 模式

Vid 模式

DirectUrl 模式下配置弹幕插件显示弹幕设置界面及实现蒙版弹幕的示例代码如下：

const playerSdk = new VePlayer({
    id: 'mse',
    streamType: 'mp4',
    url: "https://voddemo-play.****.com/453b1f794***eff.mp4",
    // 配置弹幕插件，显示弹幕设置界面
    DanmuPlugin:{
        active: true, // 默认开启
        area: 66, // 显示区域
        fontSize: 100, // 字体大小， 枚举值[0, 50, 100]，实际对应14px 16px 20px
        opacity: 66, // 弹幕透明度
        speed: 80, // 弹幕速度
        maskActive: true, // 蒙版弹幕是否默认开启
        maskConfig: {
            // 蒙版弹幕的蒙版文件地址
            maskUrl: 'https://voddemo-play.****.com/*****',
        },
        danmuItems:[
            {
                id: '1', // 弹幕唯一id
                txt: '弹幕1111111', // 弹幕文案
                start: 1000, // 弹幕开始出现时间，判断规则为该时间为当前播放时间的前后两秒内则展示
                prior: true, // 弹幕是否优先展示。即由于同一时间能够展示的弹幕比较有限（受area、弹幕字号限制、播放器大小限制），如果某条弹幕设置了prior为true，则优先展示
                style: {
                    //弹幕自定义样式
                    color: '#ff9500',
                    fontSize: '20px',
                    padding: '2px 11px',
                },
            },
            {
                id: '2',
                txt: '弹幕2222222',
                start: 2000,
            },
            {
                id: '3',
                txt: '弹幕3333333',
                start: 3000,
            },
            {
                id: '4',
                txt: '弹幕4444444',
                start: 4000,
            },
            {
                id: '5',
                txt: '弹幕555555555',
                start: 5000,
            },
            {
                id: '6',
                txt: '弹幕666666',
                start: 6000,
            },
        ]
    },
    // ...
});

Vid 模式下，如需启用蒙版弹幕，可将 getVideoByToken.needBarrageMask 设为 true，SDK 会自动配置 maskConfig 相关参数，示例代码如下：

var playerSdk = new VePlayer({
    id: 'mse',
    lang: 'zh',
    width: 640,
    height: 360,
    getVideoByToken: {
        playAuthToken: "eyJHZX***biI6IlYyIn0=",
        needBarrageMask: true,
    },
    DanmuPlugin: {
        active: true,
        danmuItems: [
            {
                id: '1',
                txt: '弹幕1111111',
                start: 1000,
                style: {
                    //弹幕自定义样式
                    color: '#ff9500',
                    fontSize: '20px',
                    padding: '2px 11px',
                },
            },
            {
                id: '2',
                txt: '弹幕2222222',
                start: 2000,
            },
            {
                id: '3',
                txt: '弹幕3333333',
                start: 3000,
            },
            {
                id: '4',
                txt: '弹幕4444444',
                start: 4000,
            },
            {
                id: '5',
                txt: '弹幕555555555',
                start: 5000,
            },
            {
                id: '6',
                txt: '弹幕666666',
                start: 6000,
            },
        ]
    },
    // ...
});

视频点播

接口调用 #

Vid 模式播放 #

获取临时播放 Token #

配置参数 #

切换视频 #

自动更新临时播放 Token #

获取播放状态 #

监听播放器报错信息 #

设置音量 #

倍速播放 #

切换清晰度 #

显示多个清晰度 #

显示单个清晰度 #

循环播放 #

自动播放 #

自动播放的配置和条件 #

PC 端自动播放

H5 和移动端 WebView 上自动播放

判断自动播放是否成功 #

通过 API 返回结果判断

通过监听自动播放失败事件

播放源过期自刷新 #

监听播放源是否过期 #

方式一：通过时间戳比较过期监听

方式二：通过播放错误监听

刷新播放源 #

监听到过期事件后主动更新播放源

设置过期回调自动刷新播放源

以 <source /> 元素设置播放源 #

视频旋转 #

进度条预览缩略图 #

前提条件 #

实现方式 #

进度条标记 #

查看视频信息 #

MP4 MSE 播放模式 #

音乐播放器模式 #

弹幕及蒙版弹幕 #

前提条件 #

实现方式 #

相关 API #

更多文档 #

接口调用

Vid 模式播放

获取临时播放 Token

配置参数

切换视频

自动更新临时播放 Token

获取播放状态

监听播放器报错信息

设置音量

倍速播放

切换清晰度

显示多个清晰度

显示单个清晰度

循环播放

自动播放

自动播放的配置和条件

判断自动播放是否成功

播放源过期自刷新

监听播放源是否过期

刷新播放源

以 `<source />` 元素设置播放源

视频旋转

进度条预览缩略图

前提条件

实现方式

进度条标记

查看视频信息

MP4 MSE 播放模式

音乐播放器模式

弹幕及蒙版弹幕

前提条件

实现方式

相关 API

更多文档