Skip to main content
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.
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.

Choose how to load the SDK

For a site with a build step: Vite, webpack, Next.js and others.
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.

The packages

To add the ready-made screens:
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.
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 does.
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.
The React block is the pattern of our example app, and Quick start 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 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:
Content-Security-Policy
Chat also connects to the chat server: add wss://*.livekit.cloud https://*.livekit.cloud to connect-src.
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.
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.
If you set advanced.platformHost or advanced.telemetryHost, allow those hosts instead.
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.

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.
The console prints cdn and a version number. If preload() rejects instead, the error’s reason says why.
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

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

Quick start

A real page: container, create(), the ready-made screens, cleanup.

Ready-made screens

What @streampixel/ui draws, and how to change it.

Options

Everything create() accepts.

The engine and its updates

Channels, pinning a version, how the engine is verified.