lib/stream-stats
What a dashboard shows of the session, gathered in one place for both cores
and published on window under one contract.
window.stream_info is what the server said of the stream: the capture path
and whether it is zero-copy, the encoder and whether it is hardware, the GPU,
and the reason a faster path was declined (stream_stats.py on the server).
It arrives once and again on a change, whether or not anybody looks.
window.stream_client is this page's half: the transport and the path it
took, the codec and resolution, and the decoder with the evidence for calling
it hardware or software. It changes only with the stream, so the core keeps
it current whether or not anybody looks, and a dashboard that opens its stats
draws it at once.
Everything that moves is gathered only while a dashboard has its stats on
screen. It says so with a statsOpen window message; the collector then asks
the server for stream_stats (the _stats verb), the core samples its own
side FIRST_SAMPLE_MS after the opening and once a second after that, and
each sample lands in window.stream_stats: latest, and history, which
starts empty when the stats open and grows while they stay open, up to
HISTORY_MAX seconds. What a sample counts (data received, frames dropped,
repairs asked for) is counted from the opening. Shut, nothing is sampled,
nothing is sent, and the server sends nothing. A shared viewer never
subscribes. Every change to the three is announced with a STATS_EVENT
event on window, which is when a dashboard reads them.
Classes
DecodeCapability
Defined in: lib/stream-stats.js:165
Whether the engine decodes a configuration efficiently, from
MediaCapabilities: what stands in for the decoder's own word where neither
the engine nor its frames say which decoder took the stream. Asked once per
configuration; efficient is null until the engine answers, and where it
cannot.
Constructors
Constructor
new DecodeCapability(): DecodeCapability;Defined in: lib/stream-stats.js:166
Returns
Properties
key
key: string;Defined in: lib/stream-stats.js:167
efficient
efficient: boolean;Defined in: lib/stream-stats.js:169
Methods
ask()
ask(configuration, key): void;Defined in: lib/stream-stats.js:176
Parameters
| Parameter | Type | Description |
|---|---|---|
configuration | MediaDecodingConfiguration | What decodingInfo is asked. |
key | string | The configuration the answer is kept for. |
Returns
void
StreamStats
Defined in: lib/stream-stats.js:239
Constructors
Constructor
new StreamStats(options): StreamStats;Defined in: lib/stream-stats.js:246
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { transport: "websockets" | "webrtc"; send: (arg0) => void; isViewer: () => boolean; onOpenChange: (arg0) => void; } | send puts one text message on the session connection; onOpenChange lets the core start and stop its own sampling. |
options.transport | "websockets" | "webrtc" | - |
options.send | (arg0) => void | - |
options.isViewer | () => boolean | - |
options.onOpenChange | (arg0) => void | - |
Returns
Accessors
open
Get Signature
get open(): boolean;Defined in: lib/stream-stats.js:268
Whether a dashboard has its stats on screen.
Returns
boolean
Methods
setOpen()
setOpen(open): void;Defined in: lib/stream-stats.js:286
A dashboard opened or shut its stats. Opening starts a fresh history.
Parameters
| Parameter | Type | Description |
|---|---|---|
open | boolean | - |
Returns
void
subscribe()
subscribe(): void;Defined in: lib/stream-stats.js:300
Tells the server what this page wants; a fresh connection has to be told again.
Returns
void
disconnected()
disconnected(): void;Defined in: lib/stream-stats.js:312
The connection went away, and the subscription and its verdict with it.
Returns
void
setConnection()
setConnection(poor): void;Defined in: lib/stream-stats.js:318
Parameters
| Parameter | Type | Description |
|---|---|---|
poor | boolean | The server's connection verdict for this page. |
Returns
void
setInfo()
setInfo(info): void;Defined in: lib/stream-stats.js:323
Parameters
| Parameter | Type | Description |
|---|---|---|
info | StreamInfo | The server's stream_info. |
Returns
void
setClient()
setClient(description): void;Defined in: lib/stream-stats.js:329
Parameters
| Parameter | Type | Description |
|---|---|---|
description | Partial<StreamClient> | What the core learned of its own side. |
Returns
void
serverSample()
serverSample(stats): void;Defined in: lib/stream-stats.js:343
The server's stream_stats, which the next sample carries. A sample on
screen that has none of the server's figures yet, the first after an
opening, takes them at once, so the first reading waits for neither side
and every later one costs a dashboard a single read.
Parameters
| Parameter | Type | Description |
|---|---|---|
stats | { } | - |
Returns
void
noteBytes()
noteBytes(bytes): void;Defined in: lib/stream-stats.js:354
Parameters
| Parameter | Type | Description |
|---|---|---|
bytes | number | Stream bytes that arrived, for the bandwidth and received figures. |
Returns
void
clientSample()
clientSample(figures): void;Defined in: lib/stream-stats.js:365
One second's figures from the core, merged with the server's and appended
to the history. mbps comes from noteBytes unless the core measured it,
and received_mb is what noteBytes counted since the opening.
Parameters
| Parameter | Type | Description |
|---|---|---|
figures | { } | - |
Returns
void
Variables
HISTORY_MAX
const HISTORY_MAX: 600 = 600;Defined in: lib/stream-stats.js:37
Seconds of history kept for the graphs.
FIRST_SAMPLE_MS
const FIRST_SAMPLE_MS: 500 = 500;Defined in: lib/stream-stats.js:39
How long after the stats open the first sample is taken, in ms.
STATS_EVENT
const STATS_EVENT: "selkies-stream-stats" = 'selkies-stream-stats';Defined in: lib/stream-stats.js:41
The event on window that announces a change to what the stats show.
SERVER_FRESH_MS
const SERVER_FRESH_MS: 3000 = 3000;Defined in: lib/stream-stats.js:43
Server figures older than this are left out of a sample, in ms.
Functions
decoderOfFormat()
function decoderOfFormat(format): "hardware" | "software" | "unknown";Defined in: lib/stream-stats.js:118
What a decoded frame's pixel format says of the decoder behind it. A hardware decoder hands out NV12 or an opaque frame, a software one planar I4xx.
Parameters
| Parameter | Type | Description |
|---|---|---|
format | string | VideoFrame.format; undefined where no frame was seen. |
Returns
"hardware" | "software" | "unknown"
framesOf()
function framesOf(format): string;Defined in: lib/stream-stats.js:125
What a decoded frame's pixel format is called in the evidence.
Parameters
| Parameter | Type |
|---|---|
format | any |
Returns
string
verdict()
function verdict(
decoder,
evidence,
expected,
shortfall?
): Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">;Defined in: lib/stream-stats.js:136
A decoder verdict and what it rests on, with whether it fell short: software where a hardware decoder was there to take the stream.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
decoder | "hardware" | "software" | "unknown" | undefined | - |
evidence | string | undefined | - |
expected | boolean | undefined | Whether a hardware decoder was there. |
shortfall? | string | 'hardware_available' | Why software fell short; said only where it did. |
Returns
Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">
capabilityVerdict()
function capabilityVerdict(capable, evidence): Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">;Defined in: lib/stream-stats.js:152
The last word where nothing names the decoder: whether the engine has an
efficient one for the stream at all (DecodeCapability). An engine that has
one is taken to be using it, since every sign of a software decode (a
preference after a fallback, a refused hardware configuration, planar frames)
has been read first and none was there; a verdict of unknown here would leave
a working hardware decoder unmarked on the engines whose frames say nothing.
Parameters
| Parameter | Type | Description |
|---|---|---|
capable | boolean | - |
evidence | string | What little there is otherwise. |
Returns
Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">
webcodecsDecoder()
function webcodecsDecoder(evidence): Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">;Defined in: lib/stream-stats.js:204
The WebCodecs decoder verdict from everything the page can know: a software
preference after a fallback is certain and falls short of the hardware it left,
an engine that refuses the stream's configuration with hardware preferred has
none, the frames say which kind made them where their format tells, and an
engine whose frames are all one format whatever decodes them (Gecko hands out
BGRX) is left to capabilityVerdict, which calls an engine with an efficient
decoder hardware. Software falls short, as over WebRTC,
where the engine says it decodes this configuration efficiently; that it
accepts the hardware preference says nothing, since some engines take it as
a hint and decode in software.
Parameters
| Parameter | Type | Description |
|---|---|---|
evidence | { forcedSoftware: boolean; hardwareSupported: boolean; format: string; capable: boolean; } | hardwareSupported is VideoDecoder.isConfigSupported with prefer-hardware, null where unasked; capable is DecodeCapability.efficient. |
evidence.forcedSoftware | boolean | - |
evidence.hardwareSupported | boolean | - |
evidence.format | string | - |
evidence.capable | boolean | - |
Returns
Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">
webrtcDecoder()
function webrtcDecoder(evidence): Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">;Defined in: lib/stream-stats.js:228
The WebRTC decoder verdict. Engines name the decoder in the inbound video report only to a page that holds a capture permission. Without one, a frame read from the received track is the decoder's own, as the WebCodecs verdict reads it; the element's current frame is not, since an engine may copy a software picture into GPU memory to composite it, so only a planar one says anything (software). Last is whether the engine has an efficient decoder for the stream at all, taken as the one in use where nothing said software.
Parameters
| Parameter | Type | Description |
|---|---|---|
evidence | { implementation: string; powerEfficient: boolean; trackFormat: string; elementFormat: string; capable: boolean; } | trackFormat is a MediaStreamTrackProcessor frame's format and elementFormat a VideoFrame of the <video>'s, undefined where none was read; capable is DecodeCapability.efficient. |
evidence.implementation | string | - |
evidence.powerEfficient | boolean | - |
evidence.trackFormat | string | - |
evidence.elementFormat | string | - |
evidence.capable | boolean | - |
Returns
Pick<StreamClient, "decoder" | "decoder_evidence" | "hardware_expected" | "decoder_reason">
References
StreamInfo
Re-exports StreamInfo
StreamClient
Re-exports StreamClient
StreamSample
Re-exports StreamSample