Skip to main content

Reference

Connection Settings​

const cloudstreamSettings = {
  directConnection: false,
  cloudConnectionParameters: {
    customer: "omnistream",
    renderService: "yourservicename",
  },
  directConnectionParameters: {
    ipAddress: "localhost",
  },
  streamingMode: "video",
  parent: "streamContainer",
  appSelect: {
    project: "omnistream",
    app: "testproject",
    id: "0000",
  },
  fakeMouseWithTouch: true,
  initialAppStateData: { "TruckColour": "red" }
};
  • directConnection - When set to true the page will connect directly to the ip address in the directConnectionParameters
  • consumeMouseClicks - When set to true OmniStream will consume mouse click events and prevent browser default actions
  • consumeContextMenuEvents - When set to true OmniStream will consume mouse right click events and prevent browser default actions (including right-click context menus in stream viewport)
  • clientApplication - The name of the connecting application (website) for tracking/accounting purposes
  • cloudConnectionParameters - Settings used to connect to cloud service
    • customer - Your customer information - provided to you by ZeroLight
    • renderService - Your cloud rendering service name (e.g. prelive or live) - provided to you by ZeroLight
  • directConnectionParameters - Settings used to directly connect to a PC
    • ipAddress - IP address of PC running the OmniStream app and ZLManager (usually "localhost")
  • idleDisconnectTime - Time in ms that a user who does not interact will be disconnected, if omitted then users will never be disconnected when idle
  • streamingMode - "video" for video stream, "image" for image mode or "xr" for VR
  • parent - Container used to display the stream
  • appSelect - Optional app select, if not defined libZL will auto query and use default app
  • fakeMouseWithTouch - Defaults to true - touch events will produce fake mouse events
  • useRawJsonMessaging - Set to true to use your raw JSON sending rather that ZeroLight state. If enabled use sendJsonData and jsonDataReceived. setAppStateData will error if true. Defaults to false.
  • initialAppStateData - State JSON object to be passed and for the app to match before a stream will be considered ready. If an app does not report the state has been matched, the stream will not be started. JSON schema follows Send and Receive
  • onDemandConfig - Settings used to control image generation when operating in image mode
    • smoothTransition - Defaults to true - adds crossfade between image frames

Functions​

Query Apps​

Get the details for all of the apps that have been deployed to a service. If multiple apps have been deployed to a service this can be used to present a UI to allow the user to chose which one they wish to stream. This can be called before a connect call.

cloudStream.queryAppsOnService({ "cloudConnectionParameters": {
    "customer": "omnistream",
    "renderService": "bc1c22dcdemoser",
    "protocol": "https"
  } }, console.warn).then(console.info);

Response comes back in the form:

{ apps: ["app name here"], metadata: { "app name here": { name: "friendly name", thumb: "thumbnail URL" }} }

Set Audio​

If audio has been enabled in the source application, then you can enable/disable audio on the stream or select between mono or stereo audio. Due to browser restrictions this can only be triggered in a JavaScript function called as a result of a user interaction.

cloudStream.setAudioState(true / false, { stereo: true / false });

Set Streaming Mode​

Switch the stream mode from between video mode and image mode after a connection has been made (switching between other modes and XR is not possible - a stream must be initiated as an XR stream). Takes a callback for when the switch has been completed.

cloudStream.setStreamingMode('image', (...args) => { console.log('Switched streaming mode to ', ...args); });

Set Omdemnd View​

When in image mode change between staticImage and panocapture views. staticImage captures and presents a static image, panocapture captures a cubemap and presents it projected on a sphere with click and drag controls.

cloudstream.setOnDemandView(mode)

Get Omdemnd View​

Returns the currently selects ondemnd view.

console.log('Current OnDemandView is: ', cloudstream.getCurrentOnDemandView().viewName);

Bandwidth Assessment​

Perform a bandwidth assessment before upgrading a stream from image to video.

cloudStream.performBandwidthAssessment( (ping, downloadSpeed) => { console.log('Download speed is ', downloadSpeed, 'ping is ', ping); });

Ge the currently active streaming mode

cloudStream.getStreamingMode();

Mouse Pointer Capture​

If the source application needs to capture the mouse (for example in a first person experience). Due to browser restrictions this can only be triggered in a JavaScript function called as a result of a user interaction.

cloudStream.setPointerLockState(true/false);

Set Fullscreen​

Makes the stream window take up the full desktop. Due to browser restrictions this can only be triggered in a JavaScript function called as a result of a user interaction.

cloudStream.setFullscreenState(true/false);

Send State Data​

Send a JSON object with the state that the application should attempt to match. When matched appStateDataChanged event will be fired. See State Management for details on OmniStream state.

cloudStream.setAppStateData(JSONObject)

Send JSON Data​

Send a JSON object to the application, intended for users who do not wish to use OmniStream state processing. Ensure useRawJsonMessaging is passed at true in the options if intending to use this method.

cloudStream.sendJsonData(JSONObject)

Capture Screenshot​

Capture a screenshot of the application at the passed resolution and return the buffer to the browser to be displayed or downloaded.

const base64Data = await cloudStream.captureImage(1920, 1080, format);
Note

Currently cloudStream.captureImage is only available in Unreal and excludes Slate UI elements from the capture.

Events​

OmniStream fires events you can listen to for information about what's happening with the stream.

Stream Ready​

The stream is ready is being rendered to the specified stream container element.

cloudStream.addEventListener("streamReady", function () {
  console.log("The stream is ready!");
});

Error​

The has been an error, error details are passed as an argument.

cloudStream.addEventListener("error", function (error) {
  console.log("OmniStream had an error: ", error);
});

App State Data Changed​

The application state has been updated, JSON object representing the new current state is passed as an argument.

Note

While appStateDataChanged is usually triggered from a call to setAppStateData, applications are allowed to trigger state changes spontaneously, so this listener should be in place even if no requests to change state have yet been sent. Two areguments are passed, the first is the new state, the second details if the transition was fully complete or if there was a timeout or any unmatched state.

cloudStream.addEventListener("appStateDataChanged", (newState, details) => {
  console.log("appStateDataChanged new state is: ", JSON.stringify(newState), " transition details: ", details);
});

JSON Data Received​

JSON data sent by the application has been received. This will fire when JSON information is sent from the application outside of the state system, but does not fire for state messages.

cloudStream.addEventListener("jsonDataReceived", (parsedJSON) => {
  console.log("jsonDataReceived", JSON.stringify(parsedJSON));
});

Drag Events​

Drag events are raised when the mouse is moved with the left mouse button held down.

cloudstream.addEventListener('dragStart', (data) => console.log('dragStart', data));
cloudstream.addEventListener('dragMove', (data) => console.log('dragMove', data));
cloudstream.addEventListener('dragEnd', (data) => console.log('dragEnd', data));

Data to the callback fuction is returned in the form:

interface DragEvtPayload {
 container: { x: number; y: number };//Exact position in the container, with top left as origin
 relative: { x: number; y: number };//Delta from last drag event in the current drag operation
 normalised: { x: number; y: number };//Normalised position in the container, with top left as origin
}

Switch Mode Set App Data​

When requesting a switch between modes (e.g. image and video), an event is fired which allows updating state for the mode to be switched to. An example use case for this would be when in an interactive camera in video mode and wanting to change to a static camera in image mode. targetMode comes through as ondemand or streaming. If setAppStateDataCallback is not called then the transition will continue with the unmodified state.

cloudstream.addEventListener('beforeModeSwitchSetAppStateData', (curAppStateData, setAppStateDataCallback, targetMode) => {
     const newState = { ...curAppStateData, camera: targetMode === 'ondemand' ? 'staticCam1' : 'flycam' };
      setAppStateDataCallback(setAppStateData);
});

Debug Commands​

Force change stream output​

The codec and connection type will be automatically selected, to help with debugging you can force the codec to a select format.

cloudStream.changeStreamOutput("WebRTCStreamOutput");
cloudStream.changeStreamOutput("H264WebSocket");
cloudStream.changeStreamOutput("H265WebSocket");
cloudStream.changeStreamOutput("VP9WebSocket");
cloudStream.changeStreamOutput("MJPEGCanvas2DWebSocket");

Stats​

The stats can help you debug issues with connection to your instances.

cloudStream.setStreamStatsEnabled(true / false);