Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(diagnostics): expose sanitized packet loss evidence (#362)
AAAa03b013594c1
diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex 16cc7e31..44c2510b 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -302,6 +302,17 @@ bandwidth estimate stayed near 13 Mbps while the sender media-source cadencefell to about 1 fps. That interval is a capture/source-production boundary, notan RTX-recovery result, and the LiveKit patch does not address it.+Chrome 151 exposed `fractionLost`, `packetsLost`, jitter, and RTT on the linked+`remote-inbound-rtp` sender report, but not the newer inherited+`packetsReceived` field. The previous sender percentage therefore remained+structurally unknown even when RTT proved that the report was linked. Current+source consumes the normalized `fractionLost` value once for each newer exact+RTCP report; a first report, repeated report timestamp, identity change,+timestamp rollback, missing field, or out-of-range value stays unknown. Viewer+route diagnostics also retain the already-authorized receive/loss deltas, RTT,+and jitter in the sanitized event. These fields remain observability only and+do not enter native quality classification, candidate comparison, or routing.+## Host And Page Cost BoundariesEach ordinary Browser child is an independent PeerConnection and normally andiff --git a/src/client/media/viewer-quality-evidence.ts b/src/client/media/viewer-quality-evidence.tsindex 8bdcc790..4959a8ff 100644--- a/src/client/media/viewer-quality-evidence.ts+++ b/src/client/media/viewer-quality-evidence.ts@@ -10,12 +10,12 @@ import {type ServerMessage,type ViewerQualityEvidenceMetrics,} from "../../shared/protocol";+import { packetLossPercentFromDeltas } from "../../shared/packet-loss";import {EMPTY_METRICS,type ConnectionMetrics,type PeerSnapshot,} from "../types";-import { packetLossPercentFromDeltas } from "../webrtc/stats";export type ViewerQualityEvidence = Extract<ServerMessage,diff --git a/src/client/webrtc/stats.ts b/src/client/webrtc/stats.tsindex 5f05adce..8ccdca0f 100644--- a/src/client/webrtc/stats.ts+++ b/src/client/webrtc/stats.ts@@ -2,6 +2,7 @@ import {EMPTY_METRICS,type ConnectionMetrics,} from "../types";+import { packetLossPercentFromDeltas } from "../../shared/packet-loss";import { deriveVideoCodecEvidence } from "../../shared/video-codec-evidence";type StatsRecord = Record<string, unknown> & {@@ -20,6 +21,7 @@ export interface StatsAccumulator {ssrc: number | null;trackIdentifier: string | null;lossSourceId: string | null;+ lossReportTimestamp: number | null;bytes: number | null;frames: number | null;timestamp: number | null;@@ -227,6 +229,7 @@ export function createStatsAccumulator(): StatsAccumulator {ssrc: null,trackIdentifier: null,lossSourceId: null,+ lossReportTimestamp: null,bytes: null,frames: null,timestamp: null,@@ -309,24 +312,6 @@ function intervalAverageMs(: null;}-export function packetLossPercentFromDeltas(- packetsReceivedDelta: number | null,- packetsLostDelta: number | null,-): number | null {- if (- packetsReceivedDelta === null ||- packetsLostDelta === null ||- !Number.isFinite(packetsReceivedDelta) ||- !Number.isFinite(packetsLostDelta) ||- packetsReceivedDelta < 0 ||- packetsLostDelta < 0- ) {- return null;- }- const packetDelta = packetsReceivedDelta + packetsLostDelta;- return packetDelta > 0 ? (packetsLostDelta / packetDelta) * 100 : null;-}-function percentOfInterval(partDelta: number | null,totalDelta: number | null,@@ -706,6 +691,7 @@ export function collectConnectionMetricsFromReport(direction === "send" ? linkedRemoteInbound(report, media) : null;const lossSource = direction === "send" ? remoteInbound : media;const lossSourceId = lossSource?.id ?? null;+ const lossReportTimestamp = numberValue(lossSource, "timestamp");const sameMedia =mediaId !== null &&mediaId === previous.mediaId &&@@ -725,6 +711,7 @@ export function collectConnectionMetricsFromReport(const packetsSent = numberValue(media, "packetsSent");const packetsReceived = numberValue(lossSource, "packetsReceived");const packetsLost = numberValue(lossSource, "packetsLost");+ const fractionLost = numberValue(remoteInbound, "fractionLost");const totalEncodeTime = numberValue(media, "totalEncodeTime");const totalDecodeTime = numberValue(media, "totalDecodeTime");const framesDropped = numberValue(media, "framesDropped");@@ -830,6 +817,19 @@ export function collectConnectionMetricsFromReport(sampleWindowMs !== null && sameLossSource,): null;+ // RTCP already defines fractionLost over its own report interval. Consume a+ // report once instead of mixing that remote interval with local send deltas.+ const senderPacketLossPercent =+ direction === "send" &&+ sameLossSource &&+ lossReportTimestamp !== null &&+ previous.lossReportTimestamp !== null &&+ lossReportTimestamp > previous.lossReportTimestamp &&+ fractionLost !== null &&+ fractionLost >= 0 &&+ fractionLost <= 1+ ? fractionLost * 100+ : null;const intervalFramesDecoded =direction === "receive"? intervalDelta(@@ -898,6 +898,7 @@ export function collectConnectionMetricsFromReport(previous.ssrc = ssrc;previous.trackIdentifier = trackIdentifier;previous.lossSourceId = lossSourceId;+ previous.lossReportTimestamp = lossReportTimestamp;previous.bytes = bytes;previous.frames = frames;previous.timestamp = timestamp;@@ -1094,10 +1095,13 @@ export function collectConnectionMetricsFromReport(intervalPacketsSent,intervalPacketsReceived,intervalPacketsLost,- packetLossPercent: packetLossPercentFromDeltas(- lossPacketsReceivedDelta,- intervalPacketsLost,- ),+ packetLossPercent:+ direction === "send"+ ? senderPacketLossPercent+ : packetLossPercentFromDeltas(+ lossPacketsReceivedDelta,+ intervalPacketsLost,+ ),jitterMs:numberValue(direction === "send" ? remoteInbound : media, "jitter") !== null? numberValue(direction === "send" ? remoteInbound : media, "jitter")! *diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 90fce68e..0d2b3635 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -1,6 +1,8 @@import { randomBytes } from "node:crypto";import { debuglog } from "node:util";+import { packetLossPercentFromDeltas } from "../shared/packet-loss.js";+import type {ClientMessage,MediaRouteUpstream,@@ -9,6 +11,7 @@ import type {RoutePolicy,Role,ServerMessage,+ ViewerQualityEvidenceMetrics,} from "../shared/protocol.js";import { assertEndpointMediaCopyCapacity } from "../shared/media-copy-accounting.js";import type { SfuTokenIssuer } from "./livekit-token.js";@@ -305,7 +308,10 @@ export class HybridMediaRouter {}observeQualityEvidence(- input: RouteQualityEvidenceInput & { roomId: string },+ input: Omit<RouteQualityEvidenceInput, "metrics"> & {+ roomId: string;+ metrics: ViewerQualityEvidenceMetrics;+ },): RouteQualityEvidenceResult {const { roomId, ...evidence } = input;const result =@@ -325,6 +331,14 @@ export class HybridMediaRouter {framesDecoded: input.metrics.framesDecodedDelta,freezes: input.metrics.freezeCountDelta,pauses: input.metrics.pauseCountDelta,+ packetsReceivedDelta: input.metrics.packetsReceivedDelta,+ packetsLostDelta: input.metrics.packetsLostDelta,+ packetLossPercent: packetLossPercentFromDeltas(+ input.metrics.packetsReceivedDelta,+ input.metrics.packetsLostDelta,+ ),+ rttMs: input.metrics.rttMs,+ jitterMs: input.metrics.jitterMs,});}return result;diff --git a/src/shared/packet-loss.ts b/src/shared/packet-loss.tsnew file mode 100644index 00000000..45511fba--- /dev/null+++ b/src/shared/packet-loss.ts@@ -0,0 +1,17 @@+export function packetLossPercentFromDeltas(+ packetsReceivedDelta: number | null,+ packetsLostDelta: number | null,+): number | null {+ if (+ packetsReceivedDelta === null ||+ packetsLostDelta === null ||+ !Number.isFinite(packetsReceivedDelta) ||+ !Number.isFinite(packetsLostDelta) ||+ packetsReceivedDelta < 0 ||+ packetsLostDelta < 0+ ) {+ return null;+ }+ const packetDelta = packetsReceivedDelta + packetsLostDelta;+ return packetDelta > 0 ? (packetsLostDelta / packetDelta) * 100 : null;+}diff --git a/tests/packet-loss.test.ts b/tests/packet-loss.test.tsnew file mode 100644index 00000000..6f4cdef1--- /dev/null+++ b/tests/packet-loss.test.ts@@ -0,0 +1,112 @@+import { describe, expect, it } from "vitest";++import {+ collectConnectionMetricsFromReport,+ createStatsAccumulator,+} from "../src/client/webrtc/stats";+import { packetLossPercentFromDeltas } from "../src/shared/packet-loss";++function senderReport(+ mediaTimestamp: number,+ lossSourceId: string,+ lossTimestamp: number,+ fractionLost: number,+ packetsLost: number,+): RTCStatsReport {+ return new Map<string, unknown>([+ [+ "video",+ {+ id: "video",+ type: "outbound-rtp",+ timestamp: mediaTimestamp,+ kind: "video",+ ssrc: 101,+ remoteId: lossSourceId,+ packetsSent: mediaTimestamp,+ bytesSent: mediaTimestamp,+ framesEncoded: mediaTimestamp / 100,+ },+ ],+ [+ lossSourceId,+ {+ id: lossSourceId,+ type: "remote-inbound-rtp",+ timestamp: lossTimestamp,+ kind: "video",+ ssrc: 101,+ packetsLost,+ fractionLost,+ roundTripTime: 0.02,+ },+ ],+ ]) as unknown as RTCStatsReport;+}++describe("packet loss evidence", () => {+ it("uses each fresh sender RTCP fraction exactly once", () => {+ const accumulator = createStatsAccumulator();++ const first = collectConnectionMetricsFromReport(+ senderReport(1_000, "remote-a", 900, 0.25, 4),+ "send",+ accumulator,+ );+ const repeatedReport = collectConnectionMetricsFromReport(+ senderReport(3_000, "remote-a", 900, 0.25, 4),+ "send",+ accumulator,+ );+ const freshReport = collectConnectionMetricsFromReport(+ senderReport(5_000, "remote-a", 4_900, 0.125, 6),+ "send",+ accumulator,+ );++ expect(first.packetLossPercent).toBeNull();+ expect(repeatedReport.packetLossPercent).toBeNull();+ expect(freshReport.packetLossPercent).toBe(12.5);+ });++ it("rebaselines sender loss on source or report-time changes", () => {+ const accumulator = createStatsAccumulator();+ collectConnectionMetricsFromReport(+ senderReport(1_000, "remote-a", 900, 0.1, 2),+ "send",+ accumulator,+ );+ const sourceChanged = collectConnectionMetricsFromReport(+ senderReport(3_000, "remote-b", 2_900, 0.2, 3),+ "send",+ accumulator,+ );+ const stableSource = collectConnectionMetricsFromReport(+ senderReport(5_000, "remote-b", 4_900, 0.2, 4),+ "send",+ accumulator,+ );+ const timestampRollback = collectConnectionMetricsFromReport(+ senderReport(7_000, "remote-b", 4_000, 0.5, 1),+ "send",+ accumulator,+ );+ const invalidFraction = collectConnectionMetricsFromReport(+ senderReport(9_000, "remote-b", 8_900, 1.1, 5),+ "send",+ accumulator,+ );++ expect(sourceChanged.packetLossPercent).toBeNull();+ expect(stableSource.packetLossPercent).toBe(20);+ expect(timestampRollback.packetLossPercent).toBeNull();+ expect(invalidFraction.packetLossPercent).toBeNull();+ });++ it("keeps receive-side delta validation unchanged", () => {+ expect(packetLossPercentFromDeltas(90, 10)).toBe(10);+ expect(packetLossPercentFromDeltas(0, 0)).toBeNull();+ expect(packetLossPercentFromDeltas(null, 1)).toBeNull();+ expect(packetLossPercentFromDeltas(10, -1)).toBeNull();+ });+});