feat(VideoDecoderIssueDetector): measure local decode demand, not fps volatility

[jenspalmqvist]

Closes #48

Purpose

VideoDecoderIssueDetector emits decoder-cpu-throttling when the device that runs the library cannot decode the incoming video fast enough. Today it measures only how much the frame rate of each inbound stream wobbles over the last five samples. A remote participant whose encoder gives up frame rate because of a bad uplink or a slow CPU produces exactly that wobble on every receiver, so every receiver reports decoder-cpu-throttling about its own device. With three publishers, one wobbling sender is 33 percent of the inbound streams, above the default 30 percent threshold.

After this change the issue fires only when, per peer connection, frames that arrived on this device were not decoded, enough inbound streams show that shortfall, the incoming video together demands a large share of decoder time, and at least one affected stream is itself costly to decode. Streams with packet loss, high RTP jitter, hardware decoding, missing counters, no decoded frames, or a counter reset in the window are excluded. A sender that sends fewer frames no longer triggers the issue.

What changed

• src/detectors/VideoDecoderIssueDetector.ts: volatility signal replaced by decode demand (totalDecodeTime per decoded frame times received frames per second), frame shortfall (framesReceived - framesDecoded), an affected-streams gate, and a per-stream corroboration. New params decodeDemandThreshold, affectedStreamDemandThreshold, frameShortfallPctThreshold, minFramesReceived, minWindowMs, maxPacketLossPct, maxJitterMs. affectedStreamsPercentThreshold keeps working. volatilityThreshold is accepted and ignored (deprecated).
• Payload: adds decodeDemand, frameShortfallPct, windowMs, evaluatedStreams, throttledStreams. Keeps affectedStreamsPercent and the misspelled throtthedStreams (deprecated, same array as throttledStreams, still only the affected streams), with allFps and volatility kept per entry as deprecated informational fields.
• src/types.ts: optional powerEfficientDecoder on ParsedInboundVideoStreamStats.
• test/detectors/VideoDecoderIssueDetector.spec.ts: first spec for this detector, 22 tests with a cumulative-counter fixture builder. The test does not report a sender whose frame rate wobbles fails on the current code and passes here.
• README.md: section rewritten; the old example showed a field the code never emitted.
• docs/plans/EXECPLAN_DECODER_CPU_THROTTLING_SIGNAL.md: the design record, six review rounds, decision log, and test evidence.

Known limitation

Browsers drop a frame before decode only when a later frame is decodable without it, which needs temporal layers (simulcast or SVC). On a single-layer stream (peer-to-peer VP8 without simulcast, H.264) an overloaded receiver decodes every frame late and shows no shortfall, so this detector stays silent there. The README says so.

Compatibility notes (minor release)

Earliest emission moves from the sixth to the fifth poll. affectedStreamsPercent is rounded to three decimals. allFps holds one value per stored sample (4 by default) instead of exactly 5. A very high volatilityThreshold no longer silences the detector. The detector needs id, timestamp, framesReceived, framesDecoded, totalDecodeTime, packetsReceived, packetsLost, and jitter in inbound video stats and is silent without them.

Verification

• npm test on Node 24: 58 passing, 0 failing (36 existing plus 22 new), run on this exact commit.
• npm run lint and npm run lint:tests: clean on this exact commit.
• Milestone checkpoint: with the previous detector and only the wobble test present, the suite reported that test failing at the sixth call with fps series [30, 30, 15, 30, 15], volatility 30, 33.3 percent affected.
• Not performed: a browser run. The manual check in the plan (SFU call with simulcast, uplink throttle on one participant, CPU burner on another, unattached track) is still open and should be done in a staging call before relying on the release.
• Reviews: three Codex adversarial reviews and two independent Claude reviews of the plan, one Codex adversarial review of this diff. All accepted findings are recorded in the plan.

🤖 Generated with Claude Code

https://claude.ai/code/session_01V1KrAS941bzfk9EuBPG33k