A password is neither of the two. On a password project
create() resolves, and the stream waits in the state awaitingPassword. A wrong password comes back as that state with wrong: true. See Access.The short version
This handler covers both moments. The sections below explain every branch.handle-errors.ts
Errors from create()
create() rejects with one of four errors.
AuthError and EngineLoadError are exported by @streampixel/web-sdk, so instanceof works.
A full handler for the kinds a viewer can meet:
create-errors.ts
How long create() can take before it rejects
How long create() can take before it rejects
Aborting
signal during a platform call rejects at once. Aborting during the engine download rejects as soon as the download has finished or failed.AuthError
Every AuthError has these properties:
The category. Switch on it. The table below lists every kind. A newer engine may add a kind this page does not list yet, so keep a
default branch.A description. For
sso-failed it is one of a fixed set of sentences written for the viewer. For the other kinds, treat it as text for your logs.The project’s logo, banner, loading texts and theme. Present once the project is known, so your own offline or sign-in screen can look like the project.
For
rate-limited: true means every attempt from this network is refused for now, not only wrong passwords.stream.submitPassword() rejects with the same AuthError for failures that are not about the password itself (kind network, project-offline and so on). A wrong password does not reject: it resolves, and the state is awaitingPassword with wrong: true.EngineLoadError
The package you install is a small loader. The engine is downloaded when create() runs, from js.streampixel.io or its mirror js-backup.streampixel.io, and verified. When no verified engine can be loaded, create() rejects with EngineLoadError and no stream starts: the npm package holds no copy of the engine to fall back to. A failed load is not remembered, so calling create() again tries again.
err.reason says why. The first group is what you can fix in your page or on the viewer’s network:
The second group means the list of engine builds (the manifest) failed one of the loader’s checks and was refused. Your page cannot fix these. If one repeats, contact support with the
reason.
How the loader finds, checks and loads the engine is described in The engine and updates.
TypeError
Option mistakes are reported before any network call. The message names the option.
All options are listed in Options.
AbortError
When you pass signal and abort it before create() resolves, create() rejects with a DOMException named AbortError. Nothing is left running: no session, no GPU. Aborting after create() resolved destroys the stream instead, and ended fires with endKind: 'user'.
How a session ends
Once a stream exists, every ending arrives the same way: theended event, and the state ended with the same fields.
The server’s own text, or the SDK’s description. For logs and support, not for viewers.
Who ended the session. See the next table.
A sentence in plain language for the viewer. It is the same wording as Streampixel’s share page.
Codes sent by the platform
Notes on this table:
1005and1006(ABNORMAL) are connection drops. They never end a session by themselves: the SDK reconnects, and ends with4007when that fails.4010is also decided by the SDK itself when the project forces the relay and the platform handed out none. TheendKindisserverin both cases.- A Test locally session that expired ends with
1008and its own sentence: “This dev session has expired or is not valid any more. Start a new one in the dashboard (Test locally).” - For causes and fixes on the platform side, see Disconnect codes.
Codes decided by the SDK in the browser
The platform never sends these. They mean the cause is on the viewer’s side of the connection, or between the viewer and the platform. There is nothing to look for in your application’s logs.DisconnectCodes.SESSION_TERMINATED is a deprecated second name for 4000. Use PROJECT_INACTIVE for 4000 and SESSION_TERMINATED_BY_PLATFORM for 4009.What the SDK retries, and what ends the session
The exact timings are in Reliability. What your page sees while the SDK recovers is in Events and states.
What to show the viewer
The SDK already wrote the sentence: showmessage. Then decide what to offer next to it.
Start again
start-again.ts
destroy() on a live stream fires ended with code 1000 and endKind: 'user' before it drops the listeners. That is why the listener returns early for user: without the check, a restart would show an end card for the stream you just replaced. This example leaves out the try / catch around create() shown in The short version.
What to send to support
Collect these four things. The first three are available at any time aftercreate() resolved.
1
The session's IDs
stream.currentSessionId and stream.currentStreamerId. They are the IDs in your Streampixel analytics. The session event announces them, also when the SDK moves to a fresh session.2
The engine version
stream.engineVersion. The engine updates by itself, so it can differ from the package version you installed.3
The end
The
ended payload: code, reason and endKind.4
A connection snapshot
await stream.getDiagnostics(), taken while the stream is still up. After the end it returns null. The stalled event carries the same kind of snapshot at the moment the video stopped.support-report.ts
Common questions
My ended listener fires when I call destroy()
My ended listener fires when I call destroy()
That is expected.
destroy() ends a live session, so ended fires with code 1000 and endKind: 'user', and then the listeners are dropped. Check endKind, or unsubscribe before you call destroy(). stream.on() returns the function that unsubscribes.The code is 1000 and endKind is server
The code is 1000 and endKind is server
The platform closed the session cleanly. Your page did not end it:
disconnect() and destroy() give endKind: 'user'. The message is “The stream was disconnected.”create() rejected, and I see no ended event
create() rejected, and I see no ended event
ended belongs to a stream object, and a rejected create() returned none. Handle the error in the catch.The session ended with 4102 although the viewer's network is fine
The session ended with 4102 although the viewer's network is fine
4102 means the connection was up and no video frames arrived, also after the SDK tried one fresh session. The usual cause is the application: it stopped rendering or hung. Look at the application, not at the viewer’s network. 4101 is the code for a video connection that never came up.A viewer on an office network gets 4100
A viewer on an office network gets 4100
The network allows neither a direct path nor the relay. Show the sentence, and point the viewer’s IT team to Network requirements.
Next steps
Reliability
One level up: what the SDK does for each failure, with the exact timings.
Diagnostics
Read
stats and getDiagnostics(), and debug a bad session.Events and states
Every state and event, with its fields.
Stream API
Reference: every property and method of the stream object.