> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first stream in 5 minutes

> Show your Unreal Engine app in a web page you wrote yourself: one HTML file, no build tools, with the Streampixel Web SDK.

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.

> [!NOTE]
>
> **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](https://docs.streampixel.io/resources/web-sdk-v2/changelog.md).

## 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

| You need | How to check |
| - | - |
| A Streampixel project that already streams | Open its share link, `https://share.streampixel.io/` followed by your project ID. If your app plays there, the project is ready. No project yet? Follow the [Quickstart](https://docs.streampixel.io/resources/get-started/quickstart.md) first. |
| A text editor | Any editor works: VS Code, Notepad, TextEdit in plain-text mode. |
| Python 3 or Node.js | You use one of them to serve the file. In a terminal, `python3 --version` or `node --version` prints a version number when it is installed. |

## 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.

```html index.html lines expandable highlight={43} theme={"dark"}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My first Streampixel stream</title>
    <style>
      html, body { margin: 0; height: 100%; background: #000; }

      /* The video goes in here. The box needs a width and a height. */
      #stream { width: 100%; height: 100%; }

      /* A small bar on top of the video: one line of text and a few buttons. */
      #bar {
        position: fixed; top: 12px; left: 12px; z-index: 10;
        display: flex; flex-wrap: wrap; gap: 8px; align-items: center;
        font: 14px system-ui, sans-serif; color: #fff;
      }
      #status:not(:empty) { background: rgba(0, 0, 0, 0.6); padding: 6px 10px; border-radius: 6px; }
      #bar button, #bar input { font: inherit; padding: 6px 10px; }
      [hidden] { display: none !important; }
    </style>
  </head>
  <body>
    <div id="stream"></div>

    <div id="bar">
      <span id="status">Loading…</span>
      <button id="start" hidden>Click to start</button>
      <button id="sound" hidden>Turn sound on</button>
      <button id="stay" hidden></button>
      <form id="password" hidden>
        <input id="password-input" type="password" placeholder="Password" required />
        <button>Continue</button>
      </form>
      <button id="again" hidden>Start again</button>
    </div>

    <!-- The Web SDK. It defines window.StreampixelSDK. -->
    <script src="https://js.streampixel.io/v2/loader.js"></script>

    <script>
      const PROJECT_ID = 'YOUR_PROJECT_ID'; // paste your project ID here

      async function main() {
        const byId = (id) => document.getElementById(id);
        const statusLine = byId('status');
        const startButton = byId('start');
        const soundButton = byId('sound');
        const stayButton = byId('stay');
        const passwordForm = byId('password');
        const passwordInput = byId('password-input');
        const againButton = byId('again');

        againButton.onclick = () => location.reload();

        if (PROJECT_ID === 'YOUR_PROJECT_ID') {
          statusLine.textContent = 'Paste your project ID into PROJECT_ID, then reload this page.';
          return;
        }
        if (!window.StreampixelSDK) {
          statusLine.textContent = 'The Streampixel script did not load. Check your connection and any ad blocker.';
          return;
        }
        const { Streampixel, AuthError, EngineLoadError } = StreampixelSDK;

        // 1. Start. create() gives you the stream object, or throws an error.
        let stream;
        try {
          stream = await Streampixel.create({
            appId: PROJECT_ID,
            container: byId('stream'),
          });
        } catch (err) {
          // A project with single sign-on: the browser is on its way to the sign-in page.
          if (err instanceof AuthError && err.kind === 'sso-required') return;
          statusLine.textContent = explain(err);
          againButton.hidden = false;
          return;
        }

        function explain(err) {
          if (err instanceof EngineLoadError) return `The player could not be loaded (${err.reason}).`;
          if (err instanceof AuthError) {
            if (err.kind === 'project-not-found') return 'No project has this ID. Check PROJECT_ID.';
            if (err.kind === 'project-offline') return 'This project is switched off or has no active build.';
            if (err.kind === 'network') return 'Could not reach Streampixel. Check your connection.';
            return `${err.kind}: ${err.message}`;
          }
          return String(err);
        }

        // 2. Show what the stream is doing. The SDK calls render() on every change.
        function render(state) {
          startButton.hidden = state.kind !== 'awaitingPlay';
          soundButton.hidden = state.kind !== 'streaming';
          passwordForm.hidden = state.kind !== 'awaitingPassword';
          againButton.hidden = state.kind !== 'ended';
          if (state.kind === 'ended') stayButton.hidden = true;

          switch (state.kind) {
            case 'idle':
            case 'connecting':
              statusLine.textContent = 'Connecting…';
              break;
            case 'queued':
              statusLine.textContent = state.position > 0 ? `In queue, position ${state.position}` : 'In queue…';
              break;
            case 'awaitingPassword':
              statusLine.textContent = state.hard ? 'Too many attempts. Try again later.'
                : state.locked ? 'Too many wrong attempts. Check the password and try again.'
                : state.wrong ? 'Wrong password. Try again.'
                : 'This stream needs a password.';
              break;
            case 'awaitingPlay':
              statusLine.textContent = 'Ready.';
              break;
            case 'streaming':
              statusLine.textContent = '';
              soundButton.textContent = stream.muted ? 'Turn sound on' : 'Turn sound off';
              break;
            case 'reconnecting':
              statusLine.textContent = 'Reconnecting…';
              break;
            case 'recovering':
              statusLine.textContent = 'Restarting the stream…';
              break;
            case 'ended':
              statusLine.textContent = state.message; // a sentence for the viewer
              break;
            default:
              statusLine.textContent = ''; // a newer engine may add a state
          }
        }
        render(stream.state);
        stream.on('state', render);

        // 3. The buttons.
        // The browser did not start the video by itself: start it from a click.
        startButton.onclick = () => stream.play();

        // Streams start without sound: browsers want a click before they play sound.
        soundButton.onclick = () => {
          soundButton.textContent = stream.toggleAudio() ? 'Turn sound off' : 'Turn sound on';
        };

        // A password-protected project: send what the viewer typed.
        passwordForm.onsubmit = (event) => {
          event.preventDefault();
          stream.submitPassword(passwordInput.value).catch((err) => {
            statusLine.textContent = err.message;
          });
          passwordInput.value = '';
        };

        // 4. The idle warning. Without a click on this button, an idle session ends.
        stream.on('afkWarning', (warning) => {
          if (warning.kind === 'countdown') {
            stayButton.hidden = false;
            stayButton.textContent = `Still there? Click to stay (${warning.secondsRemaining})`;
            stayButton.onclick = () => warning.dismiss();
          } else {
            stayButton.hidden = true;
          }
        });
      }

      main();
    </script>
  </body>
</html>
```

Change nothing yet. Use the copy button on the code block to copy the whole file.

> [!TIP]
>
> 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.

> [tab] Python
>
> ```bash theme={"dark"}
> cd my-stream
> python3 -m http.server 8000
> ```
>
> On Windows the command is `py -m http.server 8000`.
>
> > [!TIP]
> >
> > The terminal prints a line that starts with `Serving HTTP on`. Your page is at `http://localhost:8000`.

> [tab] Node.js
>
> ```bash theme={"dark"}
> cd my-stream
> npx serve
> ```
>
> The first time, `npx` asks before it downloads `serve`. Answer `y`.
>
> > [!TIP]
> >
> > The terminal prints the address of your page, usually `http://localhost:3000`.

Leave this terminal open: the server runs until you stop it with <kbd>Ctrl</kbd> + <kbd>C</kbd>.

> [!NOTE]
>
> **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.

> [!TIP]
>
> 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 project ID (The identifier of one project in your Streampixel account. The SDK option that takes it is called appId.) tells the SDK which app to stream.

1. Sign in at [dashboard.streampixel.io](https://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](https://docs.streampixel.io/resources/api-reference/finding-your-user-and-project-ids.md).

> [!TIP]
>
> 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.

```js index.html theme={"dark"}
const PROJECT_ID = 'YOUR_PROJECT_ID'; // [!code --]
const PROJECT_ID = '0123456789abcdef01234567'; // [!code ++]
```

Save the file and reload the page in your browser.

> [!TIP]
>
> 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**.

> [!TIP]
>
> 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 <kbd>Ctrl</kbd> + <kbd>C</kbd>.

## What the line at the top tells you

| You see | What is happening |
| - | - |
| **Loading…** | The page downloads the SDK's engine and asks Streampixel about your project. |
| **Connecting…** | Streampixel starts your app and the video connection is set up. |
| **In queue…** or **In queue, position 3** | No GPU is free right now. The stream starts by itself when one is. |
| **Ready.** and a **Click to start** button | The stream is up, and the browser did not start the video by itself. Click the button, or anywhere on the video. |
| Nothing, and a **Turn sound on** button | Your app is playing. |
| **Reconnecting…** | The connection dropped. The SDK is restoring it by itself. |
| **Restarting the stream…** | No video arrived. The SDK is starting one fresh session by itself. |
| A sentence and a **Start again** button | The stream could not start, or the session is over. The sentence says why. |

## How the page works

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

### 1. A box for the video

```html index.html lines focus={2} theme={"dark"}
<body>
  <div id="stream"></div>
```

The SDK puts the video inside this element, which is called the container (The HTML element you give to the SDK. The SDK adds the video inside it and nothing else.). 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

```html index.html theme={"dark"}
<script src="https://js.streampixel.io/v2/loader.js"></script>
```

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](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md) explains why.

### 3. Starting the stream

```js index.html theme={"dark"}
stream = await Streampixel.create({
  appId: PROJECT_ID,
  container: byId('stream'),
});
```

`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

```js index.html theme={"dark"}
render(stream.state);
stream.on('state', render);
```

A stream is always in one state (What the stream is doing right now, for example connecting, queued, streaming or ended. Read it from stream.state.). `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:

| In the page | Why it is needed | What it calls |
| - | - | - |
| **Click to start** | A browser can refuse to start a video without a click. The state is then `awaitingPlay`. | `stream.play()` |
| **Turn sound on** | Streams start muted: browsers want a click before they play sound. | `stream.toggleAudio()` |
| **Still there? Click to stay** | After a time without input, a countdown starts. If nobody answers it, the session ends. The time comes from your project's settings, or is 600 seconds. | `warning.dismiss()` from the `afkWarning` event |
| The password field | A password-protected project starts nothing until the viewer gives the right password. The state is `awaitingPassword`. | `stream.submitPassword()` |
| **Start again** | A session that has ended cannot be restarted. Reloading the page starts a new one. | `location.reload()` |

> [accordion] What this page leaves out
>
> 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](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md). To draw them yourself, see the [Cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md).

## If something goes wrong

Read the line at the top of your page first. Then find it here.

> [accordion] The line still says: Paste your project ID into PROJECT\_ID
>
> 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.

> [accordion] server: Invalid project id
>
> 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.

> [accordion] No project has this ID
>
> The ID has the right form, and no project has it. Copy it again from the dashboard.

> [accordion] This project is switched off or has no active build
>
> 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.

> [accordion] The page stays on Loading… or says the Streampixel script did not load
>
> 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.

> [accordion] The player could not be loaded (…)
>
> The SDK could not download the code that runs the stream. The word in brackets says why:
>
> | In brackets | What to do |
> | - | - |
> | `no-webcrypto` | The page is not served over `https` or from `localhost`. Use the address `http://localhost:…` from the "Serve the folder" step, not your computer's network address. |
> | `manifest-unavailable`, `engine-blocked`, `engine-timeout` | Something between the browser and Streampixel blocks the download: no connection, a firewall, an ad blocker. Reload, or try another network. |
>
> For the other reasons, see [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md).

> [accordion] Could not reach Streampixel
>
> The browser could not reach Streampixel's servers, or got no answer in time. Check your connection and press **Start again**.

> [accordion] It stays on In queue…
>
> No GPU is free right now. The stream starts by itself when one becomes free: keep the page open.

> [accordion] The video plays and there is no sound
>
> Streams start muted. Press **Turn sound on**.

> [accordion] A password field appears
>
> 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](https://docs.streampixel.io/resources/quick-start-guide/security-control.md).

> [accordion] The browser goes to a sign-in page
>
> 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](https://docs.streampixel.io/resources/web-sdk-v2/access.md) for how sign-in works.

> [accordion] It ends with: Access was refused
>
> 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](https://docs.streampixel.io/resources/web-sdk-v2/migration.md#the-allowed-domains-list).

> [accordion] It ends with: Disconnected due to inactivity
>
> Nobody used the app for the idle time, and nobody pressed **Still there? Click to stay**. Press **Start again**.

> [accordion] It ends with: This network blocks the connection the stream needs
>
> 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](https://docs.streampixel.io/resources/concepts/network-requirements.md).

> [accordion] It ends with another sentence
>
> Every way a session can end has a code and a sentence. See [How a session ends](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends).

> [!TIP]
>
> To see more detail, open your browser's developer tools (<kbd>F12</kbd>, or <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>I</kbd> on a Mac) and look at the **Console** tab. The SDK writes its warnings there.

## Next steps

> [card] [How it works](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md)
>
> What happened between your page and your app, step by step.

> [card] [Build a real page](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md)
>
> npm, the ready-made screens, React.

> [card] [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md)
>
> Send messages to your app and receive its answers.

> [card] [Options](https://docs.streampixel.io/resources/web-sdk-v2/options.md)
>
> Everything `create()` accepts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.