Skip to main content
Intermediate For web developers who use npm. After this page you have a page that starts your stream, shows the right screen for every situation, reacts to what the stream does, and cleans up after itself.
No build step? Your first stream does the same in one HTML file with a script tag.

Before you start

No build yet? You can run your page against Unreal on your own machine: see Test locally.

Build the page

1

Install the two packages

The SDK:
The ready-made screens:
Your package.json lists @streampixel/web-sdk and @streampixel/ui.
2

Give the video a box

The SDK puts the video inside an element of your page, the container. Give it a width and a height.
index.html
The size is yours to choose: the full window, a 16:9 box in an article, a panel next to a form. See The container for the rules.
3

Create the stream and mount the screens

main.ts
Streampixel.create() starts the stream. mountUI() draws everything a viewer needs around the video: the loading screen, the password form, “Click to start”, the idle warning, the end message and more.
Run your dev server and open the page. You see your project’s loading screen, then your app. A control bar at the bottom right has sound, stream information and fullscreen.
4

React to what the stream does

The stream is always in one state. Listen to state for your own logic: analytics, a “live” badge, showing your own controls. Add this inside start(), after mountUI().
main.ts
Attach your listeners right after await Streampixel.create(...): connecting starts one moment later, so you see every state. All states and events are in Events and states.
5

Talk to your Unreal app

Send a message once the video is up, and listen for what your app sends back. This also goes inside start().
main.ts
send() returns false when the message was not sent: before the video is up, while reconnecting, after the end. Nothing is queued. The state streaming can come again after a reconnect, so send only what is safe to repeat. For data your app needs once at its start, use the launchParams option.
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.
6

Clean up

When the stream should go away (a closed dialog, a route change), destroy the screens first, then the stream.
main.ts
stream.destroy() ends the session if it is still live, removes the video and drops every listener. It is safe to call more than once. Keep stream and ui where your teardown code can reach them: the complete page below keeps both in variables outside start().

The complete page

The steps above, with error handling and a “Start again” button. Pick your version.
my-site
index.html
src
main.ts
package.json
This is the layout of a Vite project. Any bundler that resolves npm packages works.
What it adds to the steps:

What create() does

create() does four things before it resolves:
  1. Downloads and verifies the engine, the code that runs the stream.
  2. Looks the project up on the Streampixel platform: is it online, and how do viewers get in.
  3. Asks the platform for a ticket, a short-lived credential for one session. A password or single sign-on is checked here.
  4. Resolves with the stream object. Connecting starts one moment later.
On a password-protected project, create() resolves before step 3, with the stream in the state awaitingPassword. Nothing has started yet. @streampixel/ui shows the password form. See Access. How it works follows these steps one by one.

When create() rejects

Every kind and reason is listed in Errors and disconnects.

The container

container must be an element, not a selector string. The SDK adds one element of its own to it and puts the video inside.
How the video is fitted depends on the project’s resolution mode in the dashboard, or on the resolution.mode option.For dynamic and crop, give the container both a width and a height: a container that has no size yet is measured as the browser window.

React

React needs one thing done right: cancelling.
  • In development under <StrictMode>, React runs an effect, its cleanup, and the effect again when a component mounts.
  • In production, a fast route change unmounts a component just after it mounted.
In both cases the cleanup runs before create() has resolved. A cleanup that only calls stream.destroy() has no stream to destroy yet, and that create() then resolves into a session that nobody holds: a GPU session that streams unseen. Pass an AbortSignal and abort it in the cleanup. Aborting before create() resolves rejects it with an AbortError and starts nothing. Aborting later destroys the stream.
Without signal, React’s StrictMode starts two sessions in development, and a quick route change in production can leave one running.
If you draw your own screens instead of mounting @streampixel/ui, this hook gives your components the stream and its state:
useStreampixel.ts
Stream.tsx
The cleanup unsubscribes before it aborts: destroy() announces ended before it drops the listeners, and a state update on a component that is going away is not wanted. A fuller hook is in the Cookbook.

Starting again

A session that has ended cannot be restarted: ended is final, and it removes every listener. There is no connect() or reconnect() on a stream. To start again (a retry button, a route change), destroy the old stream and create a new one.
destroy() on a live stream fires ended (code 1000, endKind: 'user') before it drops the listeners. If your code starts a new stream when ended fires, check endKind first, or unsubscribe before you destroy.

Without the ready-made screens

@streampixel/ui is optional. Without it, the SDK draws the video and nothing else, and your page must give the viewer: Your first stream is a small page that does this by hand. The Cookbook has a recipe for each piece. You can also keep most of the ready-made screens and replace one.

Next steps

Ready-made screens

What each screen shows, and how to switch off, restyle or replace one.

Talk to your Unreal app

Messages, console commands, launch parameters, files and links.

Controls and input

Sound, resolution, fullscreen, mouse, keyboard, touch.

Events and states

One level up: build your own screens on the state machine.