Skip to main content
The Video plugin adds a full set of playback controls to video panoramas. It works with the equirectangular video adapter and the cubemap video adapter, and supports timed autorotate keypoints synchronized to the video timeline.

​
Installation

npm install @photo-sphere-viewer/video-plugin
This plugin requires its stylesheet. Import @photo-sphere-viewer/video-plugin/index.css or add the CDN link to your <head>.

​
Usage

You must load one of the video adapters alongside this plugin: equirectangular video or cubemap video. Once loaded the plugin adds the following UI elements:
  • Play/pause button in the navbar
  • Volume button in the navbar
  • Time indicator in the navbar
  • Progress bar above the navbar
  • Large play button in the center of the viewer
import { Viewer } from '@photo-sphere-viewer/core';
import { EquirectangularVideoAdapter } from '@photo-sphere-viewer/equirectangular-video-adapter';
import { VideoPlugin } from '@photo-sphere-viewer/video-plugin';

const viewer = new Viewer({
    adapter: EquirectangularVideoAdapter,
    panorama: {
        source: 'path/video.mp4',
    },
    plugins: [
        VideoPlugin,
    ],
});

​
Multiple resolutions

Pair the Video plugin with the Settings plugin and Resolution plugin to offer quality options: 
import { VideoPlugin } from '@photo-sphere-viewer/video-plugin';
import { SettingsPlugin } from '@photo-sphere-viewer/settings-plugin';
import { ResolutionPlugin } from '@photo-sphere-viewer/resolution-plugin';

const viewer = new Viewer({
    adapter: EquirectangularVideoAdapter,
    plugins: [
        VideoPlugin,
        SettingsPlugin,
        ResolutionPlugin.withConfig({
            defaultResolution: 'FHD',
            resolutions: [
                {
                    id: 'UHD',
                    label: 'Ultra high',
                    panorama: { source: 'path/video-uhd.mp4' },
                },
                {
                    id: 'FHD',
                    label: 'High',
                    panorama: { source: 'path/video-fhd.mp4' },
                },
                {
                    id: 'HD',
                    label: 'Standard',
                    panorama: { source: 'path/video-hd.mp4' },
                },
            ],
        }),
    ],
});

​
Configuration

​
keypoints
Array<{ position, time }>
Timed keypoints used by the autorotate button to follow the video timeline. Not updatable after init — use setKeypoints() instead.
keypoints: [
    { time: 0,    position: { yaw: 0,    pitch: 0 } },
    { time: 5.5,  position: { yaw: 0.25, pitch: 0 } },
    { time: 12.8, position: { yaw: 0.3,  pitch: -12 } },
]
Using keypoints requires the Autorotate plugin to be loaded.
​
progressbar
boolean
default:"true"
Display a progress bar above the navbar. Not updatable after init.
​
bigbutton
boolean
default:"true"
Display a large play button in the center of the viewer. Not updatable after init.
​
lang
object
Localization strings merged with the main viewer lang object.
lang: {
    videoPlay: 'Play/Pause',
    videoVolume: 'Volume',
}

​
Methods

​
setKeypoints(keypoints)

Replaces the current timed keypoints.

​
Events

​
play-pause

Triggered when the video starts playing or is paused. 
videoPlugin.addEventListener('play-pause', ({ playing }) => {
    console.log('Playing:', playing);
});

​
volume-change

Triggered when the video volume changes. 
videoPlugin.addEventListener('volume-change', ({ volume }) => {
    console.log('Volume:', volume);
});

​
progress

Triggered as the video plays. 
videoPlugin.addEventListener('progress', ({ time, duration, progress }) => {
    console.log(`${time}s / ${duration}s (${Math.round(progress * 100)}%)`);
});
This plugin adds the following items to the default navbar:
  • videoPlay — play/pause the video
  • videoVolume — change volume or mute
  • videoTime — displays current time and duration (not interactive)
If you use a custom navbar, add these identifiers to your navbar configuration manually.

​
SCSS variables

VariableDefaultDescription
$progressbar-height3pxHeight of the progress bar
$progressbar-height-active5pxHeight of the progress bar on mouse hover
$progressbar-progress-colorcore.$buttons-colorColor of the playing progress
$progressbar-buffer-colorcore.$buttons-active-backgroundColor of the buffered progress
$progressbar-handle-size9pxSize of the seek handle
$progressbar-handle-colorwhiteColor of the seek handle
$volume-height80pxHeight of the volume control
$volume-width$progressbar-height-activeWidth of the volume control
$volume-bar-color$progressbar-progress-colorColor of the volume bar
$volume-track-color$progressbar-buffer-colorBackground of the volume track
$volume-handle-size$progressbar-handle-sizeSize of the volume handle
$volume-handle-color$progressbar-handle-colorColor of the volume handle
$bigbutton-colorcore.$buttons-colorColor of the central play button
$bigbutton-size20vw (portrait) / 10vw (landscape)Size of the central play button

Build docs developers (and LLMs) love

Get started for freeTalk to us