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.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.
index.html
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 Attach your listeners right after
state for your own logic: analytics, a “live” badge, showing your own controls. Add this inside start(), after mountUI().main.ts
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.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.- Plain TypeScript
- React
my-site
index.html
src
main.ts
package.json
What create() does
create() does four things before it resolves:
- Downloads and verifies the engine, the code that runs the stream.
- Looks the project up on the Streampixel platform: is it online, and how do viewers get in.
- Asks the platform for a ticket, a short-lived credential for one session. A password or single sign-on is checked here.
- Resolves with the
streamobject. Connecting starts one moment later.
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: fixed, dynamic and crop
How the video is fitted: fixed, dynamic and crop
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.
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.
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
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.