Streampixel.create(), Streampixel.preload(), and every method and property of the stream object that create() returns.
All members at a glance
Streampixel (static)
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.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.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.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.
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.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.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.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.Send as soon as the stream is ready
Send as soon as the stream is ready
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
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.Read-only. Whether the sound is muted. Streams start muted: browsers require a user gesture before sound.
Mutes or unmutes. Returns the muted state now in effect. Before the video exists it returns
true.Resolution and input
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
dynamicandcropmodes the size is the new upper limit. The stream is fitted to the container under it.
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)'.Switches hover mouse on or off. With hover mouse on, the app receives mouse movement without a button pressed.
Enters or leaves the WebXR session in a headset browser. It does nothing in a browser without immersive VR.
Tells the SDK that the viewer is still there. It restarts the idle timer, and cancels the countdown when one is showing.
<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
Turns the viewer’s microphone on or off while the stream is up. Resolves to whether the microphone is now live.
- The microphone or camera must be allowed when the stream starts: the
mediaoption, or the project’s dashboard setting. Without that, the call resolvesfalseand 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
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.The current state. Switch on
state.kind. See Events and states.The project ID the platform resolved. It is the same as
appId, or the project found for the page’s custom domain.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.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.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.
All fields of StreamServerConfig
All fields of StreamServerConfig
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.
Present only when the project has chat switched on. Used by voice chat.
The version of the engine running this stream. It can be newer or older than the package you installed.
Password, moving and ending
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
awaitingPasswordagain withwrong, or withlockedandretryAfterSec. - A network error, or a project that went offline: the promise rejects with
AuthError. The state staysawaitingPassword. - Called in any other state, or while a check is running: it rejects with
Error. An empty password rejects withTypeError.
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.Ends the session on purpose and removes the video. It never reconnects.
ended fires with code 1000 and endKind: 'user'.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.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.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.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.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 withadvanced.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.