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

# Installation

> Add the Streampixel Web SDK to your site: npm or a script tag, the packages, TypeScript, where to call it in React, Vue and Svelte, server-side rendering, and the Content-Security-Policy it needs.

Intermediate For web developers who add the SDK to a site. After this page the SDK is installed, your framework calls it at the right moment, and your Content-Security-Policy lets it through.

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

## Choose how to load the SDK

> [tab] npm package
>
> For a site with a build step: Vite, webpack, Next.js and others.
>
> ```bash npm theme={"dark"}
> npm install @streampixel/web-sdk
> ```
>
> ```bash yarn theme={"dark"}
> yarn add @streampixel/web-sdk
> ```
>
> ```bash pnpm theme={"dark"}
> pnpm add @streampixel/web-sdk
> ```
>
> ```ts theme={"dark"}
> import { Streampixel, AuthError, EngineLoadError, DisconnectCodes, SDK_VERSION } from '@streampixel/web-sdk';
> ```
>
> | Fact | Detail |
> | - | - |
> | Formats | ESM and CommonJS builds, with TypeScript types. |
> | Dependencies | None at run time. |
> | Server-side rendering | Importing the package touches no browser globals. See [Server-side rendering](#server-side-rendering). |

> [tab] Script tag
>
> For a page without a build step.
>
> ```html theme={"dark"}
> <script src="https://js.streampixel.io/v2/loader.js"></script>
> <script>
>   const { Streampixel, AuthError, EngineLoadError, DisconnectCodes, SDK_VERSION } = StreampixelSDK;
> </script>
> ```
>
> The script defines `window.StreampixelSDK`, with the same exports as the npm package.
>
> | Fact | Detail |
> | - | - |
> | Same API | `Streampixel.create()` and the `stream` object behave as in the npm package. |
> | npm only | Voice chat (`@streampixel/web-sdk/voice`) and the ready-made screens (`@streampixel/ui`) are not in the script-tag build. |
> | A complete page | [Your first stream](https://docs.streampixel.io/resources/web-sdk-v2/first-stream.md) is one HTML file built on this script. |

Both ways give you a small **loader**. The **engine**, the code that runs the stream, is not in the package and not in `loader.js`: `Streampixel.create()` downloads it from Streampixel's servers. Fixes reach your site without a new install. See [How it works](https://docs.streampixel.io/resources/web-sdk-v2/how-it-works.md#the-sdk-is-a-loader-and-an-engine).

## The packages

| Package | What it is | Needed |
| - | - | - |
| `@streampixel/web-sdk` | The SDK: `Streampixel`, `AuthError`, `EngineLoadError`, `DisconnectCodes`, `SDK_VERSION`, and the types. | Always |
| `@streampixel/web-sdk/voice` | Voice, text and video chat. It is a second entry point of the same package, so pages that do not import it never load it. See [Voice chat](https://docs.streampixel.io/resources/web-sdk-v2/voice-chat.md). | Only for chat |
| `@streampixel/ui` | The screens around the video: loading, password, "Click to start", idle warning, text input for phones, files, links, controls, end message. See [Ready-made screens](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays.md). | Optional |

To add the ready-made screens:

```bash npm theme={"dark"}
npm install @streampixel/ui
```

```bash yarn theme={"dark"}
yarn add @streampixel/ui
```

```bash pnpm theme={"dark"}
pnpm add @streampixel/ui
```

```ts theme={"dark"}
import { VoiceChat } from '@streampixel/web-sdk/voice'; // chat
import { mountUI } from '@streampixel/ui';              // ready-made screens
```

> [!NOTE]
>
> The engine updates by itself. `@streampixel/ui` does not: its screens are part of the package you install, so a fix to them needs a new install. Version 2.0.0-beta.2 of `@streampixel/ui` is for `@streampixel/web-sdk` 2.0.0-beta.2 and later.

## TypeScript

The types ship inside the packages. There is nothing else to install.

```ts theme={"dark"}
import {
  Streampixel,
  type StreampixelOptions,
  type StreamState,
  type EndedEvent,
} from '@streampixel/web-sdk';

const options: StreampixelOptions = {
  appId: 'YOUR_PROJECT_ID',
  container: document.getElementById('stream')!,
};

const stream: Streampixel = await Streampixel.create(options);

stream.on('state', (state: StreamState) => console.log(state.kind));
stream.on('ended', (e: EndedEvent) => console.log(e.code, e.endKind, e.message));
```

`Streampixel` is both the object with `create()` and the type of a stream.

This example uses `await` at the top level of a module. If your build target does not allow that, put the code in an `async` function, as the [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md) does.

| What the types give you | Detail |
| - | - |
| Checked event names | `stream.on()` accepts only real event names: a typo such as `stream.on('stat', …)` does not compile. |
| Checked payloads | Each event's payload is typed: `state` gives a `StreamState`, `stats` a `StreamStats`, and so on. |
| States as a union | Switch on `state.kind` and TypeScript knows the fields of each state. Keep a `default` branch: a newer engine may add a state. |
| Events from a newer engine | An engine released after your installed package can add an event that its types do not have yet. Subscribe to it with `stream.onUnknown(name, fn)`. |

> [accordion] All exported types
>
> From `@streampixel/web-sdk`: `Streampixel` (a stream), `StreampixelOptions`, `StreampixelEvents`, `StreamState`, `StreamStats`, `EndedEvent`, `EndKind`, `AuthOption`, `SharedMode`, `EngineOptions`, `Codec`, `Resolution`, `AfkWarning`, `Diagnostics`, `DiagnosticsSnapshot`, `StreamServerConfig`, `TicketResponse`, `AccessDescriptor`.
>
> From `@streampixel/ui`: `UIOptions`, `MountedUI`.

## Frameworks

One rule covers every framework:

1. Call `Streampixel.create()` when the container element is on the page.
2. When the component goes away, abort the `signal` you passed to `create()`, or call `stream.destroy()`.
3. Never call `create()` while rendering on a server.

The `signal` option is the safe way to do step 2. A component can go away before `create()` has resolved. Aborting the signal then rejects `create()` with an `AbortError` and starts nothing. Aborting it later destroys the stream.

```tsx React theme={"dark"}
import { useEffect, useRef } from 'react';
import { Streampixel } from '@streampixel/web-sdk';

export function Stream({ appId }: { appId: string }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const container = ref.current;
    if (!container) return;
    const ac = new AbortController();

    Streampixel.create({ appId, container, signal: ac.signal })
      .then((stream) => {
        stream.on('state', (state) => console.log(state.kind));
      })
      .catch((err) => {
        if (err?.name !== 'AbortError') console.error(err);
      });

    return () => ac.abort(); // before create() resolves: nothing starts. After: the stream is destroyed.
  }, [appId]);

  return <div ref={ref} style={{ width: '100%', height: '100%' }} />;
}
```

```vue Vue theme={"dark"}
<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';
import { Streampixel } from '@streampixel/web-sdk';

const props = defineProps({ appId: String });
const container = ref(null);
let ac;

onMounted(() => {
  ac = new AbortController();
  Streampixel.create({ appId: props.appId, container: container.value, signal: ac.signal })
    .then((stream) => {
      stream.on('state', (state) => console.log(state.kind));
    })
    .catch((err) => {
      if (err?.name !== 'AbortError') console.error(err);
    });
});

onBeforeUnmount(() => ac?.abort());
</script>

<template>
  <div ref="container" style="width: 100%; height: 100%"></div>
</template>
```

```svelte Svelte theme={"dark"}
<script>
  import { onMount } from 'svelte';
  import { Streampixel } from '@streampixel/web-sdk';

  let container;

  onMount(() => {
    const ac = new AbortController();
    Streampixel.create({ appId: 'YOUR_PROJECT_ID', container, signal: ac.signal })
      .then((stream) => {
        stream.on('state', (state) => console.log(state.kind));
      })
      .catch((err) => {
        if (err?.name !== 'AbortError') console.error(err);
      });

    return () => ac.abort();
  });
</script>

<div bind:this={container} style="width: 100%; height: 100%"></div>
```

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

const container = document.getElementById('stream');
const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });

stream.on('state', (state) => console.log(state.kind));

// Later, when the stream should go away (a closed dialog, a route change):
stream.destroy();
```

> [!NOTE]
>
> The React block is the pattern of our [example app](https://github.com/infinity-void-metaverse/Streampixel-SDK-Example), and [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md#react) has the full version. The Vue and Svelte blocks are patterns that follow the same rule with each framework's mount and unmount hooks: test them in your own app. There is no separate React, Vue or Svelte package.

In every framework, leave the container element empty in your template: the SDK adds and removes its own child there.

## Server-side rendering

| Call | On a server |
| - | - |
| `import … from '@streampixel/web-sdk'` | Safe. The import touches no browser globals. |
| `Streampixel.create()` | Needs a browser. Outside one it rejects with `AuthError`, kind `network`. |

Call `create()` from code that runs only in the browser: an effect or a mount hook, as in the blocks above. In the Next.js App Router, that means a component in a file that starts with `'use client'`.

## Content-Security-Policy

Skip this section if your site sends no `Content-Security-Policy` header.

If it does, allow the engine hosts and the Streampixel platform:

```text Content-Security-Policy theme={"dark"}
script-src  https://js.streampixel.io https://js-backup.streampixel.io;
connect-src https://*.streampixel.io wss://*.streampixel.io;
```

| Directive | Host | Used for |
| - | - | - |
| `script-src` | `js.streampixel.io`, `js-backup.streampixel.io` | The engine script, and `loader.js` if you use the script tag. |
| `connect-src` | `js.streampixel.io`, `js-backup.streampixel.io` | The signed list of engine builds. |
| `connect-src` | `platform.streampixel.io` | The project lookup and the session ticket. |
| `connect-src` | `telemetry.streampixel.io` | Telemetry. |
| `connect-src` | a `wss://` host named in the ticket | Signalling: the WebSocket on which the browser and your app agree on the video connection. |

> [accordion] Voice chat
>
> Chat also connects to the chat server: add `wss://*.livekit.cloud https://*.livekit.cloud` to `connect-src`.

> [accordion] Trusted Types
>
> If you enforce `require-trusted-types-for 'script'`, allow the SDK's policy name: `trusted-types streampixel-sdk`. The policy accepts only URLs on the two engine hosts.

> [accordion] @streampixel/ui
>
> The ready-made screens show your project's logo and banner, so `img-src` must allow the hosts they are served from (and `media-src` for a video banner). The package also adds one `<style>` element to the page, which a strict `style-src` must allow.

> [accordion] Dedicated and on-premises deployments
>
> If you set `advanced.platformHost` or `advanced.telemetryHost`, allow those hosts instead.

> [!WARNING]
>
> If the policy blocks the engine, `create()` rejects with `EngineLoadError` and no stream starts: there is no copy of the engine in the package. The `reason` is `engine-blocked` when the script is blocked, and `manifest-unavailable` when the list of builds cannot be fetched. See [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md).

## Check the install

`Streampixel.preload()` downloads and verifies the engine without starting a session. It is a quick test that your install, your network and your Content-Security-Policy are right.

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

const { source, version } = await Streampixel.preload();
console.log(source, version); // 'cdn' and the engine version, for example '2.0.0-beta.2'
```

> [!TIP]
>
> The console prints `cdn` and a version number. If `preload()` rejects instead, the error's `reason` says why.

> [!TIP]
>
> `preload()` is also a warm-up. Call it when your page loads, and `create()` starts faster when the viewer presses your Start button.

## What the page needs at run time

| Requirement | Detail |
| - | - |
| `https` or `localhost` | The loader checks the signature of the list of engine builds with the browser's WebCrypto, which browsers offer only on pages served over `https` or from `localhost`. Otherwise `create()` rejects with `EngineLoadError`, reason `no-webcrypto`. |
| A browser with WebRTC | Without it `create()` rejects with `AuthError`, kind `network`. |
| A project ID | The `appId` option. See [Finding your user and project IDs](https://docs.streampixel.io/resources/api-reference/finding-your-user-and-project-ids.md). |

> [!NOTE]
>
> **The name is `Streampixel`, with a lower-case p.** Version 2.0.0-beta.1 spelled it `StreamPixel` (also `StreamPixelOptions`, `StreamPixelEvents` and `window.StreamPixelSDK`). Those names still work in 2.0.0-beta.2 and mean the same things. They are marked as deprecated: use the new spelling in new code.

## Next steps

> [card] [Quick start](https://docs.streampixel.io/resources/web-sdk-v2/quick-start.md)
>
> A real page: container, `create()`, the ready-made screens, cleanup.

> [card] [Ready-made screens](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays.md)
>
> What `@streampixel/ui` draws, and how to change it.

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

> [card] [The engine and its updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> Channels, pinning a version, how the engine is verified.


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