Video / Alpha Video / Chroma-Key Video

Related reference: Scene API / Video

The advanced Web API provides three kinds of video objects:

• standard video: createVideo()
• alpha video: createAlphaVideo()
• chroma-key video: createKeyingVideo()

Create a Video

Standard Video

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

Alpha Video

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

Chroma-Key Video

const keyingVideo = await api.createKeyingVideo(
  '/assets/green-screen.mp4',
  {
    // Key color to remove. Default is #00F400.
    color: '#00F400',
    // Color similarity (0~1). Default is 0.42.
    similarity: 0.42,
    // Smoothness (0~1). Default is 0.08.
    smoothness: 0.08,
    // Spill reduction speed (0~1). Default is 0.
    spill: 0,
  }
);
await api.add(keyingVideo);

Although ArrayBuffer input is supported, video files are usually large and consume significant memory. Using URLs is generally the better choice.

Playback Control

Play

await api.playVideo(video, {
  loop: true, // Whether playback should loop
  full_screen: false // Whether it should play fullscreen
});

You can later change the loop setting with setVideoLoop().

Pause, Stop, and Replay

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

Read Playback State

// Video duration
const duration = await api.getVideoDuration(video);
// Whether the video is paused
const paused = await api.getVideoPaused(video);
// Current playback position
const currentTime = await api.getVideoCurrentTime(video);
// Whether looping is enabled
const loop = await api.getVideoLoop(video);

Seek and Set Looping

// Jump the video to a given time
await api.setVideoCurrentTime(video, 3.2);
// Set whether the video should loop
await api.setVideoLoop(video, true);

Playback Events

• play - fires when video playback starts

function onPlay(event) {
  const { type, target } = event;
}

await api.on('play', onPlay, video);

• pause - fires when playback pauses

function onPause(event) {
  const { type, target } = event;
}

await api.on('pause', onPause, video);

• ended - fires when playback finishes naturally

function onEnded(event) {
  const { type, target } = event;
}

await api.on('ended', onEnded, video);

• replay - fires when playback restarts

function onReplay(event) {
  const { type, target } = event;
}

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

Which Video Type to Use

Standard Video

Best for most regular flat-video playback scenarios.

Alpha Video

Best when you already have a platform-supported alpha-video asset and want to overlay it directly into the scene.

Chroma-Key Video

Best for green-screen or blue-screen style keying, but the final visual quality depends heavily on source quality and keying configuration.

Note

All videos are rendered inside the 3D scene, not as regular HTML video elements on the page.

Autoplay Notes

Browsers enforce strict autoplay rules. Even though Kivicube handles some compatibility issues internally, you should still pay close attention to these cases:

• if you force-hide the Start Now Button, media is more likely to be blocked by the browser
• policies are stricter on iOS and in some in-app WebViews
• first playback is less reliable when it is not triggered by a user action

So before shipping any video-heavy content, always run a full regression pass on real target devices.