Skip to main content
Expert For developers who debug sessions, and for privacy and security reviewers. After this page you can read every number the SDK gives you, say exactly what the SDK reports to Streampixel, and find out why one session went wrong. There are three sources of information about a stream.

stats in depth

All values come from the browser’s own WebRTC statistics for the video connection.
number
Frames decoded since the previous sample, divided by the time between the two samples, rounded.
number
The network round-trip time of the connection in use, in milliseconds. It is the time for a packet to reach the other end and come back. It is not the time from a click to the picture changing: that also includes rendering, encoding and decoding.0 until the browser has a first reading. When one sample has no reading, the last good value is kept.
number
Total frames decoded on this connection.
number
Total frames the browser dropped on this connection.
number | null
Video received since the previous sample, in kilobits per second. Video only: sound is not counted. null when it cannot be computed for a sample.
string | null
The size of the decoded picture, for example "1920x1080". null until the browser reports a size.
string | null
The video codec in use, for example "H264" or "AV1". null until the browser reports it.
'' | 'udp' | 'tcp' | 'tls'
The transport of the relay in use. '' on a direct path. 'tcp' or 'tls' means UDP is blocked on the viewer’s network: see Relay fallback.
number | null
The encoder’s quantisation parameter, as the app last reported it. It is always on H.264’s scale of 0 to 51, whatever the codec. Lower means better picture quality. null before the first value.
number
Video packets lost since this connection started.
number
Bytes received since this connection started, video and sound together.
The first sample after the video starts compares with zero. Its fps and bitrateKbps cover everything received since the connection came up, so they can read high. Skip the first sample in a chart.
The videoEncoderAvgQP event gives the same quantisation parameter as avgQp, pushed about once a second as the app reports it.

Reading the numbers

These are the usual meanings. Treat them as a starting point, not as proof. How the same numbers appear in the dashboard is described in Analytics interpretation. A ready-made readout for your page is in the cookbook.

getDiagnostics()

getDiagnostics() returns a snapshot of the video connection at this moment: its states, the network paths the browser found, and the path in use.
It resolves to null when there is no video connection: before the connection is negotiated, and after the session ended. Take the snapshot while the stream is up.
The snapshot holds the viewer’s network addresses, public and local, unshortened. Give it to support. Do not publish it, and do not send it to a third-party logging service without a reason.
The stalled event carries the same snapshot, taken at the moment the SDK judged the video dead. Its TypeScript type lists the first nine fields below.
string
One sentence that sums up the snapshot.
string
The browser’s state for the network path: new, checking, connected, completed, disconnected, failed or closed.
string
The browser’s state for the whole video connection.
string
Whether the browser is still looking for network paths: new, gathering or complete.
boolean
The browser found a local address.
boolean
The browser found its public address. false together with relayCandidatesFound: false, after gathering is complete, is the pattern of a network that blocks the stream.
boolean
The browser reached the relay and got an address on it.
number
How many pairs of addresses (one on each side) the browser has.
number
How many of those pairs work.
number
How many of those pairs failed.
string
The kind of path in use: TURN for the relay, otherwise the type of the viewer’s address on that path, such as HOST or SRFLX. Absent while no path is selected.
string
The viewer’s end of the path in use, as address:port. On a relayed path this is the relay’s address. On a direct path it is the viewer’s own address.
string[]
Problems the SDK detected in this snapshot. Absent when there are none.
string
A first guess derived from issues: TURN_SERVER_ISSUE, NETWORK_FIREWALL_ISSUE, SIGNALLING_SERVER_ISSUE or UNKNOWN_ISSUE. Absent when there are no issues. It is a hint for where to look first, not a diagnosis.
number
Milliseconds since the stream object was created.
For support, the snapshot also carries the detail behind the summary.

What the SDK reports to Streampixel

This section is written for a privacy or security review. The SDK reports to Streampixel’s own telemetry service during a session. These reports are what the session pages of your dashboard show, and what Streampixel support reads when you ask about a session.

Two levels

Everything in the table below.

Sent with every report

Network addresses

The viewer’s own network addresses appear in connection diagnostics. They are shortened in the page, before a report is sent: getDiagnostics(), which returns to your own page, is not shortened.

Never reported

  • Passwords and tickets.
  • Your launchParams.
  • Messages between your page and your app, in either direction.
  • The viewer’s sound, camera picture, keyboard or mouse input.

When nothing is reported

  • Before a ticket exists. A password project that is waiting for its password has reported nothing.
  • When the ticket came from your own server (“Your app only”, not available yet) without its telemetry token.

What the SDK stores in the browser

The SDK sets no cookie.

Every connection the SDK opens

The matching Content-Security-Policy is in Installation. The ports a viewer’s network must allow are in Network requirements.

How to debug a bad session

1

Record what happened

Add this helper while you debug. It prints every state, event and end with the time since the start, and keeps the last minute of stats.
debug.ts
Call attachDebug(stream) directly after await Streampixel.create(...), so that it sees the first events.
2

Find the phase that failed

3

Read how it ended

The ended event names the side to look at.Every code is explained in Errors and disconnects. What the SDK tried before it gave up is in Reliability.
4

For a quality problem, read the numbers

Watch stats while the problem shows, and use the table in Reading the numbers. Check relayTransport first: a stream relayed over TCP or TLS has lower quality.
5

Take a snapshot while the stream is up

Call the snapshot() function that attachDebug() returned. After the session ended, getDiagnostics() returns null, so take it while the problem is visible.
6

Rule out your own page

Open the project’s share link on the same device and the same network. If the share link shows the same problem, the cause is not in your page.
7

Compare with the dashboard

Find the session in your dashboard by its session ID. The session’s page shows what the SDK reported. See Analytics interpretation.

What to send to support

Send these to support@streampixel.io:
  • The session ID and the streamer ID: stream.currentSessionId and stream.currentStreamerId.
  • The engine version: stream.engineVersion.
  • The ended payload: code, reason and endKind. Or, when create() rejected, the error’s kind or reason and its message.
  • The snapshot from getDiagnostics(), or the one the stalled event carried.
  • The time of the problem, with the time zone, and what the viewer saw.
With the session ID, support can read the same session’s reports on the platform side.

Next steps

Reliability

What the SDK does for each failure, and after how many seconds.

The engine and updates

Where the code in the page comes from, and how it is verified.

Events and states

Reference: StreamStats and every event.

Stream API

Reference: getDiagnostics() and every other method.