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 of the HoloSuite Player docs.

HoloStream requires Three.js version 0.144.0.

If your HoloStream projects are made with an older version of Three.js, please refer to the Three Migration Guide to ensure proper migration to the current supported Three Version.

Getting Started¶

To include HoloStream in your application, find the latest remote .js and .css files and 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.13/remote/holostream-2021.1.13.css">
 <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r144/three.min.js"></script>
 <script src="https://static.holostream.arcturus.studio/release/2021.1.13/remote/HoloStream-2021.1.13.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 multiple instances of HoloStream content:¶

Performance will decline as more content is played simultaneously. As you add additional players, you will want to profile your application accordingly.

Create the first HoloStream instance.
Obtain references to the Three Renderer, Three Camera, and Three Scene from the instance; unless you are providing your own, in which case use your existing references to these objects.
Assign the renderer, camera, and scene to the holoStreamOptions object.
Initialize one or more additional players with the holoStreamOptions object, so that the Three references are shared.

Note

It is not recommended to use the default HoloStream UI when using multiple players; as the UI will currently only control the instance it is attached to.

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);

Important

It is advised that you wait for the streaming content to be ready for playback before presenting playback UI or other relevant application components to users.

Reference the .sequenceReadyFunctions to execute relevant components once playback is ready.

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.

openURL will return true if it succeeds or false if it fails. openURL can fail if a resource is unavailable, a network connection is interrupted, or if there is an internal issue with HoloStream. It is recommended that logic is added to safeguard your project to handle an occurrence of the failure case.

.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 second of the HoloStream clip.

value: Input an integer or float for the value, the value passed to handleSeek is the number of seconds to seek to.

.handleSeek(2);

.getThreeScene()¶

Returns the ThreeJS Scene associated with the HoloStream Player.

.getThreeMesh()¶

Returns the ThreeJS Mesh associated with the HoloStream Player.

.destroy()¶

Destroys an instance of HoloStream and all of its generated resources.

.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¶

.sequenceReadyFunctions¶

This array is used to inject functions that should be executed when the HoloStream object has refreshed the frame, rendered and is ready to play.

.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 function to call.

For example,

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

.postUpdateFunctions¶

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