Video Player

Studio is being deprecated, please head over to the documentation page for Mattercraft, our most advanced 3D tool for the web, where you can find the most recent information and tutorials.

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

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:

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.