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.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
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.Which build runs
The loader chooses the build in this order:- The version you pinned with
engine.version. - Otherwise, a build that the manifest names for your project. Streampixel can do this for one project that needs a particular engine build.
- Otherwise, the build of your channel:
engine.channel, which is'stable'unless you set it.
- Stable (default)
- Beta channel
- Pin a version
Do nothing. Your page runs the build of the
stable channel and gets fixes by itself.Which release runs. A channel the manifest does not have rejects with reason
no-channel.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.Staged releases
Staged releases
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.
Which engine is running in my page?
Which engine is running in my page?
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.
Optional. Pass the same choices you will pass to
create(), so that the build create() picks is the one already loaded.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.
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.