stats in depth
Frames decoded since the previous sample, divided by the time between the two samples, rounded.
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.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.The size of the decoded picture, for example
"1920x1080". null until the browser reports a size.The video codec in use, for example
"H264" or "AV1". null until the browser reports it.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.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.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.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.
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 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.
The browser’s state for the network path:
new, checking, connected, completed, disconnected, failed or closed.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.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.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.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.The raw lists in the snapshot
The raw lists in the snapshot
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
- standard (default)
- minimal
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 Call
stats.debug.ts
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.currentSessionIdandstream.currentStreamerId. - The engine version:
stream.engineVersion. - The
endedpayload:code,reasonandendKind. Or, whencreate()rejected, the error’skindorreasonand itsmessage. - The snapshot from
getDiagnostics(), or the one thestalledevent carried. - The time of the problem, with the time zone, and what the viewer saw.
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.