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

# Web SDK overview

> The Streampixel Web SDK puts your Unreal Engine app inside your own web page and gives your code one stream object to control it. What it is, when to use it instead of a share link or an iframe, and where to start.

Beginner For everyone who is new to the Web SDK. After this page you know what the SDK is, whether you need it, and which page to read next.

> [!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).

Your Unreal Engine app runs on Streampixel's GPU servers. The **Web SDK** is a JavaScript library that shows that app inside a page of your own website, as live video that reacts to the viewer's mouse, keyboard and touch. Your code gets one `stream` object: it tells you what the stream is doing, and it lets you talk to your app.

```ts theme={"dark"}
import { Streampixel } from '@streampixel/web-sdk';

const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',                      // which app
  container: document.getElementById('stream')!, // where the video goes
});

stream.on('state', (state) => console.log(state.kind)); // connecting, queued, streaming, ended …
stream.send({ action: 'openDoor' });                    // a message to your Unreal app
```

## Choose your path

> [card] [I am new here](https://docs.streampixel.io/resources/web-sdk-v2/first-stream.md)
>
> **Beginner.** See your app in your own page in five minutes: one HTML file, nothing to install.

> [card] [I am building a page](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md)
>
> **Intermediate.** npm, the ready-made screens, React, talking to your app.

> [card] [I am going to production](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md)
>
> **Advanced.** States and events, access, errors, shared sessions, recipes.

> [card] [I want to know exactly what happens](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> **Expert.** How the engine loads and updates, recovery timings, diagnostics.

> [card] [I have a page on the v1 SDK](https://docs.streampixel.io/resources/web-sdk-v2/migration.md)
>
> **Upgrading.** Keep your code with the compatibility package, or move to the v2 API.

> [card] [I am looking something up](https://docs.streampixel.io/resources/web-sdk-v2/options.md)
>
> **Reference.** Every option, method, event and error.

Not sure how the pieces fit together? [How it works](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md) explains them step by step, without code.

## Do you need the Web SDK?

Streampixel has three ways to put a stream in front of a viewer. Use the simplest one that does what you need.

| | Share link | Iframe | Web SDK |
| - | - | - | - |
| What it is | Streampixel's own page for your project | That same page, in a frame on your page | The stream itself, inside your page |
| What you write | Nothing | One `<iframe>` tag | JavaScript |
| The screens the viewer sees (loading, password, controls) | Streampixel's, with your branding | Streampixel's, with your branding | Yours, or the ready-made ones from `@streampixel/ui` |
| Talking to your Unreal app | Values in the link's address, once at the start | Messages through the frame (`postMessage`) | Method calls on the `stream` object |
| Knowing what the stream is doing | No | Messages from the frame | Typed states, events and errors in your code |
| Read more | [Share and embed](https://docs.streampixel.io/resources/quick-start-guide/sharing-and-embedding.md) | [Iframe integration](https://docs.streampixel.io/resources/iframe-integration/overview.md) | These pages |

> [accordion] Use the share link when…
>
> You want to send people a link, and Streampixel's page is all they need. There is nothing to build.

> [accordion] Use an iframe when…
>
> You want the stream on your own site with almost no code, and Streampixel's screens are fine. Your page can still send commands and receive messages through the frame.

> [accordion] Use the Web SDK when…
>
> * You want your own screens and controls: your own loading screen, your own buttons, your own layout.
> * Your page and your Unreal app talk to each other a lot, and you want plain method calls and events for it.
> * Your code must know exactly what the stream is doing: queued, reconnecting, why it ended.
> * You build with a framework such as React and want the stream to be a component of your app.

## What you need

| You need | Detail |
| - | - |
| A Streampixel project | With an uploaded build, and switched on. No project yet? Start with the [Quickstart](https://docs.streampixel.io/resources/get-started/quickstart.md). |
| Its project ID | The SDK option is named `appId`. See [Finding your user and project IDs](https://docs.streampixel.io/resources/api-reference/finding-your-user-and-project-ids.md). |
| A page served over `https`, or from `localhost` | The SDK does not start on a plain `http` site. |
| A browser with WebRTC | The technology browsers use for live video. |

Two things to check if they apply to you:

* **Your site sends a Content-Security-Policy header.** Allow the SDK's hosts: see [Content-Security-Policy](https://docs.streampixel.io/resources/web-sdk-v2/installation.md#content-security-policy).
* **Your project has an allowed-domains list.** The address of your page must be on it: see [The allowed-domains list](https://docs.streampixel.io/resources/web-sdk-v2/migration.md#the-allowed-domains-list).

## What is in the box

| Package | What it is |
| - | - |
| `@streampixel/web-sdk` | The SDK. It draws the video and nothing else. |
| `@streampixel/web-sdk/voice` | Voice, text and video chat, for projects with chat switched on. Part of the same package, loaded only by pages that import it. |
| `@streampixel/ui` | Optional. The screens around the video: loading, password, "Click to start", idle warning, text input for phones, controls, end message. |

Without a build step, one `<script>` tag gives you the SDK with the same API: see [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md).

> [accordion] What the SDK does for you
>
> * **Access.** It follows the project's access setting in the dashboard: public, password, or single sign-on. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md).
> * **One state.** `stream.state` always says what the stream is doing, and the `state` event fires on every change.
> * **Recovery.** It reconnects by itself when the connection drops, and starts one fresh session by itself when no video arrives. See [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md).
> * **Plain-language endings.** When a session ends, your code gets a code, a kind and a sentence you can show the viewer.
> * **Epic's names work too.** If you know Epic's Pixel Streaming library, `emitUIInteraction()`, `emitConsoleCommand()` and `addResponseEventListener()` are on the stream object. See [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md).

> [accordion] How the SDK stays up to date
>
> The package you install is a small **loader**. The **engine**, the code that runs the stream, is downloaded from Streampixel's servers when your page starts a stream. Fixes reach your site without a new install or deploy.
>
> The engine is verified before it runs, and there is no copy of it in the package: if it cannot be loaded, `create()` rejects with `EngineLoadError`. See [How it works](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md#the-sdk-is-a-loader-and-an-engine) and [The engine and its updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md).

> [accordion] What the SDK reports to Streampixel
>
> The SDK reports the session's lifecycle and connection quality to Streampixel's own telemetry service. These reports are what the session pages of your dashboard show. There are no third-party trackers, no analytics SDKs and no cookies in the package. Passwords, tickets and the messages between your page and your app are never sent. See [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md).

## Next steps

> [card] [Your first stream](https://docs.streampixel.io/resources/web-sdk-v2/first-stream.md)
>
> One HTML file, five minutes.

> [card] [How it works](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md)
>
> Your page, the SDK, the platform and the GPU server, step by step.

> [card] [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md)
>
> npm or a script tag, TypeScript, frameworks.

> [card] [FAQ](https://docs.streampixel.io/resources/web-sdk-v2/faq.md)
>
> Short answers to common questions.


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