LibZL API

Direct API links:

Zlbolt
direct2D
direct2DController

LibZL is a library used for interacting with ZeroLight content streams. LibZL allows you to more finely control what occurs in the stream by providing an API which allows you to augment the capabilities of the stream.

Usage

LibZL itself consists of an API factory, allowing you to choose which API you wish to use. There are at this time two APIs - zlbolt and direct2D. The zlbolt API provides control over a 2D or 3D stream, while direct2D instead provides you with the capability to generate a series of images via a set of frame configurations.

This document has a few basic usage examples and explanations of the public APIs provided for working with the ZeroLight content streams.

LibZL can be invoked to produce the zlbolt API in the following way:

const libzl = new LibZL();
const zlbolt = libzl.zlbolt(projectName, mainDomain);

and similarly the direct2d API can be called with libzl.direct2D(mainDomain).

These return promises which you can resolve to get the API. Earlier workflows often involved overriding event functions after the API was defined in the browser. This method has been succeeded by the promises form and a newer event listener method to call multiple functions at the time of the event.

Using Zlbolt

Created using libzl.zlbolt(projectName, mainDomain);, this exposes the zlbolt API. This is typically used via listening to event functions, such as onModeChange, to extend the stream's functionality. For a full list of events see the Events and Listeners section.

Note that some events may be overridden instead of adding a listener. This is a legacy feature and isn't recommended. Some events may not support that method of calling.

Minimal Usage Example

This is a minimal example for a fictitious car manufacturer, Antarctic Motors, connecting to a stream of the 2019 Snowmobile.

const libzl = new LibZL();
const connectionParameters = {
    customer: 'antarctic',
    environment: 'live',
    protocol: 'https',
    region: 'eu-west-1'
};

const car = {
    manufacturer: 'antarctic',
    model: 'snowmobile',
    year: 2019
};

// the element ID of the container to put the stream in
const parent = 'myStreamContainer';
const options = {connectionParameters, parent, car};

const projectName = 'antarctic';
libzl.zlbolt(projectName, 'zlthunder.net')
    .then(function(api) {
        // Adding to the global namespace
        zlbolt = window.zlbolt = api;

        // Adding event listeners for things we're interested in
        zlbolt.addEventListener('error', function(error) {
            console.log('zlbolt had an error: ', error);
        });
        zlbolt.addEventListener('streamReady', function() {
            console.log('The stream is ready!');
        });

        //Connecting to the stream
        //    - options contains parent DOM element name to attach to
        zlbolt.connect(options);
    });

Events and Listeners

To extend the stream's functionality there are a set of event functions which may be overridden, or listened to.

Events are hooked into via addEventListener instead. These include a larger range of events, and are intended to be used for page events. These can be either listened to or overridden entirely (not recommended). To override the event function entirely, capitalise the event name and prefix with on. Please note that this is a legacy feature and some event types may not support this.

Valid events, and their arguments provided, to listen for include:

onError - fired when zlbolt encounters an error
onReconnect - fired upon attempting to reconnect to a previous stream
onStreamReady - fired upon the stream being ready
onReadyToStream - fired upon the stream being primed for streaming
onStreamDisconnect - fired upon the stream disconnecting
streamReady
streamMetricsUpdated - single argument an object with streamMetrics in
streamDisconnect - single argument a string with the reason for disconnecting
streamConnectFailed - single argument, object - { outputType: string (e.g.'WebRTCStreamOutput'), error: Error }
allStreamAttemptsFailed - single argument, object - { instanceIp: string, ssl: boolean, errors: { [outputType: string]: Error } }
streamWillDowngrade
streamWillUpgrade
streamDidDowngrade
streamDidUpgrade
streamBecameIdle
streamBecameActive
streamQualityChange - single argument with the name of the new string quality
switchEnvironment
animStateChanged - an object with the name of the triggered animation and the anim state
environmentChanged - single argument with the name of the environment
prcodesChanged - single argument object with the PR code differences
cameraChanged
cameraMoved - single argument object with duration and measurements
2DODAvailable - a single argument returning the 2D api - not recommended to use directly
2DFrameRequest - a pair of arguments representing any errors and the returned frame object
all2DFramesReady
2DFrameTransition - a pair of arguments representing any errors and the returned frame object
2DProgressBarChanges - a pair of arguments representing any errors, and a progress object
adoptionInformation - a single argument representing very rough adoption estimates
error - single argument an object representing the error
reconnect
maximumConnectionRetries
optionsReconcile
optionsChange
mouseDown - a single argument object representing the click position
mouseUp - a single argument object representing the mouse position
cameraSequenceStart - a single argument string with the name of the camera sequence
cameraSequenceEnd - a single argument string with the name of the camera sequence
modeChange - a pair of arguments with the mode and a string status (pending, success, or error)
ping - Raised when the 3D stream receives an instance ping result. ({ success: true, time: number} | { success: false, count: number })
streamElementsChanged - Raised when the stream containers elements are changed.
bandwidthAssessed - a single argument with the bandwidth results
connectionStatusChanged - a pair of arguments with the previous status and changed status in connection flow ({status, newStatus})
makeFrameConfig - a triple of arguments with the made frame config, the base config that was supplied, and the string context that it was called in
fetchFramesRequest - a triple of arguments with the frameConfigs, the generation options, and the string context that it was called in

There are a few extra that require richDataStreamConfig.enableCompletionEvents to be set in options

environmentChange - (status, [env name]) string arguments e.g. ("started", undefined) ("completed", "Antarctica")
animationChange - animationsObject object argument with key animation names and state value
cameraChange - cameraName string argument with the camera name
prcodesChange - prcodes string argument with the current prcodes once they change

Debugging and Profiling

The libZL Profiler

LibZL profiler could be enabled for a single session by the user or on a per-service basis in Central Config.

Single session

Use one of the below methods to enable profiler:

URL parameter - add zlLoggerTimer=1 to your URL parameters
Local storage - add zlLoggerTimer=1 to the browser's local storage

Central config Add to Central Config file property:

{
    "debug": {
        "profile": true
    }
}

Profile summary will be available using the libZL method:

LibZL.zlLoggerTimerSummary()

Using Direct2D

Created using libzl.direct2D(mainDomain), this exposes the 2d API. This is slightly different as it needs an intermediate connection step handling the options. This API is used to obtain images of the cars by specifying frame configurations, which is useful for e.g. thumbnail images or preview shots.

A returned frame has a variety of promises as properties, which resolve at different times. See the direct2D class for more details.

Minimal Usage Example

This is a minimal example for a fictitious car manufacturer, Antarctic Motors, connecting to a stream of the 2019 Snowmobile.

const libzl = new LibZL();

const connectionParameters = {
    customer: 'antarctic',
    environment: 'live',
    protocol: 'https',
    region: 'eu-west-1'
};

const car = {
    manufacturer: 'antarctic',
    model: 'snowmobile',
    year: 2019
};

const options = {connectionParameters, car};

libzl.direct2D('zlthunder.net')
    .then(api => api.connect(options))
    .then(api => {

        // Create a frame config from a partial one.
        let frame = api.makeFrameConfig({
            car: '{manufacturer} {model} {year}',
            environment: '{environment}',
            camera: {
                specification: 'named',
                name: '{camera}'
            },
            size: [800, 600]
        });

        // Request the frames. Pass larger array for more frames.
        let frameRequest = api.fetchFrames([frame]);

        // Add listener to the ready promise of each frame.
        Object.keys(frameRequest.frames).forEach(function(filename) {
            let frame = frameRequest.frames[filename];

            // When frame is ready, insert it into DOM.
            frame.readyPromise.then(function() {
                    $('<img />').attr('src', frame.url).appendTo($('body'));
            });
        });
    });

API Reference

zlboltAPI

This is the zlbolt API. One can expand its functionality by adding event listeners to the following events (via zlbolt.addEventListener):

streamReady
streamMetricsUpdated
streamDisconnect
streamWillDowngrade
streamWillUpgrade
streamDidDowngrade
streamDidUpgrade
streamBecameIdle
streamBecameActive
streamQualityChange
switchEnvironment
switchBackplate
environmentChanged
prcodesChanged
cameraChanged
2DODAvailable
2DFrameRequest
2DFramesReady
error
reconnect
optionsReconcile
optionsChange
mouseDown
mouseUp
cameraSequenceStart
cameraSequenceEnd
modeChange
bandwidthAssessed
connectionStatusChanged
ping

Kind: global class

new zlboltAPI(zlboltV2)

Construct the API - Don't construct this yourself, get it via libZL.

Params

zlboltV2 ZLBolt -
The ZLBolt instance.

zlboltAPI.streamIsActive ⇒ `boolean`

Deprecated

Get a boolean representing whether the stream is active.

Kind: instance property of zlboltAPI
Returns: boolean -

Whether the stream is active.

Since: 4.8.0 and will be suspended from 5.0.0
Properties

Name	Type	Description
isActive	`boolean`	Whether the stream is active.

zlboltAPI.version ⇒ `string`

The API version string

Kind: instance property of zlboltAPI
Returns: string -

Semantic version string.

Properties

Name	Type	Description
version	`string`	Semantic version string.

zlboltAPI.logger ⇒ `object`

Get the default logger instance.

Kind: instance property of zlboltAPI
Returns: object -

The default logger instance.

Properties

Name	Type	Description
logger	`object`	The default logger instance.

zlboltAPI.minSupportedJQuery

The minimum version of jQuery that we support.

Kind: instance property of zlboltAPI
Properties

Name	Type	Description
minSupportedJQuery	`string`	Min jQuery version.

zlboltAPI.addEventListener(eventName, callback)

Add a function to be called upon certain stream events.

Kind: instance method of zlboltAPI
Params

eventName string -
The name of the event to add a listener for.
callback function -
The function to call for the given event, with arguments coming from the event type itself.

zlboltAPIbatchChanges(command, callback)

Call a supplied function without provoking stream updates

This can be useful for e.g. changing the camera and PR codes in a single call without creating additional intermediate 2D images that aren't required.

Upon completion triggers a generation call.

Params

command function -
Executes this function without provoking stream updates
callback requestCallback

zlboltAPI.changeStreamOutput(handlerClass)

Attempts to change the stream output method (3D mode only).

Available handlers:

Outputs.VP9WebSocket
Outputs.MJPEGCanvas2DWebSocket

Kind: instance method of zlboltAPI
Params

handlerClass Class -
Reference to target handler class.

zlboltAPI.checkConnectionQuality([callback])

Check the quality of the current connection to the ZeroLight stream.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.
The result parameter is an object that contains a latency property; this is a number between 0 (best) and 3 (very poor).
And a connected property which is true once connection to the stream-server is established.

zlboltAPI.checkSupport(callback)

Query the 2d and 3d support for the current user.

The callback receives an object of form { support2D, support3D } where the values are one of "unsupported", "full", or "partial".

Kind: instance method of zlboltAPI
Params

callback requestCallback

zlboltAPI.clearStreamIdleTimeout()

If the stream has gone idle, clear the idle state, trigger the stream becoming active event, and remove any idle overlay if there is one.

Kind: instance method of zlboltAPI

zlboltAPI.connect(options, [callback]) ⇒ `ZLBolt`

Connect to the ZeroLight Instance Manager and request a stream.

Kind: instance method of zlboltAPI
Returns: ZLBolt -

A ZLBolt instance

Emits: zlbolt#event:onStreamReady, zlbolt#event:on2DODAvailable
Params

options object -
A set of options.
- .connectionParameters object -
  A structure containing the definition of which Zerolight CAS service to connect to.
  - [.protocol] string -
    Server protocol to use ("http" or "https").
  - .customer string -
    Customer ID of service to connect to.
  - .environment string -
    Environment ID of service to connect to (For example "live").
  - [.region] string -
    Optional AWS region to connect to (auto-detected if not provided).
- [.resolution] object -
  The desired resolution of the stream.
  - [.x] number -
    The desired width of the stream, in pixels.
  - [.y] number -
    The desired height of the stream, in pixels.
- [.authToken] string -
  An authorisation token.
- .parent string -
  The name of a DOM element that will contain the stream object.
- [.setupPrCodes] string -
  Specify an initial set of prcodes.
- [.setupCamera] string -
  Specify the initial camera.
- [.setupEnvironment] string -
  Specify the initial environment.
- .car object -
  The car to use in the stream.
  - .manufacturer string -
    The name of the car manufacturer.
  - .model string -
    The name of the car model.
  - .year string -
    The car production year. For example "2015".
- [.reservedInstanceTag] string -
  The name of a specific cloud instance to request the stream from.
- [.streamClass] string -
  Optional class which will be added to the stream dom element.
- [.username] string -
  Optional string to be passed onto the CAS for authorisation.
- [.password] string -
  Optional string to be passed onto the CAS for authorisation.
- [.cloudmine] string -
  Cloudmine accumulator's URL to use, if not set - instance manager's endpoint will be used instead.
- [.clientMarket] string -
  Optional string to be used to filter metrics.
- [.clientApplication] string -
  Optional string to be used to filter metrics.
- [.consumeMouseScrollEvents] boolean -
  Optional boolean; if present and true, causes mousewheel events to be consumed by the canvas and not passed onto the page.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.disconnect([callback])

Disconnect from a live stream.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.enableMouseTracking([toggle], [callback])

Deprecated

Enable or disable automatic mouse camera controls

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

[toggle] boolean = true -
Whether to enable or disable the mouse camera controls
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.enumerateAllAnimations([callback])

Passes a list of animations to the provided callback (async) - will include invalid animations.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.enumerateAllCamerasByType([callback])

Enumerates all available cameras, keyed by type.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.enumerateAnimations([callback])

Passes a list of valid animations to the provided callback (async).

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.enumerateCameras([callback])

Passes a list of valid cameras to the provided callback (async).

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.enumerateEnvironments([callback])

Passes a list of valid environments to the provided callback (async).

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.forceImageChanging([duration], [callback])

Force the stream to update its image, even if it would be otherwise idle

Kind: instance method of zlboltAPI
Params

[duration] number = 0.5 -
Duration for output to be forced
callback requestCallback -
A function to be called on the response.

zlboltAPI.getAnimStates()

Return the current animation states.

Kind: instance method of zlboltAPI

zlboltAPI.getAssetMetadata()

Query the active connection for asset metadata, if available. Responds with metadata (a dictionary keyed by car identifiers) and extended metadata (a more complex object detailing car and environment assets, as well as service and viewer information).

Kind: instance method of zlboltAPI

zlboltAPI.getAvailableLayers([callback])

Get and return the list of available layers.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getBandwidthAssessment()

Get the results of the bandwidth assessment. This is an object featuring the ping and downloadSpeedfound, set to -1 if they haven't been measured yet or there was an error.

Kind: instance method of zlboltAPI

zlboltAPI.getCamera()

Return the current camera name as a string.

Kind: instance method of zlboltAPI

zlboltAPI.getCameraPosRotFov([callback])

Return the current posrotfov data as seen by the controller.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that receives an error or the data

zlboltAPI.getCarPosRotPanelUI([callback])

Get Car Pos/Rot gizmo ui.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getConnectionStatus() ⇒ `string`

Get an instance zlbolt connection flow Class.

Kind: instance method of zlboltAPI
Returns: string -

Current ZLbolt connection flow status

zlboltAPI.getCurrentMode()

Returns the mode of the current connection, e.g. '2D', '3D', or null.

Kind: instance method of zlboltAPI

zlboltAPI.getCurrentScalingProfile()

Get current scaling profile

Kind: instance method of zlboltAPI

zlboltAPI.getDevelopmentStates([callback])

Get and return the list of development states.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getEnvironment()

Return the current environment name as a string.

Kind: instance method of zlboltAPI

zlboltAPI.getFrameStatuses(filenames, [string], callback)

Deprecated

Query the instance manager for very recent frame statuses This method only works with a direct2D instance active during a 2d stream

The callback receives an argument of form { success, frames }success is a boolean representing whether the API call succeededframes is an object of filename: status mappings

Note that post-generation cleanup means it may report as unknown if called some time after generation has occurred

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

filenames Array -
list of frame filenames to query
[string] -
clientId - optional clientId to ask for, if unspecified uses your own
callback requestCallback

zlboltAPI.getFrameStatuses(filenames, [string], callback)

Deprecated

Query the instance manager for very recent frame details This method only works with a direct2D instance active during a 2d stream

The callback receives an argument of form { success, records }success is a boolean representing whether the API call succeededrecords is a filename: progressRecord mapping

The progress records contain information about the stage of generation the request is in and the progress percentage through that stage

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

filenames Array -
list of frame filenames to query
[string] -
clientId - optional clientId to ask for, if unspecified uses your own
callback requestCallback

zlboltAPI.getGizmoDataUI([callback])

Returns all currently valid gizmo data.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getPosRotFov()

Return the current posrotfov data.

Kind: instance method of zlboltAPI

zlboltAPI.getPrCodes()

Return the current set of product codes for the current live stream.

Kind: instance method of zlboltAPI

zlboltAPI.getQRCode(elementName, [callback])

Deprecated

Get a QR Code to synchronise a Samsung Gear VR with the current cloud instance

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

elementName string -
The name of a DOM element (typically a div) to append the QR Code to
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.getRequestState(requestId, [callback])

Returns the status of a request

Kind: instance method of zlboltAPI
Params

requestId int -
A valid request id that was provided from the viewer
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.getResolution()

Return the current stream resolution.

Kind: instance method of zlboltAPI

zlboltAPI.getRotationIndex([callback])

Get the current turnaround rotation index, if applicable.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getRotationIndex([callback])

Get the maximum valid rotation index, if applicable.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getSceneTypes([callback])

Get Scene Types.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getScreenshotURL(options, [height])

Deprecated

Returns the url to use to generate a screenshot of current stream

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

options Object | number -
screenshot options (interpreted as width if height was specified)
[height] number | undefined -
(legacy) height of the screenshot (interprets "options" parameter as width if this is specified)
- .width number -
  width (required)
- .height number -
  height (required)
- .msaa number -
  msaa
- .ssaa number -
  ssaa
- .format string -
  one of [png,jpg] (png includes alpha channel)
- .filename string -
  alphanumeric string (with no extension)
- .quality number -
  quality 1-100
- .background_colour number -
  background_colour If specified will hide background environment and render plain colour

zlboltAPI.getSteerAngle()

Get the angle of the wheels in degrees

Kind: instance method of zlboltAPI

zlboltAPI.getStreamController()

Return the internal stream controller (2D or 3D), if connected

Kind: instance method of zlboltAPI

zlboltAPI.getStreamElements() ⇒ `Object`

Returns the stream HTMLElements that can be used to make some custom overlays on the stream. When the elements are updated to removed the streamElementsChanged event will be fired

Kind: instance method of zlboltAPI
Returns: Object -

object with references to current stream elements

zlboltAPI.getStreamQuality()

Get the current 3D quality setting. This is an index for an object representing the stream quality options available.

Kind: instance method of zlboltAPI
See: getStreamQualityOptions

zlboltAPI.getStreamQualityOptions([callback])

Get the stream quality options. This can be used alongside setStreamQuality to set features such as the max resolution and minimum bandwidth required before a downgrade to a 2D stream occurs.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function called on the response - check the second argument's options property for the quality options.

zlboltAPI.getStreamSnapshotURL([callback])

Ask to capture a snapshot of the stream, and return its URL (async).

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.getStreamedAssetInfo(callback)

Query the active connection for asset information, if available. This is a convenience wrapper around getAssetMetadata to get asset references and idents.

Kind: instance method of zlboltAPI
Params

callback requestCallback

zlboltAPI.getUserContentAssets([callback], type)

Get User Content Assets.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.
type String -
Requires a field UserContentType passing the string of the type you are requesting (I.E ‘UserContentType: “Dome“').

zlboltAPI.getUserContentSceneUI([callback], type)

Get Scene UI.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.
type String -
Requires a field UserContentType passing the string of the type you are requesting (I.E ‘UserContentType: “Dome“').

zlboltAPI.isSupported([callback])

Deprecated

Check if zlbolt is supported.

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.movableExteriorCamera(val)

Set/Get the string representing the exterior camera movement style.

Kind: instance method of zlboltAPI
Params

val string -
Name of moveable exterior camera.

zlboltAPI.movableInteriorCamera(val)

Set/Get the string representing the interior camera movement style.

Kind: instance method of zlboltAPI
Params

val string -
Name of moveable interior camera.

zlboltAPI.moveCamera(posX, posY, posZ, [callback])

Move the camera by a certain amount of world units, subject to the current camera"s constraints. Note that calling this function when an animated camera is active will cause an automatic switch to a static camera type.

Kind: instance method of zlboltAPI
Params

posX number -
The amount of movement on the screen-space X axis.
posY number -
The amount of movement on the screen-space Y axis.
posZ number -
The amount of movement on the screen-space Z axis (depth).
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.moveFlyCamera(positionDelta, rotationDelta, zoom, [callback])

Free-Move the Fly Camera

Kind: instance method of zlboltAPI
Params

positionDelta number
rotationDelta number
zoom number
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.moveSharkCamera([posVel], [rotVel], [callback])

Applies positional and/or rotational impulses to camera.

Kind: instance method of zlboltAPI
Params

[posVel] number -
Forward movement impulse value (0 to 1 range), or null.
[rotVel] object -
Object with {x, y} keys (-1 to 1 range), or null.
callback requestCallback -
Fired when impulse has been applied.

zlboltAPI.moveStream(domElementId)

Move the stream wrapper element to a new parent

Kind: instance method of zlboltAPI
Params

domElementId string -
DOM identifier for the element to be the new parent of the stream wrapper.

zlboltAPI.panoramicCapture([callback])

Take a panoramic capture of the stream (if supported)

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.
- The result parameter is an object that contains a latency property; this is a number between 0 (best) and 3 (very poor).
- And a connected property which is true once connection to the stream-server is established.

zlboltAPI.pauseSequence()

If a sequence is playing, pause it on the current frame

Kind: instance method of zlboltAPI

zlboltAPI.reconnect([options], [callback])

Attempts to reconnect, with the specified options.

Kind: instance method of zlboltAPI
Params

[options] object -
Optional new options. Uses existing if omitted.
callback function -
Invoked upon success or failure.

zlboltAPI.removeEventListener(eventName, callback)

Remove the given event listener - Note: This compares the callback functions, so be aware that this may fail to remove the function if you're not passing the same function object in.

Kind: instance method of zlboltAPI
Params

eventName string -
The name of the event to remove a listener for.
callback function -
The function to remove from the given event.

zlboltAPI.resetCameraToStart([callback])

Resets camera to initial position.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
Fired when reset has completed.

zlboltAPI.resumeSequence()

If a sequence is paused, resume playing the sequence from the current frame

Kind: instance method of zlboltAPI

zlboltAPI.rollingPlane(floorColor, stop, rollingspeed, [callback])

Use a specific camera for the live stream

Kind: instance method of zlboltAPI
Params

floorColor Array.<Number> -
colors to be used for the floor color [
stop boolean -
whether to stop the rolling
rollingspeed number -
the speed to move at
callback requestCallback -
the function to call afterwards

zlboltAPI.screenshotCapture(width, height, [callback])

Capture a screenshot of the given width and height.

Kind: instance method of zlboltAPI
Params

width number -
Of the screenshot.
height number -
Of the screenshot.
callback requestCallback

zlboltAPI.sendRawMouseEvent(type, x, y, wheel, [callback])

Deprecated

Programmatically send mouse events of various (e.g. A click) over the stream

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

type string -
The type should be one of['mouseover', 'mouseout', 'mousemove', 'mousedown', 'mouseup', 'wheel', 'click']
x number -
the horizontal proportion of the window the event occurred at, in range [0,1]
y number -
the vertical proportion of the window the event occurred at, in range [0,1]
wheel boolean -
doesn't actually affect anything but left in the signature to not break legacy usage.
callback requestCallback -
A function to be called on the network response

zlboltAPI.setAnimation(anim, animationState, instant, [callback])

Signals the VE to set the state of a particular animation. Maintains animation state locally.

Kind: instance method of zlboltAPI
Params

anim string -
Animation identifier.
animationState boolean -
The desired state of the animation.
instant boolean -
Flag to skip animation to end. 1 to skip, 0 to play normally.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setCarPosRot(data, [callback])

Set the position and rotation of the car in world space, with optional snap to ground plane.

Kind: instance method of zlboltAPI
Params

data Object -
Object containing: {position: [x,y,z], rotation: [x,y,z], snapToGround: False, useWheelContacts: False}
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setCarPosRotPanelUI([callback])

Set Car Pos/Rot gizmo ui.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setCurrentMode(mode, [callback])

Dynamically transition between 2D and 3D modes. Note, upon transition, a disconnect even will be fired, with the reason, "mode_transition".

Kind: instance method of zlboltAPI
Emits: zlbolt#event:onModeChange
Params

mode string -
The mode to switch to (2D, 3D).
callback function -
Invoked upon success or failure.

zlboltAPI.setFeatureFlag(name, state, [callback])

Deprecated

Set feature flag states after connection.

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

name string -
The name of the feature flag.
state boolean -
The state of the feature flag.
callback requestCallback

zlboltAPI.setGalleryCameraList(galleryCameraList)

Set the gallery camera list for turnarounds/rotation indices

Kind: instance method of zlboltAPI
Params

galleryCameraList Array.<String> -
gallery cameras

zlboltAPI.setGizmo(gizmo, eventType, [callback])

Set a gizmo.

Kind: instance method of zlboltAPI
Params

gizmo Array.<string> -
Object with gizmo GUID.
eventType string -
String e.g "SELECT" | "UPDATE" | "DESELECT".
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setInputTrackingState([state], [callback])

Enable or disable input tracking (keyboard, mouse, etc.)

Kind: instance method of zlboltAPI
Params

[state] boolean = true -
Whether to enable or disable the input tracking
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.setLogLevel(...levels)

Set logging levels for all currently registered loggers. Presently supported for integers 1-4.

Kind: instance method of zlboltAPI
Params

...levels number -
The level of each log.

zlboltAPI.setPosRotFov(Current, [callback])

Set the current posrotfov, if applicable.

Kind: instance method of zlboltAPI
Params

Current object -
Posrotfov data.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setPrCodes(codes, options, [callback])

Set multiple product codes for the current live stream.

Kind: instance method of zlboltAPI
Params

codes Array -
An array of strings, with each string being a product code.
options Object -
Advanced options object for switching pr codes
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setRotationIndex(Current, [callback])

Set the current turnaround rotation index, if applicable.

Kind: instance method of zlboltAPI
Params

Current object -
Rotation index.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setScalingProfile(name, updateViewport, noAnimation)

Switch to a different scaling profile that's in the scaling config

Kind: instance method of zlboltAPI
Params

name string -
The name of the scaling profile to switch to
updateViewport boolean -
Whether to update the current container
noAnimation boolean -
Whether to instantly switch it

zlboltAPI.setSharkCameraEnabled(state, [callback])

Toggles state of shark camera. Disabling will return stream to previously active camera, if applicable.

Kind: instance method of zlboltAPI
Params

state boolean -
True to enable shark camera, false otherwise.
callback requestCallback -
Fired when reset has completed.

zlboltAPI.setSteerAngle(angle, [options], [callback])

Set the angle of the wheels

Kind: instance method of zlboltAPI
Params

angle number -
clamped to [-45, 45] degrees
[options] object -
steering options
- [.instant] bool = false -
  whether the wheels should turn smoothly or jump (ignored in 2DOD in favour of true)
callback requestCallback -
a function that is executed when this operation is complete

zlboltAPI.setStreamQuality(name)

Set the current 3D quality setting. This is the index of an object representing the stream quality options available.

Kind: instance method of zlboltAPI
Params

name string -
The key of the stream quality options to switch to.

zlboltAPI.setTranslatedPrCodes(codes, [callback])

Set multiple product codes for the current live stream, without running them through any translation.

Kind: instance method of zlboltAPI
Params

codes Array -
An array of strings, with each string being an already translated product code.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.setUserContentScene([callback], type, sceneData)

Set Scene UI.

Kind: instance method of zlboltAPI
Params

callback requestCallback -
A function that is executed when this operation is complete.
type String -
Requires a field UserContentType passing the string of the type you are requesting (I.E ‘UserContentType: “Dome“').
sceneData Object -
Scene data such as effects and assets to update.

zlboltAPI.setViewportSize(width, height, [callback])

Set the viewport dimensions. Note that this will be ignored if the autoscaling configuration option is set.

Kind: instance method of zlboltAPI
Params

width number -
The desired width of the viewport.
height number -
The desired height of the viewport.
callback requestCallback -
A function to be called upon the response.

zlboltAPI.startSequence(Sequence)

Start playing a sequence for the live stream

Kind: instance method of zlboltAPI
Params

Sequence sequence -
The sequence to play including signed s3 urls

zlboltAPI.stopSequence()

Stop playing a sequence on the live stream

Kind: instance method of zlboltAPI

zlboltAPI.switchBackplate(Backplate, options, [callback])

Set backplate

Kind: instance method of zlboltAPI
Params

Backplate Object -
The backplate data we want to use
options Object -
Used to pass the env and userContentType & resetAll
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.switchCamera(cameraName, [options], [callback])

Use a specific camera for the live stream

Kind: instance method of zlboltAPI
Params

cameraName string | number -
The name or id of the camera
[options] object -
A set of options for this switch
- [.force] boolean -
  Forces the camera switch without inheriting parameters
- [.movementMode] string -
  Special movement for 3D cameras, e.g. 'fly', 'flysmooth', 'fade'
- [.preserveIndex] boolean -
  Attempts to preserve rotation index if switching between rails
- [.preserveIndex3D] boolean -
  Attempts to preserve rotation index if switching between rails in 3D
- [.smooth] boolean -
  In 2D determines whether there should be a visible fade when switching image
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.switchEnvironment(Name, [callback])

Set environment - valid environments can be found with enumerateEnvironment

Kind: instance method of zlboltAPI
Params

Name String -
of the environment to switch to
callback requestCallback -
A function that is executed when this operation is complete

zlboltAPI.toggleAlexa(toggle)

Deprecated

Enables or disables "Alexa control mode".

Kind: instance method of zlboltAPI
Since: 4.8.0 and will be suspended from 5.0.0
Params

toggle bool -
Alexa mode on or off.

zlboltAPI.triggerAnimation(anim, instant, [callback])

Signals the VE to trigger a particular animation. Maintains animation state locally and requests reverse if animation has already played.

Kind: instance method of zlboltAPI
Params

anim string -
Animation identifier.
instant boolean -
Flag to skip animation to end. 1 to skip, 0 to play normally.
callback requestCallback -
A function that is executed when this operation is complete.

zlboltAPI.updateOutputResolution(width, height, [noResize])

Update the resolution of an active stream. By default, it will resize the viewport, and attempt to change the resolution of the video stream itself, if applicable.

Kind: instance method of zlboltAPI
Params

width number -
Target stream width.
height number -
Target stream height.
[noResize] boolean = false -
Whether or not to resize the viewport.

zlboltAPI.validate([options], [callback])

Connect to the ZeroLight streaming service and ask for pre-stream validation of this client.

Kind: instance method of zlboltAPI
Params

[options] object -
A set of options (see "zlbolt.connect" for details of valid options).
callback requestCallback -
A function that is executed when this operation is complete. The result parameter contains two fields: "status" which will be "valid" if a subsequent call to zlbolt.connect can be expected to succeed, or "invalid" if it will not. In the invalid case, the result will also contain a "reason" field containing details as to why the validation was refused.

createZLBoltAPI(libZLIdentifierData) ⇒ `zlbolt`

Entrypoint for creating a new ZLBolt instance

Kind: global function
Returns: zlbolt -

The zlbolt instance.

Params

libZLIdentifierData * -
LibZL identifier.

_default(mainDomain, libZLIdentifierData) ⇒ `object`

Creates an instance of direct2D.

Kind: global function
Returns: object -

The direct2D API instance.

See: direct2DController
Params

mainDomain string -
Domain name for connection purposes.
libZLIdentifierData object -
InstanceId (string): libZL instance ID (uuid), origin (string): request origin for server or page url for browser.

direct2DController

This class, created via direct2D, allows you to create and request frame promises. The frames will resolve into the requested images.

The standard workflow is to create and submit an array of frameConfigs and resolve them to get the images.

Kind: global variable

direct2DController.makeFrameConfig(partialConfig, [context]) ⇒ `FrameConfig`

Constructs a full frame config, based on the specified partial config.

Example partial frame config:

{

    prcodes: 'AAAA,BBBB,CCCC',
    environment: '{environment}',
    camera: {
        specification: 'named',
        name: '{camera}'
    },
    anim_state: { Doors: 1, Trunk: 0 },
    size: [720, 360],
    car: '{manufacturer} {model} {year}',
}

Kind: instance method of direct2DController
Returns: FrameConfig -

A frame configuration object.

Params

partialConfig object -
Partial config data.
- .car string -
  Manufacturer, model, and year, separated by spaces.
- .environment string -
  Environment to use.
- [.prcodes] string -
  Comma-separated list of prcodes to apply.
- [.camera] object -
  Camera object
  - [.specification] string -
    Camera mode (currently "named").
  - [.name] string -
    Camera name.
- [.anim_state] object -
  Object with animation names as keys (1 to enable, 0 to disable).
- [.size] Array -
  Two element array, containing target width and height of frame.
- [.format] string -
  File output format (jpg,png).
[context] string | undefined -
Type of request for new frameConfig

direct2DController.makeFrameConfig(filename, [getGeneratedURL], [cdnURLOverride]) ⇒ `string`

Builds the full URL to the specified frame filename.

Kind: instance method of direct2DController
Returns: string -

The full URL to the specified frame filename.

Params

filename string -
Frame filename.
[getGeneratedURL] boolean -
Whether the base url of what's returned is that of the image store.
[cdnURLOverride] string -
An override of the base url of what's returned (if !getGeneratedURL).

direct2DController.destroy()

Disconnects, killing the client session, and cancels any pending jobs.

Kind: instance method of direct2DController

direct2DController.getClientId() ⇒ `string`

Returns current 2D client ID string, if connected.

Kind: instance method of direct2DController
Returns: string -

The client ID.

Direct API links:
Usage
Using Zlbolt
- Minimal Usage Example
Events and Listeners
Debugging and Profiling
- The libZL Profiler
Using Direct2D
- Minimal Usage Example
zlboltAPI
createZLBoltAPI(libZLIdentifierData) ⇒ zlbolt
_default(mainDomain, libZLIdentifierData) ⇒ object
direct2DController

LibZL API

Direct API links:​

Usage​

Using Zlbolt​

Minimal Usage Example​

Events and Listeners​

Debugging and Profiling​

The libZL Profiler​

Using Direct2D​

Minimal Usage Example​

API Reference

zlboltAPI​

new zlboltAPI(zlboltV2)​

zlboltAPI.streamIsActive ⇒ boolean​

zlboltAPI.version ⇒ string​

zlboltAPI.logger ⇒ object​

zlboltAPI.minSupportedJQuery​

zlboltAPI.addEventListener(eventName, callback)​

zlboltAPIbatchChanges(command, callback)​

zlboltAPI.changeStreamOutput(handlerClass)​

zlboltAPI.checkConnectionQuality([callback])​

zlboltAPI.checkSupport(callback)​

zlboltAPI.clearStreamIdleTimeout()​

zlboltAPI.connect(options, [callback]) ⇒ ZLBolt​

zlboltAPI.disconnect([callback])​

zlboltAPI.enableMouseTracking([toggle], [callback])​

zlboltAPI.enumerateAllAnimations([callback])​

zlboltAPI.enumerateAllCamerasByType([callback])​

zlboltAPI.enumerateAnimations([callback])​

zlboltAPI.enumerateCameras([callback])​

zlboltAPI.enumerateEnvironments([callback])​

zlboltAPI.forceImageChanging([duration], [callback])​

zlboltAPI.getAnimStates()​

zlboltAPI.getAssetMetadata()​

zlboltAPI.getAvailableLayers([callback])​

zlboltAPI.getBandwidthAssessment()​

zlboltAPI.getCamera()​

zlboltAPI.getCameraPosRotFov([callback])​

zlboltAPI.getCarPosRotPanelUI([callback])​

zlboltAPI.getConnectionStatus() ⇒ string​

zlboltAPI.getCurrentMode()​

zlboltAPI.getCurrentScalingProfile()​

zlboltAPI.getDevelopmentStates([callback])​

zlboltAPI.getEnvironment()​

zlboltAPI.getFrameStatuses(filenames, [string], callback)​

zlboltAPI.getFrameStatuses(filenames, [string], callback)​

zlboltAPI.getGizmoDataUI([callback])​

zlboltAPI.getPosRotFov()​

zlboltAPI.getPrCodes()​

zlboltAPI.getQRCode(elementName, [callback])​

zlboltAPI.getRequestState(requestId, [callback])​

zlboltAPI.getResolution()​

zlboltAPI.getRotationIndex([callback])​

zlboltAPI.getRotationIndex([callback])​

zlboltAPI.getSceneTypes([callback])​

zlboltAPI.getScreenshotURL(options, [height])​

zlboltAPI.getSteerAngle()​

zlboltAPI.getStreamController()​

zlboltAPI.getStreamElements() ⇒ Object​

zlboltAPI.getStreamQuality()​

zlboltAPI.getStreamQualityOptions([callback])​

zlboltAPI.getStreamSnapshotURL([callback])​

zlboltAPI.getStreamedAssetInfo(callback)​

zlboltAPI.getUserContentAssets([callback], type)​

zlboltAPI.getUserContentSceneUI([callback], type)​

zlboltAPI.isSupported([callback])​

zlboltAPI.movableExteriorCamera(val)​

zlboltAPI.movableInteriorCamera(val)​

zlboltAPI.moveCamera(posX, posY, posZ, [callback])​

zlboltAPI.moveFlyCamera(positionDelta, rotationDelta, zoom, [callback])​

zlboltAPI.moveSharkCamera([posVel], [rotVel], [callback])​

zlboltAPI.moveStream(domElementId)​

zlboltAPI.panoramicCapture([callback])​

zlboltAPI.pauseSequence()​

zlboltAPI.reconnect([options], [callback])​

zlboltAPI.removeEventListener(eventName, callback)​

zlboltAPI.resetCameraToStart([callback])​

zlboltAPI.resumeSequence()​

zlboltAPI.rollingPlane(floorColor, stop, rollingspeed, [callback])​

zlboltAPI.screenshotCapture(width, height, [callback])​

Direct API links:

Usage

Using Zlbolt

Minimal Usage Example

Events and Listeners

Debugging and Profiling

The libZL Profiler

Using Direct2D

Minimal Usage Example

zlboltAPI

new zlboltAPI(zlboltV2)

zlboltAPI.streamIsActive ⇒ `boolean`

zlboltAPI.version ⇒ `string`

zlboltAPI.logger ⇒ `object`

zlboltAPI.minSupportedJQuery

zlboltAPI.addEventListener(eventName, callback)

zlboltAPIbatchChanges(command, callback)

zlboltAPI.changeStreamOutput(handlerClass)

zlboltAPI.checkConnectionQuality([callback])

zlboltAPI.checkSupport(callback)

zlboltAPI.clearStreamIdleTimeout()

zlboltAPI.connect(options, [callback]) ⇒ `ZLBolt`

zlboltAPI.disconnect([callback])

zlboltAPI.enableMouseTracking([toggle], [callback])

zlboltAPI.enumerateAllAnimations([callback])

zlboltAPI.enumerateAllCamerasByType([callback])

zlboltAPI.enumerateAnimations([callback])

zlboltAPI.enumerateCameras([callback])

zlboltAPI.enumerateEnvironments([callback])

zlboltAPI.forceImageChanging([duration], [callback])

zlboltAPI.getAnimStates()

zlboltAPI.getAssetMetadata()

zlboltAPI.getAvailableLayers([callback])

zlboltAPI.getBandwidthAssessment()

zlboltAPI.getCamera()

zlboltAPI.getCameraPosRotFov([callback])

zlboltAPI.getCarPosRotPanelUI([callback])

zlboltAPI.getConnectionStatus() ⇒ `string`

zlboltAPI.getCurrentMode()

zlboltAPI.getCurrentScalingProfile()

zlboltAPI.getDevelopmentStates([callback])

zlboltAPI.getEnvironment()

zlboltAPI.getFrameStatuses(filenames, [string], callback)

zlboltAPI.getFrameStatuses(filenames, [string], callback)

zlboltAPI.getGizmoDataUI([callback])

zlboltAPI.getPosRotFov()

zlboltAPI.getPrCodes()

zlboltAPI.getQRCode(elementName, [callback])

zlboltAPI.getRequestState(requestId, [callback])

zlboltAPI.getResolution()

zlboltAPI.getRotationIndex([callback])

zlboltAPI.getRotationIndex([callback])

zlboltAPI.getSceneTypes([callback])

zlboltAPI.getScreenshotURL(options, [height])

zlboltAPI.getSteerAngle()

zlboltAPI.getStreamController()

zlboltAPI.getStreamElements() ⇒ `Object`

zlboltAPI.getStreamQuality()

zlboltAPI.getStreamQualityOptions([callback])

zlboltAPI.getStreamSnapshotURL([callback])

zlboltAPI.getStreamedAssetInfo(callback)

zlboltAPI.getUserContentAssets([callback], type)

zlboltAPI.getUserContentSceneUI([callback], type)

zlboltAPI.isSupported([callback])

zlboltAPI.movableExteriorCamera(val)

zlboltAPI.movableInteriorCamera(val)

zlboltAPI.moveCamera(posX, posY, posZ, [callback])

zlboltAPI.moveFlyCamera(positionDelta, rotationDelta, zoom, [callback])

zlboltAPI.moveSharkCamera([posVel], [rotVel], [callback])

zlboltAPI.moveStream(domElementId)

zlboltAPI.panoramicCapture([callback])

zlboltAPI.pauseSequence()

zlboltAPI.reconnect([options], [callback])

zlboltAPI.removeEventListener(eventName, callback)

zlboltAPI.resetCameraToStart([callback])

zlboltAPI.resumeSequence()

zlboltAPI.rollingPlane(floorColor, stop, rollingspeed, [callback])

zlboltAPI.screenshotCapture(width, height, [callback])

zlboltAPI.sendRawMouseEvent(type, x, y, wheel, [callback])

zlboltAPI.setAnimation(anim, animationState, instant, [callback])