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.StreamPixelApplication function of the streampixelsdk package. v2 is @streampixel/web-sdk.
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: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
- Path 1: keep your code
- Path 2: move to the v2 API
1
Install the compatibility package
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.What stays the same
What stays the same
StreamPixelApplication(settings) resolves to the same five objects.Also exported, with their v1 names:
StreamPixelVoiceChat: the same constructor and methods.Flags,NumericParameters,TextParametersandControlSchemeType: the setting names of the Pixel Streaming library, as plain values.
#afkOverlay { display: none }, still hide the screen that stands for it.Options, and the new v2 option
Options, and the new v2 option
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.Voice and text chat
Voice and text chat
StreamPixelVoiceChatneeds the stream: callStreamPixelApplicationfirst.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 whenjoin()runs.
What the package cannot cover
What the package cannot cover
- 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 ownPixelStreamingobject needs the v2 API. pixelStreamingis 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 codecandPlayersare 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.iocannot 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:
React: pass a signal instead of calling disconnect()
React: pass a signal instead of calling disconnect()
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 v2stream object. The shortest move changes only the object in front of them:
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 ismountUI(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
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.
Access
What your page does for each access setting: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 v2stream 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
- Path 1: keep your code
- Path 2: move to the v2 API
- 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@nextinstalled; imports and code unchanged - What is different read against your page:
disconnectedhandlers, a start that fails, overlay functions,minQP/maxQP - Relay:
forceTurn: trueif 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.