Kivicube文档

简体中文

English

主题

视频/透明视频/色度视频 ​

相关参考：Scene API / 视频

Web 高级 API 提供了三类视频对象创建能力：

  • 普通视频：createVideo()
  • 透明视频：createAlphaVideo()
  • 色度抠像视频：createKeyingVideo()

创建视频 ​

自动播放的处理 ​

因为浏览器的媒体自动播放约束策略。会让场景中的视频，在需要播放时，可能播放失败。

因此，kivicube会在用户点击首页上的「立即体验」按钮时，让场景中的音视频媒体静默播放一下。

就可以在之后的体验中，进行任意播放。

这解决了场景中自带音视频对象的自动播放问题。但是对于使用api动态添加的视频，还是会遇到自动播放失败。

因此，插件提供apisetVideoNum来告知插件，应用层会动态添加多少个视频。

而插件就会在点击「立即体验」按钮时，去静默播放更多的视频。在后续调用createVideo或类似api时，就会自动匹配上可以自动播放的video标签，达到可自动播放的效果。

注意

必须在用户点击「立即体验」按钮之前调用，否则无效。

js
// 告知插件，应用层会动态添加多少个视频
await api.setVideoNum(10);

创建视频对象 ​

普通视频 ​

js
const video = await api.createVideo('https://your.domain.com/ar.mp4');
await api.add(video);

透明视频 ​

js
const alphaVideo = await api.createAlphaVideo('/assets/glow.mp4');
await api.add(alphaVideo);

色度视频 ​

js
const keyingVideo = await api.createKeyingVideo(
  '/assets/green-screen.mp4',
  {
    // 被抠出的颜色值，默认#00F400
    color: '#00F400',
    // 颜色相似度(0~1)，默认0.42
    similarity: 0.42,
    // 柔和度（0~1），默认0.08
    smoothness: 0.08,
    // 饱和度下降速度（0~1），默认0
    spill: 0,
  }
);
await api.add(keyingVideo);

虽然支持传递ArrayBuffer，但视频文件一般较大，会占用不少内存。更建议传递URL地址来创建视频类对象。

播放控制 ​

播放 ​

js
await api.playVideo(video, {
  loop: true, // 是否循环播放
  full_screen: false // 使其全屏播放
});

后续也可以使用setVideoLoop()来修改是否循环

暂停、停止、重播 ​

js
await api.pauseVideo(video);
await api.stopVideo(video);
await api.playbackVideo(video, { loop: false });

读取状态 ​

js
// 获取视频时长
const duration = await api.getVideoDuration(video);
// 获取视频是否暂停播放
const paused = await api.getVideoPaused(video);
// 获取当前播放的时间点
const currentTime = await api.getVideoCurrentTime(video);
// 获取当前是否循环播放
const loop = await api.getVideoLoop(video);

跳转时间与循环设置 ​

js
// 让视频跳到某一个时间
await api.setVideoCurrentTime(video, 3.2);
// 设置视频是否循环播放
await api.setVideoLoop(video, true);

播放事件 ​

  • play - 视频播放时触发
js
function onPlay(event) {
  const { type, target } = event;
}

await api.on('play', onPlay, video);
  • pause - 播放暂停时触发
js
function onPause(event) {
  const { type, target } = event;
}

await api.on('pause', onPause, video);
  • ended - 自然播放完毕时触发
js
function onEnded(event) {
  const { type, target } = event;
}

await api.on('ended', onEnded, video);
  • replay - 重新播放时触发
js
function onReplay(event) {
  const { type, target } = event;
}

await api.on('replay', onReplay, video);

什么时候用哪种视频 ​

普通视频 ​

适合绝大多数平面视频播放场景。

透明视频 ​

适合你已经准备好了平台支持的透明视频素材(左侧正常视频，右侧透明度)，希望直接叠加到场景中。

色度视频 ​

适合绿幕/蓝幕等抠色类效果，但最终视觉质量高度依赖素材质量和抠色配置。

注意

视频都是在3D场景中呈现，不是以普通的video标签形式在页面上出现。

自动播放注意 ​

浏览器对视频自动播放有强限制。即便 Kivicube 内部做了一些处置，以下情况仍要特别注意：

  • 强制隐藏立即体验按钮后，媒体更容易被浏览器拦截，导致不能播放
  • iOS 和部分 App 内 WebView 的策略更严格，也会导致不能播放
  • 首次播放时，如果不是用户点击视频播放，也会影响播放成功率

因此视频型内容上线前，务必在真实终端上做一次完整回归。