The page the recipes start from
Every recipe adds a few elements and a few lines to this page. Two recipes replacemain.js and say so.
- Keep
#streamempty. The SDK adds and removes its own element there. Your elements go in#player, next to it. - The recipes leave out the
tryandcatcharoundcreate(). What it rejects with is on Errors and disconnects. - No build tools? Load
https://js.streampixel.io/v2/loader.jswith a script tag, and replace theimportline withconst { Streampixel } = StreampixelSDK;. See Installation.
Your own loading screen
Intermediate Shows a message until the video plays, and again whenever the stream is not playing. Uses the project’s own loading texts and logo from the dashboard.Add inside #player
Add to main.js
You see “Connecting…”, then your project’s loading texts, then the video. Stop your network for a few seconds and the screen comes back with “Reconnecting…”.
A queue position display
Intermediate Tells a waiting viewer where they are. The server sends a new position as the queue moves.Add inside #player
Add to main.js
When no GPU is free, the banner shows the viewer’s place in the queue and follows it as the queue moves. It disappears when the application starts.
A reconnecting banner
Advanced A small banner with a countdown, instead of a full loading screen. It suits a reconnect: the last picture often stays on screen while the SDK restores the connection.Add inside #player
Add to main.js
When the SDK gives up, the state is
ended and the banner hides. Show the end message: see Start again after the session ends. What leads to each state is on Events and states.
An idle warning
Intermediate Warns the viewer before an idle session is closed, and lets them stay.Add inside #player
Add to main.js
Leave the stream alone for the project’s idle time. The warning counts down. Press the button and the stream continues. Let it run out and the session ends with
endKind: 'afk'.stream.keepAlive() from your page from time to time. The application can do the same with a heartbeat message: see Talk to your Unreal app.
A React hook
Intermediate Creates a stream when a component mounts and removes it when the component unmounts. It is safe under<StrictMode> and on fast route changes.
React can run a component’s cleanup before create() has resolved. A cleanup that only calls stream.destroy() then has nothing to destroy, and the session that create() starts afterwards streams with nobody watching. The signal option solves it: abort before create() resolves and nothing starts; abort afterwards and the stream is destroyed.
use-streampixel.ts
Stream.tsx
- Keep the container
<div>empty in your JSX. The SDK adds and removes its own child there. - Use the returned
streamfor everything else on this page:stream?.on(...)in an effect of your own,stream?.send(...)in a click handler. - Other frameworks: the same pattern works wherever a component has a cleanup step. Create on mount, pass a
signal, abort it on unmount.
Start on a button press
Beginner Starts the stream only when the viewer asks for it. No session, and so no GPU, is used before the click.Add inside #player
main.js (replaces the one above)
The page loads with a button and no video. After the click the stream connects. With the warm-up, the engine is already in the browser, so
create() does not have to download it first.A stats readout
Intermediate Shows the viewer, or you, what the stream is doing. Thestats event fires every second while the video is up.
Add inside #player
Add to main.js
StreamStats. For a deeper look at a bad session, see Diagnostics.
Saving a screenshot
Beginner Saves the current video frame as a PNG, from your own button and when the application asks.Add inside #player
Add to main.js
pixelstream_screenshot.png.
Start again after the session ends
Intermediateended is final: a stream cannot be connected again. To start again, destroy it and create a new one.
Add inside #player
main.js (replaces the one above)
@streampixel/ui, pass the function instead: mountUI(stream, { container, onRestart: start }). Destroy the UI before the stream.
Pass the page address to your application
Beginner Sends the query parameters of your page’s address to the application when it starts, as a share link does.main.js
Open your page as
https://your-site.example/viewer?unit=A-12&lang=fr. Shortly after the first frame, the application receives one message: { "unit": "A-12", "lang": "fr" }. Every value is a string.stream.send() or stream.emitUIInteraction(): see Talk to your Unreal app.
Link a session to your own user
Advanced Stores the ids of each session with your own user, so that you can find a viewer’s session in your Streampixel analytics.Add to main.js, directly after create()
More recipes on other pages
Sound, resolution, fullscreen
A sound button, a resolution picker, a fullscreen button, “Click to start”, text input for phones.
Messages, files and links
Send when the stream is ready, a Save button for files, a button for links.
Your own password form
The complete form, with lockouts.
Voice and text chat
Join the project’s chat room from your page.
Next steps
Reliability
One level up: what the SDK does when things go wrong, with the real timings.
Events and states
Every state and event these recipes use, with payloads.
Stream API reference
Every method and property of the stream object.
Options reference
Every option of
create().