Skip to main content
All levels For anyone who needs to look up an option of Streampixel.create(): every option is here, with its type, its default and what it does.
Anything you leave out comes from the project’s settings in the dashboard. Set an option only when this page must differ from the dashboard.

All options at a glance

In TypeScript the whole object is the type StreampixelOptions:

Basics

string
required
The project ID from the dashboard. You can leave it out only on a page served from the project’s own verified custom domain: the SDK then finds the project by the page’s hostname.
HTMLElement
The element the video goes into. It must be an element, not a selector string, and it needs a width. The SDK adds one element of its own to it and puts the <video> inside. See Quick start for the sizing rules.Leave it out to start without a video on the page, and call stream.attach(element) later.
AbortSignal
Cancels the stream. Aborting before create() resolves rejects it with an AbortError and leaves nothing running. Aborting later destroys the stream.Pass the signal of an AbortController in a React effect and abort it in the cleanup. Without it, a fast unmount or the double effect of React StrictMode leaves a session streaming in the background.
'standard' | 'minimal'
default:"'standard'"
What the SDK reports to Streampixel’s own telemetry service.
  • 'standard': the session’s lifecycle, WebRTC diagnostics, and a statistics row about once a minute.
  • 'minimal': the session’s lifecycle only.
There is no “off” value, and there are no third-party trackers. See Diagnostics.
The loading option of early pre-release builds was removed. Passing it logs a console warning and draws nothing. Use @streampixel/ui for the loading screen.

auth

How the viewer gets in. With the default, the SDK follows the project’s access setting in the dashboard. Each mode is explained on Access.
AuthOption
default:"{ mode: 'auto' }"
One object. mode chooses the path; the other fields belong to one mode each.
boolean
default:"true"
Password projects with auth 'auto'. After a correct password, the SDK keeps it for this browser tab only (sessionStorage, per project) and tries it silently on the next create(), so a reload does not ask again. false turns this off.
Errors that create() rejects with are listed on Errors and disconnects.

shared

SharedMode
A shared session: one app, one host who controls it, and viewers who watch. Leave it out for a private session (the default). See Shared sessions.

dev: test locally

object
Streams from Unreal on your own machine instead of an uploaded build. For development only: viewers of a released app use the normal options.
  • appId is required with dev.
  • dev cannot be combined with shared or with auth: { mode: 'ticket' }. Both are refused with a TypeError.
  • An unknown or expired session rejects with AuthError kind dev-session-not-found or dev-session-expired.
How to start a session, how to connect Unreal, and what is different in a dev session are on Test locally.

Video

object
The video codec. Both fields default to the project’s codec settings.
object
The size of the stream. All fields default to the project’s resolution settings. None of them can go above the project’s maximum stream quality: see Dashboard limits.
Resolution is one of these strings, or an object with two numbers:
In the object form, both numbers must be at least 64. Odd values are rounded down to even ones. A value that is not usable is ignored, with a console warning.
object
Limits for the encoder’s bitrate, in kilobits per second. { min: 1_000, max: 20_000 } is 1 to 20 Mbps. Not set by default.
Bitrate is in kilobits per second, not bits per second. A value above 200,000 logs a console warning, because it looks like bits per second.

Input and media

object
Which input the app receives from the viewer. Each field defaults to the project’s dashboard setting.
object
Sends the viewer’s microphone or camera to the app. Each field defaults to the project’s dashboard setting.
A viewer of a shared session is watch-only. Mouse, keyboard, touch, gamepad, microphone and camera are off for a viewer, whatever these options say.
How these behave in a page is on Controls and input.

Session

object
Values for your Unreal app, for example { unit: 'A-12', lang: 'fr' }. The SDK sends them to the app once per started app, as one UI interaction, shortly after the first frame. They are sent again when the SDK recovers into a fresh session, because that is a new app process. A shared-session viewer does not send them.See Talk to your Unreal app.
object
The idle time.

engine

Which engine build runs the stream. The engine is downloaded from Streampixel’s servers when create() runs. It is never part of your bundle. See Engine and updates.
EngineOptions
default:"{ channel: 'stable' }"
stream.engineVersion tells you which engine is running. If the chosen engine cannot be loaded, create() rejects with EngineLoadError. There is no engine inside the npm package to fall back to.

advanced

For special cases. Leave these unset unless you know you need one, or support asks you to set one.
object

Flags the engine reads

All four are on by default. Set one to false to turn it off.
boolean
default:"true"
false stops the { type: 'isTouchDevice', value, os, device } message that the SDK sends to the app on every video start. See Hide / unhide touch controls.
boolean
default:"true"
false stops the SDK from running the project’s startup console commands. See Launch arguments and startup commands.
boolean
default:"true"
false stops the SDK from ending the session after 60 seconds in the background on phones and tablets.
boolean
default:"true"
false stops the SDK from entering VR by itself in a headset browser.

Dashboard limits

For the settings that cost GPU time or bandwidth, the dashboard is the upper limit. Your code can ask for less, never more. A value above the limit is lowered to it, with one warning in the browser console.

What create() checks

Mistakes in the options are reported before any network call.

Next steps

Stream methods and properties

Everything on the object that create() returns.

Errors and disconnects

What create() rejects with, and how a session ends.

Engine and updates

How the engine is loaded, verified and pinned.

FAQ

Short answers to common questions.