Skip to main content
Beginner For anyone who can edit an HTML file. At the end, your Unreal app runs inside a page you wrote, and you know what each part of that page does.
Public beta. These pages describe version 2.0.0-beta.2 of @streampixel/web-sdk. Names and behaviour can still change before the stable 2.0.0 release. See the changelog.

What you build

One file, index.html. It shows:
  • your app’s video, filling the browser window;
  • one line of text that says what is happening: “Connecting…”, “In queue…”, or why the stream ended;
  • a few buttons that appear only when they are needed: start, sound, “still there?”, start again.
You install nothing. The page loads the Web SDK from Streampixel with one <script> tag.

Before you start

Build the page

1

Create the file

Make a new folder, for example my-stream. Inside it, create a file named index.html.
my-stream
index.html
Paste this code into the file and save it.
index.html
Change nothing yet. Use the copy button on the code block to copy the whole file.
Your folder has one file, index.html, with the code above in it.
2

Serve the folder

Open a terminal, go to the folder, and start a small web server. Pick the tool you have.
On Windows the command is py -m http.server 8000.
The terminal prints a line that starts with Serving HTTP on. Your page is at http://localhost:8000.
Leave this terminal open: the server runs until you stop it with Ctrl + C.
Why not double-click the file? The SDK needs a page served over https or from localhost. A file you open by double-click has an address that starts with file://, which is neither.
3

Open the page

In your browser, go to the address from the previous step.
The page is black, with one line at the top left: Paste your project ID into PROJECT_ID, then reload this page. That line comes from the script in your file, so the file is served and its code runs.
4

Copy your project ID

The tells the SDK which app to stream.
  1. Sign in at dashboard.streampixel.io and open your project.
  2. Click the Project ID button to copy it.
You can also read it from the address bar: it is the last part of the project page’s address. See Finding your user and project IDs.
You have a string of letters and digits, such as 0123456789abcdef01234567 (a made-up example: no project has this ID).
5

Paste it into the file

In index.html, find line 43 and replace YOUR_PROJECT_ID with your ID. Keep the quotes.
index.html
Save the file and reload the page in your browser.
The line at the top left changes to Loading…, then Connecting…. It may show In queue… for a while. Then the line disappears and your app’s video fills the window. The first start can take some time: Streampixel is starting your app on a GPU server.
6

Use your app

Click on the video and use your mouse and keyboard as you would in the app itself. Then press Turn sound on.
Your app reacts to your input, and you hear its sound.
You have a working page. When you are done, close the browser tab and stop the server with Ctrl + C.

What the line at the top tells you

How the page works

The file has five parts. You can change any of them.

1. A box for the video

index.html
The SDK puts the video inside this element, which is called the . The container needs a width and a height. In this page the CSS rule #stream { width: 100%; height: 100%; } makes it fill the window. To show the stream in part of a page, give the box another size.

2. The SDK

index.html
This script defines StreampixelSDK. It is small: the code that runs the stream is downloaded later, when your page starts a stream. How it works explains why.

3. Starting the stream

index.html
Streampixel.create() needs two things: your project ID (the option is named appId) and the container. It gives back the stream object, which the rest of the script uses. When the stream cannot start, create() throws an error instead. The explain() function in the file turns that error into a sentence for the status line.

4. Showing what happens

index.html
A stream is always in one . stream.state.kind is its name: connecting, queued, streaming, ended and a few more. The SDK calls render() each time the state changes, and render() writes the line at the top and shows or hides the buttons.

5. What the viewer needs from your page

The SDK draws the video and nothing else. Everything a viewer clicks is yours to draw. This page has the smallest set that works:
A page for real viewers needs a few more things:
  • a loading screen with your project’s logo and loading texts;
  • a text field on phones, when your app asks the viewer to type;
  • a Save button for files and an Open button for links that your app sends, on phones and tablets;
  • a notice when the viewer’s network forces a slower connection;
  • controls such as fullscreen.
The @streampixel/ui package draws all of them, and the five above, with one line of code. It needs npm: see the Quick start. To draw them yourself, see the Cookbook.

If something goes wrong

Read the line at the top of your page first. Then find it here.
The browser is showing the file as it was before your change. Save the file, then reload the page. Check that you edited the index.html in the folder you are serving.
The text between the quotes is not a project ID. Copy the ID again with the Project ID button in the dashboard. Check for a missing character or a space.
The ID has the right form, and no project has it. Copy it again from the dashboard.
The project exists and cannot stream right now. In the dashboard, check that the project is switched on and that it has an active build. The project’s share link is a quick test: when your app plays there, the project is ready.
The browser could not load https://js.streampixel.io/v2/loader.js. Check your internet connection. Switch off any ad blocker for this page and reload.
The SDK could not download the code that runs the stream. The word in brackets says why:For the other reasons, see Errors and disconnects.
The browser could not reach Streampixel’s servers, or got no answer in time. Check your connection and press Start again.
No GPU is free right now. The stream starts by itself when one becomes free: keep the page open.
Streams start muted. Press Turn sound on.
Your project is password-protected. Type the project’s password and press Continue. The password is set in the project’s settings in the dashboard: see Security and access control.
Your project uses single sign-on. After you sign in, the browser comes back to your page and the page starts the stream. See Access for how sign-in works.
If your project has an allowed-domains list, the address of your page must be on it. That includes the address you use on your own computer, for example http://localhost:8000. See The allowed-domains list.
Nobody used the app for the idle time, and nobody pressed Still there? Click to stay. Press Start again.
The network you are on does not let the video through. Try another network, for example a phone hotspot. For what a network must allow, see Network requirements.
Every way a session can end has a code and a sentence. See How a session ends.
To see more detail, open your browser’s developer tools (F12, or Cmd + Option + I on a Mac) and look at the Console tab. The SDK writes its warnings there.

Next steps

How it works

What happened between your page and your app, step by step.

Build a real page

npm, the ready-made screens, React.

Talk to your Unreal app

Send messages to your app and receive its answers.

Options

Everything create() accepts.