Skip to main content
All levels For anyone who needs to look up a call: Streampixel.create(), Streampixel.preload(), and every method and property of the stream object that create() returns.

All members at a glance

Streampixel (static)

Promise<Streampixel>
Starts a stream. It downloads and verifies the engine, looks the project up, asks the platform for a session ticket, and resolves with the stream object. Connecting starts one moment later, so listeners you attach right after await see every state and event.
Every error kind and reason is listed on Errors and disconnects.
Promise<{ source, version }>
Optional warm-up. It downloads and verifies the engine without starting a session, for example before the viewer presses Start. A later create() with the same values does not download it again.Rejects with EngineLoadError when the engine cannot be loaded.

Events

The stream object emits typed events. Every event and its payload is listed on Events and states.
() => void
Subscribes fn to an event. Returns the function that unsubscribes. In TypeScript, an event name that does not exist does not compile.The event names are state, session, progress, queue, stats, videoEncoderAvgQP, stalled, relayFallback, autoplayBlocked, afkWarning, osk, oskHide, ueMessage, openUrl, fileProgress, file, screenshot and ended.
void
Unsubscribes fn, by reference.
() => void
Subscribes to an event by any name. Use it for an event added by an engine that is newer than your installed package, and so not in its types yet. Returns the function that unsubscribes.
A listener that throws is logged to the console and does not affect the stream or other listeners. All listeners are removed when the session ends, after ended has fired.

Talking to your Unreal app

The stream object has two sets of names for messages: the SDK’s own, and the names of Epic’s Pixel Streaming library. They are the same calls. Use whichever you know. How to use them, with examples on the Unreal side, is on Talk to your Unreal app. That page also explains why the SDK has names of its own.
boolean
Sends a message to the app. The Unreal side receives it as a Pixel Streaming UI interaction. See JSON messaging.Returns true when the message was handed to the stream. Returns false when it was not sent: before the video is up, while reconnecting, and after the end. Nothing is queued: send it again once the state is streaming.
boolean
Sends a console command to the app. Returns false when it was not sent: in the same cases as send(), and when the app does not allow console commands. The app must be launched with -AllowPixelStreamingCommands.
void
Receives every message from the app, the same messages as on('ueMessage', fn). fn always gets the message as a string. An on('ueMessage') listener gets it as the app sent it, which is usually a JSON string.
void
Removes the listener that was added under name.
void
Answers an osk event with the text the viewer typed. The osk event fires when the app asks for the on-screen keyboard, for example on a phone.
Nothing is queued, so a message sent too early is lost. This helper sends at once when it can, and otherwise waits for the state streaming:

Messages the SDK acts on

Some messages from your app trigger built-in behaviour, the same as on the share page. They still reach your listeners.

Messages the SDK sends to your app

A shared-session viewer sends none of these, because one app serves the whole room. You can turn the first two off with advanced.flags.

Audio and playback

void
Starts playback when the browser blocked autoplay (the state is awaitingPlay). Call it from a click or tap handler. A press anywhere on the container also starts playback.
boolean
Read-only. Whether the sound is muted. Streams start muted: browsers require a user gesture before sound.
boolean
Mutes or unmutes. Returns the muted state now in effect. Before the video exists it returns true.
boolean
Flips mute. Returns true when the sound is now on.

Resolution and input

{ width, height } | null
Asks the app to render at this size. The size is lowered to the maximum (the resolution.max option, never above the project’s maximum stream quality), keeping the aspect ratio, and rounded to even numbers. It needs no console-command permission on the app.Returns the size that was sent, or null when nothing was sent: numbers under 64, no stream up yet, after the end, and always for a shared-session viewer (the size is the host’s).
  • A size asked for before the stream is up is remembered. It is applied when the stream starts, and after every reconnect.
  • In dynamic and crop modes the size is the new upper limit. The stream is fitted to the container under it.
string[]
Read-only. The project’s sizes up to its maximum stream quality, for a picker: '360p (640x360)', '480p (854x480)', '720p (1280x720)', '1080p (1920x1080)', '1440p (2560x1440)', '4K (3840x2160)'.
void
Switches hover mouse on or off. With hover mouse on, the app receives mouse movement without a button pressed.
void
Enters or leaves the WebXR session in a headset browser. It does nothing in a browser without immersive VR.
void
Tells the SDK that the viewer is still there. It restarts the idle timer, and cancels the countdown when one is showing.
Keys typed into your page’s own <input>, <textarea>, <select> and editable elements are not sent to the app. How input, sound and resolution behave in a page is on Controls and input.

Microphone and camera

Promise<boolean>
Turns the viewer’s microphone on or off while the stream is up. Resolves to whether the microphone is now live.
Promise<boolean>
The same for the viewer’s camera.
  • The microphone or camera must be allowed when the stream starts: the media option, or the project’s dashboard setting. Without that, the call resolves false and nothing is captured.
  • The first call may show the browser’s permission prompt. Call it from a click or tap.
  • A shared-session viewer always gets false.

Screenshots and diagnostics

string | null
A PNG data URL of the current frame. null before the first frame.
Promise<DiagnosticsSnapshot | null>
A snapshot of the video connection, for support requests. null when there is no connection. The network addresses in it are not shortened. See Diagnostics.

Identity and configuration

All of these are read-only.
StreamState
The current state. Switch on state.kind. See Events and states.
string
The project ID the platform resolved. It is the same as appId, or the project found for the page’s custom domain.
string
The streamer ID of this connection. The host of a shared session gives it to viewers. It changes when the SDK recovers into a fresh session. In a dev session it is the dev session id.
string
The same value as streamerId, under a second name.
string
The platform’s session ID of the session that is up. It changes when the SDK recovers into a fresh session. The session event announces each new pair of ids.
StreamServerConfig
The project’s stream settings for this session, branding included, for your own loading screen or overlays. Before a password is accepted it holds the branding only.
The field names are the platform’s own, letter for letter. A field is absent when the platform did not send it, and a newer platform may send more.
string | undefined
Present only when the project has chat switched on. Used by voice chat.
string
The version of the engine running this stream. It can be newer or older than the package you installed.
'cdn'
How the engine was loaded. Always 'cdn' in the published package.

Password, moving and ending

Promise<void>
Answers the awaitingPassword state with what the viewer typed. See Access.
  • A right password: the stream starts.
  • A wrong password, or too many attempts: the promise resolves, and the state is awaitingPassword again with wrong, or with locked and retryAfterSec.
  • A network error, or a project that went offline: the promise rejects with AuthError. The state stays awaitingPassword.
  • Called in any other state, or while a check is running: it rejects with Error. An empty password rejects with TypeError.
void
Moves the video into another element. Use it when you created the stream without a container. The element needs a height of its own. In dynamic and crop modes the stream is then sized to that element.
void
Ends the session on purpose and removes the video. It never reconnects. ended fires with code 1000 and endKind: 'user'.
void
Does what disconnect() does if the session is still live, and then drops every listener. It is safe to call more than once. Call it before you create another stream in the same container, and when your component unmounts.
destroy() on a live stream fires ended (code 1000, endKind: 'user') before it drops the listeners. If your code restarts the stream on ended, check endKind first, or unsubscribe before you destroy.
A stream that has ended cannot be started again: there is no connect() or reconnect(). Destroy it and call create() again:

Pixel Streaming object and events

For code written against Epic’s Pixel Streaming library: Epic’s own object, and Epic’s events by their original names.
object | null
Read-only. Epic’s own PixelStreaming object for this connection. null when there is no connection.The SDK replaces this object when it rebuilds the connection. Read it each time you use it, and do not keep a reference to it. Do not call its reconnect(), unmuteMicrophone() or unmuteCamera(): the SDK owns reconnection and capture.
void
Subscribes to one of Epic’s events by its original name, for example webRtcConnected, playStream, afkWarningActivate or statsReceived. The SDK attaches your listener again each time it rebuilds the connection.
void
Removes a listener added with addEventListener().
Through addEventListener(), Epic’s webRtcDisconnected event fires on every signalling drop, including the ones the SDK recovers from by itself. To show a “Disconnected” message, use the state and ended events instead.

Tabs in the background

  • When the tab is hidden or loses focus, held keys and mouse buttons are released, so nothing stays stuck in the app.
  • On phones and tablets, a tab left in the background for 60 seconds ends the session (endKind: 'afk'), so a forgotten phone does not hold a GPU until the idle timeout. Turn this off with advanced.flags.backgroundDisconnect: false.

Package exports

What @streampixel/web-sdk exports besides the stream object: The script-tag build puts the same values on window.StreampixelSDK: Streampixel, AuthError, EngineLoadError, DisconnectCodes and SDK_VERSION. Voice chat is a separate entry, @streampixel/web-sdk/voice: see Voice chat.

Next steps

Options

Every option of Streampixel.create().

Events and states

Every state and every event, with its payload.

Talk to your Unreal app

Sending and receiving messages, with examples.

Errors and disconnects

What create() rejects with, and every end code.