基础功能

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

接口调用

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

获取播放器内核的示例代码如下所示。

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

 playerSdk.on('complete', () => {
   // 获取播放器内核
   const player = playerSdk.player;
   console.log('player core', 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 模式播放

VePlayer 结合视频点播服务，可以实现视频 Vid+PlayAuthToken 播放。

如下为您介绍实现视频 Vid+PlayAuthToken 播放的操作步骤。

获取 playAuthToken

首先，在服务端通过 Vid 生成播放使用的 playAuthToken。playAuthToken 除了包含视频 Vid 等信息，还可以通过参数指定视频分辨率、转码类型、封装格式等信息。

配置参数

在 VePlayer 实例化参数中传入getVideoByToken。

详细的参数说明如下所示。

{aid: 1234}

{'480p': '标清', '720p': '高清'}

{ '480p': { definition: 'sd', definitionTextKey: 'SD' }, '720p': { definition: 'hd', definitionTextKey: 'HD' }}

配置参数的代码示例如下所示。

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  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);
});

切换视频

如果需要切换视频源，可以传入新的 playAuthToken 进行切换，示例代码如下所示。

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

自动更新 PlayAuthToken

PlayAuthToken 具有一定的有效时间，建议在需要播放时获取使用。如果 PlayAuthToken 过期，视频将无法起播。VePlayer 提供 onTokenExpired 事件，可以在 token 过期时自动更新 token ，代码示例如下所示。

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

播放质量上报

VePlayer 提供播放质量上报功能，可以监控和上报播放量、播放失败率和首帧时间等指标。接入播放质量上报功能后，您可以在视频点播控制台的质量平台查看各个播放质量指标的详细情况。

如需接入播放质量上报功能，您需在播放器实例化的 options 参数中传入 vodLogOpts。示例代码如下：

const player = new VePlayer({
  id: 'video',
  width: 600,
  height: 400,
  url: "https://demo.vod.com/xxx.mp4",
  vodLogOpts: {
    line_app_id: XXXX, // 【必选】该值为 int 类型，接入视频点播的SDK应用 ID ，可以从点播控制台-点播SDK-应用管理获取。
    line_user_id: 'XXX', // 用户 ID， String 或者 int 类型，不传入将是一个根据用户浏览器随机生成的值。
    tag: '普通视频', // 业务标签，对应业务类型，用于区分业务中不同的场景，方便后续进行多维度分析。
  }
});

vodLogOpts 各项配置参数如下所示。

获取播放状态

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

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

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

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

设置音量

设置音量包括音量大小调节和静音设置。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 = false;
  

倍速播放

在点播场景下，VePlayer 默认 UI 中自带倍速播放设置控件。您可以根据需要调节播放速度，默认提供 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.playbackRate

切换清晰度

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

显示多个清晰度

为实现清晰度切换功能，您需要准备同一视频的不同清晰度版本。您可以通过视频点播控制台的媒体处理功能获取同一视频的不同清晰度版本，具体操作请见视频转码模板。

不同的播放模式下，显示清晰度切换控件的实现方式有所不同。

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

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 。此外，如果您还需自定义该清晰度对应的文案，不同的播放模式下，实现方式有所不同。示例代码如下：

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

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 四个自动播放相关的配置，详见接口说明。但是自动播放能否成功，在不同浏览器环境中还需要满足以下条件。

PC 端自动播放

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

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

• 音频被静音或其音量设置为 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, // 开启自动降级静音播放，即有声音播放不支持时自动降级到静音自动播放
});

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

• Android 设置 setMediaPlaybackRequiresUserGesture，示例代码如下：

  myWebView.getSettings().setMediaPlaybackRequiresUserGesture(false);
  

• iOS WKWebView 设置 mediaTypesRequiringUserActionForPlayback，示例代码如下：

  [self.webvie 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 = false），在不支持有声音自动播放的浏览器环境下，浏览器会强制视频暂停。

视频旋转

设置 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 // 旋转方向是否为顺时针
  }
});

外挂字幕

VePlayer 支持 VTT 格式的外挂字幕。你可通过 Subtitle 参数设置字幕列表，可实现字幕切换，示例代码如下所示。

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  width: 600,
  height: 400,
  plugins: [VePlayer.Subtitle],
  Subtitle: {
    isDefaultOpen: true,
    list: [
      {
        "url": "https://字幕1.vtt",
        "text": "中英",
        "isDefault": true
      },
      {
        "url": "https://字幕2.vtt",
        "text": "中日",
        "isDefault": false
      }
    ]
  },
});

记忆播放

VePlayer 可实现记忆播放的功能，可以在您上次观看视频离开后的时间点继续播放。传入 MemoryPlay 配置项，为视频配置唯一的 id: memoryId，即可实现记忆播放。代码示例如下所示。

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    plugins: [VePlayer.MemoryPlay],
    MemoryPlay: {
        memoryId: 'example_memory_id'
    },
});

播放器默认使用浏览器的 localStorage API 存储播放时间，即默认情况下不能实现跨端跨平台共享存储记忆的播放时间点。

如果需要通过服务共享播放时间点，实现的方式如下所示。

1. 传入 getTime 和 saveTime 两个函数；
2. getTime 要求入参为 memoryId，返回为时间的同步或异步函数；
3. saveTime 要求入参数可接受 memoryId 和时间的函数。

实现的示例代码如下所示。

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    plugins: [VePlayer.MemoryPlay],
    MemoryPlay: {
        memoryId: 'example_memory_id',
        getTime: async (id) => {
            // ...异步处理
            // const time = await getTimeApi(id);
            return time;
        },
        saveTime: async (id, time) => {
            // 调用接口存储时间
        }
    },
});

在页面被隐藏、播放器被销毁、或者页面卸载时，VePlayer 会存储播放时间点。

视频镜像

VePlayer 支持水平方向的视频镜像功能。如下示例代码，可以快速实现镜像功能。

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  height: 400,
  plugins: [VePlayer.MirrorPlugin],
});

播放列表

VePlayer 支持播放列表功能，即在给定一个视频列表后，按顺序自动播放列表中的视频。VePlayer 提供播放列表相关的 UI 以及“打开/隐藏播放列表”和“播放下一个视频”两个按钮。具体效果如下：

如需使用播放列表功能，您可在初始化播放器实例时设置 plugins 参数传入播放列表插件实例，再通过 playListPlugin 参数对播放列表功能进行初始化配置。示例代码如下：

const playerSdkIns = new VePlayer({
  id: 'video',
  width: 800,
  height: 600,
  // 注册播放列表插件
  plugins: [VePlayer.playListPlugin],
  // 配置播放列表插件
  playListPlugin: {
    list: [
      {
        url: 'xx.demo.com/1.mp4',
        poster: 'xx.demo.com/1.jpg',
        vid: '67ghsadd8a78s9df8',
        title: 'Remember to bring a little simple everyday',
      },
      {
        playAuthToken: 'demovideoplayAuthToken',
        poster: 'xx.demo.com/2.jpg',
        vid: '67ghsadd8a78s213df8',
        title: 'The night came quietly, with the heat and light',
      },
      {
        url: 'xx.demo.com/3.mp4',
        poster: 'xx.demo.com/3.jpg',
        vid: '67ghsaddhh78s9df8',
        title: 'Watching a beautiful fireworks at night will make you feel good',
      },
      {
        url: 'xx.demo.com/4.mp4',
        poster: 'xx.demo.com/4.jpg',
        vid: '67ghiodd8a78s9df8',
        title: 'Gentle and lazy sea breeze',
      },
    ],
  },
});

此外，播放列表插件提供 API 和事件，具体说明如下：

API

以下示例展示了如何播放下一个视频：

// 播放下一个视频
playerSdkIns.getPlugin('playListPlugin').next();

下表列出播放列表插件支持的 API。

事件

以下示例展示了如何监听播放项变更：

playerSdkIns.on('play_list_item_change', data =>
  console.log('play_list_item_change, current item: ', data),
);

下表列出播放列表插件支持的事件。

查看视频信息

播放器入参中传入 enableContextmenu 和 closeVideoStopPropagation，取值同时设置为 true，可在播放器上右键查看视频信息。实现的示例代码如下所示。

const playerSdk = new VePlayer({
    id: 'mse',
    width: 600,
    height: 400,
    enableContextmenu: true,
    closeVideoStopPropagation: 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
});

音乐播放器模式

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

传入 isMusic 参数设置为 true 即开启音乐播放器模式，以 URL 播放为例：

const playerSdk = new VePlayer({
    id: "music",
    width: 640,
    height: 90,
    isMusic: true,
    url: "http://voddemo-play.volcvod.com/Solitude******4485191-0-d8d39b9e5d825bc516adc8b8df4d97d4",
    title: "Solitude",
    vid: "v02dfag10001cerdcarelauag2njv000",
    poster: "https://s1.ax1x.com/2023/01/05/pSAlSAS.jpg",
  });

效果如下图所示。

不同的播放模式下，音乐播放器模式的实现方式有所不同。

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',
      }
    }
  });
        

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",
        }
      ]
    },
  });
        

配置音乐播放的详细信息如下表所示。具体可参考接口说明中 IMusicConfig。

对应的相关属性的详细信息如下表所示。

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

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

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

相关方法的详细信息如下表所示。

playerSdk.musicAdd({
  src:'https://demo.com/music.mp3',
  title:'demo_music',
  vid: 'demo_music',
  poster: 'https://demo.com/poster.jpg'
});

playerSdk.musicRemove('music_list_2');

playerSdk.musicRandom();

playerSdk.musicNext();

playerSdk.musicPrev();

playerSdk.musicSetIndex(2);

playerSdk.musicPrev();

playerSdk.musicBackward();

playerSdk.musicSetAbCycle({
  start: 3,
  end: 30,
  loop: true,
});

playerSdk.musicRemoveAbCycle();