Skip to main content
Advanced For developers who build their own interface around a stream. Each recipe is a small, complete piece that you can copy. Each one says which level it suits.

The page the recipes start from

Every recipe adds a few elements and a few lines to this page. Two recipes replace main.js and say so.
Three things the recipes rely on:
  • Keep #stream empty. The SDK adds and removes its own element there. Your elements go in #player, next to it.
  • The recipes leave out the try and catch around create(). What it rejects with is on Errors and disconnects.
  • No build tools? Load https://js.streampixel.io/v2/loader.js with a script tag, and replace the import line with const { Streampixel } = StreampixelSDK;. See Installation.
You can mix your own parts with the ready-made ones. Mount @streampixel/ui and switch off only what you replace: mountUI(stream, { container, loading: false }) for the loading recipes, afk: false for the idle warning.

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…”.
This screen hides itself in awaitingPlay and awaitingPassword. Those states need their own controls: a “Click to start” button and a password form. Without your own, mount @streampixel/ui with loading: false.

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'.
While you test, shorten the wait: afk: { timeoutSec: 30 } in the options. Your code can make the idle time shorter than the project’s setting, never longer.
If the viewer watches without clicking, for example during a video inside the application, call 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 stream for 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. The stats event fires every second while the video is up.
Add inside #player
Add to main.js
Every field is explained in 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
The picture is the video frame only. Your own buttons and overlays are not in it. Without the second listener, the SDK saves an application’s request as pixelstream_screenshot.png.

Start again after the session ends

Intermediate ended 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)
destroy() on a live stream fires ended too, with endKind: 'user'. A page that restarts on every ended would restart for ever. Check endKind, as above.
With @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.
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.
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.
To send something later, when the viewer presses a button, use stream.send() or stream.emitUIInteraction(): see Talk to your Unreal app. 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().