Intro

Building a Web Page

If more control is needed that the OmniStream Viewer allows then a native integration is the approach to take. This allows for custom loading screens, more control over the video codecs used and for deeper integration between the application being streamed and the webpage hosting the page through sending JSON data between the webpage and the application.

LibZL is the JavaScript library used to do this integration. It and forms a part of the collection of modules and tools within the ZeroLight Palette SDK. To connect to and control an OmniStream experience we need to use the ZLCloudStream sub-module.

Note

When accessing an OmniStream stream from outside of a ZeroLight domain, you need to add your origin in the render service settings to allow access from that domain.

Basics

Including LibZL dynamically

The module is hosted to allow dynamic inclusion like so:

<script src="https://libzl.zlthunder.net/libzl/versions/latest/libzl.js"></script>

A specific version identifier can be used to stick to a specific version:

<script src="https://libzl.zlthunder.net/libzl/versions/5.1.3/libzl.js"></script>

Connect

Connects to a stream using the defined connection settings. Event listeners should be bound before calling connect, to be sure of catching all events.

cloudstream.connect(cloudstreamSettings);

Connection Parameters

The settings that define where a cloudstream will attempt to connect to to retrieve a stream, and where on the hosting page to display the stream.

const cloudstreamSettings = {
  //True when connecting to a specific machine you know the address of, false for normal usage
  directConnection: false,
  //Your account settings
  cloudConnectionParameters: {
    //Your project name
    customer: "omnistream",
    //Your streaming Render Service (eg. stage or live)
    renderService: "yourservicename",
  },
  //Optional: Address for a direct connection to a instance or PC - leave empty for normal usage
  directConnectionParameters: {
    ipAddress: "localhost",
  },
  //Container in hosting page to present stream in to
  parent: "streamContainer",
  //Optional: video or xr, to request a video stream or xr stream
  streamingMode: "video",
  //Optional: defaults to true - touch events will produce fake mouse events
  fakeMouseWithTouch: true,
};

note

You can find the the specific parameters to connect to your service in Portal.

Simple Example

<!-- We need libZL -->
<script src="https://libzl.zlthunder.net/libzl/versions/latest/libzl.js"></script>

<!-- We need a container to attach the stream to -->
<div id="streamContainer"></div>

<!-- We need a bit of javascript to sort the connection out -->
<script>
  const libzl = new LibZL();

  const cloudstreamSettings = {
    directConnection: false,
    cloudConnectionParameters: {
      customer: "omnistream",
      renderService: "yourservicename",
    },
    streamingMode: "video",
    parent: "streamContainer",
  };

  libzl.cloudstream("cloudstreamExample").then(function (api) {
    //Adding to the global namespace
    cloudstream = window.cloudstream = api;

    //Adding event listeners to what we're interested in
    cloudstream.addEventListener("error", function (error) {
      console.log("OmniStream had an error: ", error);
    });
    cloudstream.addEventListener("streamReady", function () {
      console.log("The stream is ready!");
    });

    //Connecting to the stream
    //    - options contains parent DOM element name to attach to
    cloudstream.connect(cloudstreamSettings);
  });
</script>

Advanced Example

For an advanced example, including a full state integration see https://github.com/ZeroLight-Ltd/omnistream-web-state-example/blob/main/OmniStreamStateExample.html