Moving from StreamPixel or Arcware

Here is a small StreamPixel page, written the way StreamPixel's documentation shows. It hides a loading screen when the stream is ready, has a mute button, and sends openDoor to the Unreal application:

<iframe id="streamIframe"
  src="https://share.streampixel.io/PROJECT_ID"
  allow="autoplay; fullscreen" allowfullscreen></iframe>

<script>
  const STREAM_ORIGIN = "https://share.streampixel.io";
  const streamIframe = document.getElementById("streamIframe");

  window.addEventListener("message", (event) => {
    if (event.origin !== STREAM_ORIGIN) return;
    if (event.data.type === "stream-state" && event.data.value === "loadingComplete") {
      hideMyLoadingScreen();
    }
  });

  function mute() {
    streamIframe.contentWindow.postMessage({ message: "muteAudio" }, STREAM_ORIGIN);
  }
  function openDoor() {
    streamIframe.contentWindow.postMessage({ message: "openDoor" }, STREAM_ORIGIN);
  }
</script>

The same page on Eagle 3D Streaming. Two lines differ:

<iframe id="streamIframe"
  src="https://connector.eagle3dstreaming.com/v5/YOURNAME/YourApp/default?e3dsCompat=streampixel"
  allow="autoplay; fullscreen" allowfullscreen></iframe>

<script>
  const STREAM_ORIGIN = "https://connector.eagle3dstreaming.com";
  const streamIframe = document.getElementById("streamIframe");

  window.addEventListener("message", (event) => {
    if (event.origin !== STREAM_ORIGIN) return;
    if (event.data.type === "stream-state" && event.data.value === "loadingComplete") {
      hideMyLoadingScreen();
    }
  });

  function mute() {
    streamIframe.contentWindow.postMessage({ message: "muteAudio" }, STREAM_ORIGIN);
  }
  function openDoor() {
    streamIframe.contentWindow.postMessage({ message: "openDoor" }, STREAM_ORIGIN);
  }
</script>

1. Point the iframe at your Eagle 3D Streaming link

   Copy the streaming URL of your application from the Control Panel, as described in Embed with an iframe, and use it as the src.

2. Add ?e3dsCompat=streampixel to it

   This turns on the two StreamPixel behaviours that could confuse a page written for Eagle 3D Streaming, explained below. If the link already has a ?, add it as &e3dsCompat=streampixel.

3. Change the origin your code checks and posts to

   The browser checks this, not Eagle 3D Streaming. A message posted with "https://share.streampixel.io" as its target origin is never delivered to a frame on another address, and a listener that only accepts that origin ignores every reply. Use the origin of your Eagle 3D Streaming link, which is the scheme and host only, with no path.

What ?e3dsCompat=streampixel turns on

Almost everything works without it: the messages your page posts, the stream-state events and the stream-metadata event are always understood and always sent. The parameter turns on StreamPixel mode, which adds two behaviours that a page written for Eagle 3D Streaming would not expect:

Why the parameter, and not just the first message. StreamPixel's own sample page waits for the plain text "loadingComplete" before it posts anything. Without the parameter that page would wait forever: the plain text is only sent in StreamPixel mode, and nothing has been posted yet to turn the mode on. With the parameter, the plain text arrives once the stream is ready. If the mode turns on later, after the stream is already ready, the plain text is sent at that moment.

Why it is not always on. A page written for Eagle 3D Streaming may run JSON.parse on every message it receives, and a plain loadingComplete would make it throw. And a bare web address from an Eagle 3D Streaming app is shown as a short message on screen, not opened.

Post them exactly as StreamPixel documents them, as plain objects. The same command sent as a JSON string works too. Only messages from the page that directly contains the iframe are accepted.

* These use the Eagle 3D Streaming iframe commands setVolume, ForceEndSession and captureScreenShot, which are in the next platform release. The current production player ignores them without an error. See Controlling the stream.

A screenshot is not downloaded inside the frame. StreamPixel's frame downloads the picture by itself. A browser refuses a download that starts inside a frame from another website without a click in that frame, so on Eagle 3D Streaming the picture is handed to your page and your page saves it. The few lines that do that are in Controlling the stream.

Messages posted before the Eagle 3D page has loaded are lost, as they are with StreamPixel. Wait for the first stream-state event, authenticating, before posting anything.

Every event arrives as StreamPixel documents it, { type: "stream-state", value: "loadingComplete" } and so on, after Eagle 3D Streaming's own event for the same moment. The four loading stages always arrive in order, each exactly once, even when Eagle 3D Streaming skips a step: an application that is already running has nothing to prepare, so connecting is sent just before finalising.

* reconnecting arrives with the next platform release. Codes 4004 and 4006 follow from the same events as Eagle 3D Streaming's own time-limit and application-closed messages, but have not yet been reproduced in a test.

Never sent: restricted, and the codes 1001, 1005, 1006, 4000–4003, 4005 and 4007.

Your application sends these with Send Pixel Streaming Response, exactly as it did for StreamPixel.

Your listener also receives Eagle 3D Streaming's own messages. They are objects, and when your application sends JSON, a parsed copy of it follows the text. A StreamPixel page that checks event.data.type is unaffected. A page that runs JSON.parse(event.data) on everything should check typeof event.data === "string" first.

Arcware's Web SDK starts a session from a Share ID written into the page. Eagle 3D Streaming starts one from a session token that your server requests with your Streaming API key and passes to the page. That is the one part of your code that has to change. A file called arcware-compat.js provides Arcware's names on top of the Eagle 3D Streaming Web SDK, so the rest of your code runs as it is.

A page written the way Arcware's documentation shows:

<div id="video-container"></div>
<button onclick="showCamera()">Camera 1</button>

<script type="module">
  import { ArcwareInit } from "@arcware-cloud/pixelstreaming-websdk";

  const { PixelStreaming, Application } = ArcwareInit(
    { shareId: "share-YOUR-SHARE-ID" },
    { initialSettings: { AutoConnect: true }, settings: {} }
  );

  PixelStreaming.videoInitializedHandler.add(() => hideMyLoadingScreen());
  Application.getApplicationResponse((response) => console.log("from Unreal", response));
  document.getElementById("video-container").appendChild(Application.rootElement);

  window.showCamera = () => Application.emitUIInteraction({ camera_view: "cam_01" });
</script>

The same page on Eagle 3D Streaming:

<div id="video-container"><div id="playerUI"></div></div>
<button onclick="showCamera()">Camera 1</button>

<script src="./scripts/dist/e3dsCore.min_ns.js"></script>
<script src="./compat/arcware-compat.js"></script>

<script type="module">
  // Your server requests the token with your Streaming API key.
  const tokenData = await fetch("/api/stream-token", { method: "POST" })
                            .then((r) => r.json());

  const { PixelStreaming, Application } = ArcwareInit(
    { tokenData, client: "your-username" },
    { initialSettings: { AutoConnect: true }, settings: {} }
  );

  PixelStreaming.videoInitializedHandler.add(() => hideMyLoadingScreen());
  Application.getApplicationResponse((response) => console.log("from Unreal", response));
  document.getElementById("video-container").appendChild(Application.rootElement);

  window.showCamera = () => Application.emitUIInteraction({ camera_view: "cam_01" });
</script>

1. Load the Eagle 3D Streaming Web SDK, then arcware-compat.js

   In that order. e3dsCore.min_ns.js is the Web SDK itself, from the Web SDK sample (see Set up the Web SDK); arcware-compat.js is in the compat folder of the same repository. Remove the import of @arcware-cloud/pixelstreaming-websdk: ArcwareInit is now provided by the script.

2. Add <div id="playerUI"></div>

   The Eagle 3D Streaming player draws into that element, and rootElement returns it. Your code can still append rootElement wherever it did before; that moves it there.

3. Pass a session token instead of the Share ID

   ArcwareInit({ tokenData, client }): tokenData is the token response your server got from Eagle 3D Streaming, and client is the username the token was created for. How to get one is in The token, and e3ds_controller.main(); keep the request on your server, as Keeping your API key off the browser explains. Passing only a shareId stops with an error saying that a token is needed.

Everything after ArcwareInit is unchanged. Each mapping below has been checked call by call; a complete live session through this layer has not yet been tested end to end.

Accepted, but never called. These exist so your code does not stop with an error, and the first use of each logs one notice in the browser console: queueHandler, sessionIdHandler, loveLetterHandler, whiteLabellingChangedHandler, fileTransferHandler, and the afkWarningActivate, afkWarningUpdate, afkWarningDeactivate and afkTimedOut events. Nothing registered with addEventListener is called.

Accepted, and do nothing apart from a one-time notice: toggleMic, reconnect, send and sendAnalyticsEvent.

Coming from StreamPixel

• The origin your page checks and posts to, as above.
• Settings from StreamPixel's dashboard — password, idle timeout, session length, resolution limits — are set again in the Eagle 3D Streaming Control Panel; see Session and access.
• Built-in chat (comms) has no counterpart. The messages are accepted and ignored.
• Values on the link for your application (?key=value sent to Unreal as JSON at the start) are not translated. Eagle 3D Streaming passes values on the link to your application as command-line parameters instead; see Command-line parameters.
• Meeting rooms (streamerId, sfuHost, sfuPlayer on the link) are not translated. Eagle 3D Streaming's equivalent is meeting links.
• isTouchDevice is not sent to your application at the start of a session. Your application asks for the viewer's device instead; see Detect the viewer's device.
• Screenshots are saved by your page, not by the frame, as above.
• setResolution is applied as requested. StreamPixel's rule of ignoring sizes above the project's maximum quality has no counterpart.
• Custom data with a top-level cmd or Type field is read as an Eagle 3D Streaming message, not forwarded to your application. Rename that field.
• StreamPixel's Web SDK (StreamPixelApplication, from streampixelsdk) is not translated; only the iframe is. Move such a page to an iframe as above, or to the Eagle 3D Streaming Web SDK.

Coming from Arcware

• The session start: a token from your server in place of the Share ID, as above.
• initialSettings and settings are kept in Config but not applied. Buttons, mouse mode, muted start and branding are set in the Eagle 3D Streaming Control Panel or with the Web SDK's own calls; see Controlling the stream.
• The queue, session id, loading messages, idle warning and file transfer events never fire, as listed above. For loading progress, use the Web SDK's own callbacks in the Web SDK reference.
• Close codes 4450–4666 are never produced. websocketOnCloseHandler always reports 1000, and reason says why.
• Session reuse — reconnect() and the ?session, ?noSession and ?reconnect parameters — has no counterpart. A new session needs a new token, because a token is used once.
• Not provided at all: CoreSetup, getIncomingFile(), fileDownload() and the ?wl branding parameter. Code that calls them must be changed.
• Resizing: Arcware's page sends your application { Console: "r.setres …" } when the window changes size. This layer does not, because Eagle 3D Streaming manages the stream's resolution itself. Whether an application that resizes only on that message follows the window has not been tested.