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

Handling Autoplay

Because of the browser's media autoplay restrictions, videos inside a scene may fail to play when playback is requested.

To handle this, Kivicube silently plays the audio and video media in the scene once when the user clicks the "Start Now" button on the landing page.

After that, playback can happen freely during the experience.

This solves the autoplay issue for audio and video objects that come with the scene. However, videos added dynamically through the API can still fail to autoplay.

For that case, the plugin provides the setVideoNum API so the application layer can tell the plugin how many videos it intends to add dynamically.

The plugin will then silently play more videos when the "Start Now" button is clicked. Later, when createVideo or similar APIs are called, they will automatically be matched to a video element that can autoplay, achieving the autoplay effect.

Note

This must be called before the user clicks the "Start Now" button, otherwise it has no effect.

// Tell the plugin how many videos the application layer will dynamically add
await api.setVideoNum(10);

Create Video Objects

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.