Video Player Symbol

Studio

Video Player Symbol

The Video Player symbol is a component for displaying streaming video in the 3D view using a URL to a hosted video file.

The URL needs to link directly to a video file as opposed to one uploaded to a video hosting site such as Vimeo or YouTube. The server hosting the video file also needs to support range requests in order for the video to play properly across all devices. We recommend using a CDN for faster, more scalable video serving e.g. AWS CloudFront or CloudFlare.

It comes complete with user control UI as well as emitted events and exported functions for controlling video playback from outside the symbol.

Creating a Video Player Symbol

Creating a Video Player Symbol

The Video Player symbol can be added to your project by clicking on the plus icon from the Symbol Definitions panel, then selecting the 'Video Player' component. Clicking 'Create' will add the subsymbol to the list of Symbol Definitions.

Using a Video Player Symbol

First, drag the Video Player symbol into your Hierarchy to create an instance of it. Then, with the instance selected in the Hierarchy, head to the Properties panel to edit its settings.

The settings for a Video Player symbol are as follows:

Video Player Symbol Settings
Parameter Type Description
videoURL string The URL of the video.
autoPlay boolean Whether the video should start playing automatically.
showControls boolean Whether the video controls should be visible.
showSeekBar boolean Whether the bar depicting the current playback time should be visible.

Supported Video Format

The Video Player symbol uses Z.Video to display the streaming video.

The following format is supported across a wide range of mobile devices, and is the recommended format for video played with Z.Video:

  • MP4
  • "Web-optimized" with the index at the start of the file
  • Baseline or Main profile
  • 800 kbps bitrate in order to support playback over cellular connections

Z.Video also supports HLS (HTTP Live Streaming), a format that automatically adjusts the quality of a video stream between multiple bitrates and resolutions, based on the bandwidth capacity of a users device. For more information see the Wikipedia article.

Emitted Events

A Video Player symbol emits the following events:

Event Description
video:finish Emitted when the video completes.
video:paused Emitted when the video is paused.
video:buffering Emitted when more data must be downloaded before playback can continue.
video:playing Emitted when playback first occurs.
video:error Emitted when there's an issue with video playback.
video:aspectratio Emitted when the aspect ratio of the video is known, or subsequently changes.
video:resize Emitted when the width/height in pixels of the video is known, or subsequently changes.
video:time Emitted when the seek position of playback changes.
video:duration Emitted when the duration of the video is known, or subsequently changes.
Example
// Local variable storing a video player node
var video_player = symbol.nodes.video_player;
// Event handler for the finish event
video_player.on("video:finish", () => {
    // Runs when the finish event occurs on the video_player 
    console.log("Video finished!");
});

Exported Functions

A Video Player symbol exports the following functions:

Parameter
video_player.nodes.control.start( ) Continues playback from the current seek position.
video_player.nodes.control.restart( ) Restarts playback from the start of the video.
video_player.nodes.control.pause( ) Pauses playback at the current seek position.
video_player.nodes.control.time( ) : number Gets the current seek time in milliseconds.
video_player.nodes.control.time(t : number) Sets the current seek time in milliseconds.
video_player.nodes.control.volume( ) : number[] Gets the current volume.
video_player.nodes.control.volume(v: number) : void Sets the current volume.
Example
// Local variable storing a video player node
var video_player = symbol.nodes.video_player;
// Calling the start function
video_player.nodes.control.start();
Open in new window