Skip to main content
Expert For developers and security reviewers who want to know exactly what code runs in the page and where it comes from. After this page you can explain the download to a reviewer, choose between automatic updates and a pinned version, and handle a download that fails. The SDK has two parts. You install one. The other is downloaded when a stream starts.

The loader

What npm install puts in your bundle. It finds the engine, proves that it comes from Streampixel, and hands it your options. It decides nothing about streaming. It never changes after you install it.

The engine

Everything that runs a stream: access, signalling, WebRTC, input, reconnection, telemetry. It is not in the package. create() downloads it from Streampixel’s servers, so fixes reach your site without a new install or deploy.
When your page calls Streampixel.create(), the loader fetches a signed manifest from the engine hosts, checks its signature, expiry and sequence number, and chooses a build: the version you pinned, else the one your channel runs. It then loads the engine script with its integrity hash and hands it your options. Only after these steps does the engine look the project up and ask the platform for a ticket.

What the npm package contains

@streampixel/web-sdk is the loader. It is under 10 KB of minified JavaScript and has no runtime dependencies. The package holds no engine, and so no copy to fall back to.
The script-tag build is the same loader, served as https://js.streampixel.io/v2/loader.js. It defines window.StreampixelSDK. See Installation.

What create() downloads

Two files, both from the same two public hosts. https://js.streampixel.io is tried first. https://js-backup.streampixel.io is its mirror. If your page uses chat, the chat code is a third file. It is loaded the first time you call VoiceChat.for(), in the same version as the stream’s engine, with the same checks. In your browser’s network panel the requests look like this:
https://js.streampixel.io
v2
manifest.json
v2.0.0-beta.2 (one folder per engine version)
engine.js
voice.js
The loader keeps what it loaded for the life of the page. A second create() with the same engine options and appId does not download again.

How the download is verified

The loader trusts a file only after every check below has passed. If one fails, nothing from that answer is run.
1

The hosts are fixed

The two hosts are constants in the package. No option, URL parameter or page global can point the loader to another host.
2

The manifest is signed

The manifest carries a signature (ECDSA, curve P-256, with SHA-256). The loader verifies it with the browser’s WebCrypto against public keys that are built into the package. A manifest without a valid signature is refused: reason signature.This is why the page must be served over https or from localhost: WebCrypto is not available elsewhere, and create() then rejects with reason no-webcrypto.
3

The manifest is current

Together these stop someone from serving an old, validly signed manifest to hold viewers on an old engine.
4

The engine file matches its hash

The engine is loaded as a script with Subresource Integrity. The hash (SHA-384) comes from the signed manifest, so the browser itself refuses a file with other content.
5

The script registers as the build that was chosen

After it loaded, the script must report the version and the contract number the loader expects. Otherwise the load fails with reason engine-register.
What this means for a reviewer:

Which build runs

The loader chooses the build in this order:
  1. The version you pinned with engine.version.
  2. Otherwise, a build that the manifest names for your project. Streampixel can do this for one project that needs a particular engine build.
  3. Otherwise, the build of your channel: engine.channel, which is 'stable' unless you set it.
Do nothing. Your page runs the build of the stable channel and gets fixes by itself.
'stable' | 'beta'
default:"'stable'"
Which release runs. A channel the manifest does not have rejects with reason no-channel.
string
One exact engine version, for example '2.0.0-beta.2'. It wins over the channel. A string that is not a version rejects with a TypeError. A version that does not exist rejects with EngineLoadError, reason no-build.
A pinned page gets no fixes until you change the pin. Pin when you need change control, and plan how you will move the pin. The manifest is still downloaded and verified on every page load.
A channel can list more than one build, each with a percentage. The loader then draws one random number per page load and takes the build that number falls on. Every stream on the same page load gets the same build. A reload can get the other one.
The two versions can differ: the engine updates by itself, the package does not. Include stream.engineVersion in every support request.

preload()

Streampixel.preload() downloads and verifies the engine without starting a session. Nothing else happens: no project lookup, no ticket, no GPU. Call it when the page loads, so that create() starts faster when the viewer presses Start.
object
Optional. Pass the same choices you will pass to create(), so that the build create() picks is the one already loaded.
Promise<{ source, version }>
version is the engine version that was loaded. source is 'cdn' in every published package. It rejects with EngineLoadError when the engine cannot be loaded.

Time limits

A healthy load takes a fraction of these limits. The longest waits apply only when every attempt runs into its limit. Aborting the signal you passed to create() does not interrupt the download. create() rejects with AbortError as soon as the download has finished or failed, and nothing starts.

When the download fails

create() and preload() reject with EngineLoadError. No stream starts.
err.reason says which step failed. The reasons you can act on: The full list, with the manifest checks, is in Errors and disconnects.
To see what a viewer’s network does, open the browser’s network panel and filter on streampixel.io. A blocked manifest or engine request shows there with the browser’s own reason.

What an update can and cannot change

The split between loader and engine is also a contract. Because the engine can add things after you compiled your page, write your code so that additions do not break it:
These pages describe engine 2.0.0-beta.2. A page that pins an older engine does not have everything described here: check stream.engineVersion.

Next steps

Reliability

What the engine does when the network or the app fails, with the timings.

Diagnostics

What you can read yourself, and what the SDK reports to Streampixel.

Options

Reference: engine.channel, engine.version and every other option.

Changelog

Reference: what changed in each release.