Skip to main content
Intermediate For a developer with a page built on the v1 SDK. After this page, that page runs on the current engine: either with its code unchanged, or rewritten for the v2 API.
Public beta. These pages describe version 2.0.0-beta.2 of @streampixel/web-sdk. Names and behaviour can still change before the stable 2.0.0 release. See the changelog.
v1 is the StreamPixelApplication function of the streampixelsdk package. v2 is @streampixel/web-sdk.
Keep v1 in production until you have tested v2 with your own project.

Choose your path

There are two ways to move a v1 page. Both end on the same engine. Why move: v1 is no longer developed. Fixes and new features arrive in v2, whose engine updates without a reinstall and recovers from more network problems.

Before you start

These three checks apply to both paths. None of them needs code.

Check the access setting of each project

Your page follows the access setting of the project in the dashboard: Check each project’s access setting before you move its page, so that a password or sign-in screen does not surprise your viewers. If you put a password on a project only to protect its share link, and your site has its own sign-in, Your app only (not available yet) is the mode for you (see Access).

The allowed-domains list

The platform checks the project’s allowed-domains list when the page connects. It compares the exact origin of the page: scheme, host and port. A page on an origin that is not allowed is refused when it connects: the session ends with code 1008. If your project has a list, test the page on its real domain before going live.

Content-Security-Policy

v1 was one bundle. v2 downloads its engine from Streampixel’s servers when the stream starts, and talks to different hosts. If your site sends a Content-Security-Policy header:
Add wss://*.livekit.cloud https://*.livekit.cloud to connect-src if you use chat. Entries that only v1 needed can be removed. If the engine cannot be downloaded, the stream does not start (create() rejects with EngineLoadError); there is no copy inside the package. The full list is under Content-Security-Policy.

The two paths, step by step

1

Install the compatibility package

It replaces the v1 package of the same name.
2

Leave your code as it is

Imports and calls stay the same:
3

Check what is different

Read What is different below against your page.
4

Build, test and release

Build the page and test it once with your own project before you release it.
The stream starts in your page as before. If the project is set to password or single sign-on, the viewer sees that screen first.

Keep your code: the compatibility package

streampixelsdk@next is the v1 API (StreamPixelApplication) running on the v2 engine. A page written for v1 keeps its code. Underneath, every session is a v2 session: it is opened with a session ticket, it follows the project’s access setting, and it runs the engine that Streampixel serves and updates. The compatibility package receives fixes, not new features. New features arrive in the v2 API.

What you get

  • Access screens built in. A password project asks for its password, and a single sign-on project sends the viewer to sign in, with no code from you.
  • A self-updating engine. Fixes to connection, recovery and telemetry reach your page without a reinstall.
  • Recovery. A dropped connection is repaired for up to 180 seconds (v1: 60 seconds).
  • A direct connection first. The stream uses the relay only when the network needs it.

What is different

Check each of these against your page.
StreamPixelApplication(settings) resolves to the same five objects.Also exported, with their v1 names:
  • StreamPixelVoiceChat: the same constructor and methods.
  • Flags, NumericParameters, TextParameters and ControlSchemeType: the setting names of the Pixel Streaming library, as plain values.
The stream-state messages that v1 posted to an embedding page are posted in the same shape. Page styles that hid a v1 screen by its id, such as #afkOverlay { display: none }, still hide the screen that stands for it.
Every v1 option is accepted. An option you leave out follows the project’s dashboard setting.One option is new. v2 passes v2 options to the engine as they are, on top of the translated v1 options. Use it for what v1 could not express:
container and signal are set by the package and cannot be passed.
  • StreamPixelVoiceChat needs the stream: call StreamPixelApplication first. join() waits for the stream, and for a password that is still being typed.
  • The project must have chat switched on in the dashboard.
  • A room belongs to the project. A room name equal to the project ID is the project’s room; any other name is a room inside the project. A v2 room is not the v1 room of the same name.
  • getToken() throws. The engine obtains the room token when join() runs.
  • The classes of the Pixel Streaming library are not exported. Config, PixelStreaming, Application, the overlay classes and the settings panel are not part of the package. A page that built its own PixelStreaming object needs the v2 API.
  • pixelStreaming is a stand-in. The engine builds a new library object whenever it rebuilds the connection, so the package returns one stable object that forwards to the live one. Do not keep references to its inner objects across a reconnect.
  • Statistics. getStreamStats() returns the v1 keys that the library fills. Audio Bitrate (kbps), Audio codec and Players are present only when the library has a value for them.
  • The engine is not in your bundle. It is loaded from Streampixel’s servers when the stream starts. A page that must work without access to js.streampixel.io cannot use this package.

Move to the v2 API

The rest of this page maps v1 to v2, topic by topic. In each pair of code blocks, choose v1 or v2: your choice applies to every pair on the page. First replace the package:
@streampixel/ui draws the screens v1 drew by itself (see The screens v1 drew for you). Without a bundler, the core is also available from a script tag (https://js.streampixel.io/v2/loader.js, global StreampixelSDK); @streampixel/ui and chat are npm only.

Start a stream

To start on a button press:
v1 examples called disconnect() in the effect cleanup. In v2 pass a signal and abort it: without it, React StrictMode’s double effect (or a fast unmount) leaves a session streaming in the background. Quick start has a full hook.

Settings

What you leave out comes from the project’s dashboard settings. An option name v2 does not know is ignored with a console warning, so a v1 name left in place does not fail silently. Every v2 option is on Options.

Messages to and from your application

The method names of Epic’s Pixel Streaming library that your v1 code calls are on the v2 stream object. The shortest move changes only the object in front of them:
Coming from Epic’s Pixel Streaming library? Its method names work on the stream object too: emitUIInteraction(), emitConsoleCommand() and addResponseEventListener(). They are the same calls as send(), consoleCommand() and on('ueMessage'). Use whichever you know. See Talk to your Unreal app.
The same three lines with the SDK’s own names:
With either set of names, sending returns false when the message was not handed to the stream (before the video is up, while reconnecting, after the end). Nothing is queued. See Talk to your Unreal app.

The screens v1 drew for you

v1 drew its own connecting screen, queue text, idle countdown, text box for phones and “Disconnected” screen. The v2 core draws only the video. A page moved to the core alone has no idle warning, no end message, no “Click to start” when the browser blocks autoplay, and text fields in the application stop working on phones. The simplest move is mountUI(stream, { container }) from @streampixel/ui, which draws all of these: CSS written for v1’s elements (#afkOverlay, #connectOverlay, #infoOverlay, #uiFeatures) matches nothing in v2; @streampixel/ui uses spx-* class names. appStream.showDisconnectOverlay(), appStream.showTextOverlay() and appStream.statsPanel have no v2 call. To draw a screen yourself, switch that part off and use the events:

Loading, queue, reconnecting, ended

All listeners added with stream.on() are removed when the session ends. Do not keep a reference to the <video> element or to stream.pixelStreaming: v2 replaces both when it rebuilds the connection. Every state and event is on Events and states.

Idle warning

Text input on phones

v1 opened a text box by itself when the application asked for the keyboard. In v2, mountUI does it, or you do:

Controls

Every method is on Stream methods and properties.

Microphone and camera to the application

The microphone or camera must be allowed when the stream starts (media, or the dashboard). With it allowed, the browser asks for permission once the video is up, and setMicrophone(on) / setCamera(on) switch it afterwards.
Do not call unmuteMicrophone() or unmuteCamera() on stream.pixelStreaming: they make Epic’s library reconnect on its own, against the SDK.

Access

What your page does for each access setting:
Never put a project password in your page’s code: anyone can read it there.

Shared sessions

A shared session runs one application for several people: a host who controls it and viewers who watch.
hostStreamerId must be exactly the host’s stream.streamerId. In v2 that id is <id>_<projectId>, not the bare id. Porting streamerId: 'room1' to both sides gives a viewer that never joins. If both pages already agree on a room name, keep it like this:

Voice and text chat

See Voice chat.

Pixel Streaming names that work in v2

These names of Epic’s Pixel Streaming library are on the v2 stream object. They are equal to the SDK’s own names: use whichever you know.
Through addEventListener, webRtcDisconnected fires on every signalling drop, including the ones v2 recovers from by itself. A v1 handler that shows “Disconnected” on that event will show it during a reconnect that succeeds. Drive your screens from the state event.

What has no equivalent

Behaviour that changed

Check list

  • Access setting of each project checked in the dashboard
  • Allowed-domains list checked against the exact origins of your pages, and tested
  • Content-Security-Policy updated, if you have one
  • streampixelsdk@next installed; imports and code unchanged
  • What is different read against your page: disconnected handlers, a start that fails, overlay functions, minQP / maxQP
  • Relay: forceTurn: true if you depended on relay-only
  • Built and tested with your own project, on a phone and through a short network drop

Next steps

Quick start

A real page on the v2 API, in plain JavaScript and in React.

UI overlays

The screens @streampixel/ui draws, and how to replace one.

Options

Every option of Streampixel.create().

Stream methods and properties

Everything on the stream object.