• home
  • HoloStream Web API

HoloStream Web API

The HoloStream Web API is a javascript API for Three.js projects.

This document is for developers looking to learn how to use the HoloStream API in their projects. For an example project using the HoloStream API, see the Example Web Player section.

HoloStream requires Three.js version 124.

Getting Started

To include HoloStream in your application, find the latest remote .js and .css files aand include them in your source along with Three.js, like so:

 <link rel="stylesheet" type="text/css" href="https://static.holostream.arcturus.studio/release/2021.1.5/remote/holostream-2021.1.5.css">
 <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r124/three.min.js"></script>
 <script src="https://static.holostream.arcturus.studio/release/2021.1.5/remote/HoloStream-2021.1.5.min.js"></script>

Creating a new HoloStream Instance

Use the new HoloStream() function to create a HoloStream Instance.

var holoStream = new HoloStream();

This will create and initialize a new HoloStream instance on your page. It will create a new <div> element to contain the web player, and inside of that it will create new <video> and<canvas>elements which are required for playback. The <video> element will be hidden, and the canvas will be used to present the streaming volumetric video content. You can optionally provide a container, as well as a canvas, if you wish to place and style the resources on your page instead of allowing HoloStream to automatically create the required components. To do this, see the available options in the next section of this document.

Playing HoloStream Content

To play HoloStream content, provide a valid manifest URL to the openURL() function, eg:

holoStream.openURL("[https://yourMediaService.com/validManifest.mpd](https://yourMediaService.com/validManifest.mpd)")

This will immediately load the referenced content, and it will be available to play back as soon as enough of the initial content has been retrieved and processed.

holoStream.handlePlay(true);

Constructor

HoloStream( options )

An optional Options object can be provided to the HoloStream constructor. You can supply an options object with the following fields:

  • debugEnabled - True/False. Enable additional debugging output to the browser console if debugEnabled == true

  • targetCanvasID - Supply the id of a <canvas> element to use with HoloStream.

  • targetContainerDivID - A string corresponding to the id of the <div> to contain the HoloStream web player.

  • hideUI- True/False. If true, then the UI will be completely hidden, will not be updated, and the underlying UI object will not be constructed

  • threeScene - A ThreeJS Scene object to use with HoloStream. If no threeScene is supplied one will be generated.

  • threeCamera -A ThreeJS Camera object to use with HoloStream. If no threeCamera is supplied one will be generated.

  • threeRenderer - A ThreeJS Renderer object to use with HoloStream. If no threeRenderer is supplied one will be generated.

  • uiImages - A JSON object containing one or more JSON objects corresponding to a desired UI element of the web player. The available object keys are: playButton, pauseButton, bufferingSymbol, playHead, jumboPlayButton. A special key, splashImage, is also available. If one of these objects is not included, the default HoloStream object will be loaded. If one of these objects is included, but with an empty string as its source, then that UI element will not be displayed. Each UI Image Object takes the form:

{source: "[https://yourimageURL](https://yourimageURL)", width: 100, height: 150}

The splashImage key has two additional controls, scaleToPercentageByWidth and scaleToPercentageByHeight. These parameters take a value between 0.0 and 1.0, representing 0% to 100%. These parameters allow you to scale the splash image to a percentage of the height or width of the player, while still maintaining the dimensions specified by width and height, and remaining within the bounds of the player window. It is important to note that the image must be served from a location with a proper CORS configuration. An example (used for the HoloStream splash image) to keep the image scaled to 80% of the width of the player is as follows:

{source: "[https://holostreamimageurl](https://yourimageURL)", width: 896, height: 151, scaleToPercentageByWidth: 0.8}

To use a HoloStream Options object, create it before initializing the HoloStream instance, and pass it to the constructor as follows:

var options = {hideUI: false};
var holoStream = new HoloStream(options);

Methods

.openURL(url : String)

To play HoloStream content, provide a valid .mpd URL to the openURL() function, eg:

holoStream.openURL("https://api-prod.holostream.arcturus.studio/media/bc701e01-4f4e-488d-bd7c-b77ed2cbb24a/stream/dash/manifest.mpd")

This will immediately load the referenced content, and it will be available to play back as soon as enough of the initial content has been retrieved and processed.

.handlePlay(playing : Boolean)

handlePlay plays and pauses the HoloStream clip.

  • playing: true plays the streaming clip. Setting handleplay to false pauses playback at the current frame.

.handleSeek(value : Number)

handleSeek seeks to the provided percentage of the HoloStream clip.

  • value: supply a value between 0.0 and 1.0 to specify a percentage of the total clip length to seek to.

.handleSeek(0.5);

.getThreeScene()

Returns the ThreeJS Scene associated with the HoloStream Player.

.getThreeMesh()

Returns the ThreeJS Mesh associated with the HoloStream Player.

.getHoloStreamCanvas()

Returns the Canvas that HoloStream is rendering to.

.getThreeRenderer()

Returns the ThreeJS Renderer that is rendering the HoloStream Player.

.getThreeCamera()

Returns the ThreeJS Camera associated with the HoloStream Player.

Properties

.preUpdateFunctions

This array is used to inject functions that should be executed immediately before the HoloStream object refreshes the frame and renders. Push objects which contain an update functions to call.

For example,

        holoStream.preUpdateFunctions.push({update: () => {
        console.log("updating");}
        });

.postUpdateFunctions

This array is used to inject functions that should be executed immediately before the HoloStream object refreshes the frame and renders. Push objects which contain an update function to call.

For example,

        holoStream.postUpdateFunctions.push({update: () => {
        console.log("updating");}
        });