Skip to content

armgit / Piik

Public Imported from GitHub
0

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.md
index 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 cadence
fell to about 1 fps. That interval is a capture/source-production boundary, not
an 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 Boundaries
Each ordinary Browser child is an independent PeerConnection and normally an
diff --git a/src/client/media/viewer-quality-evidence.ts b/src/client/media/viewer-quality-evidence.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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();
+ });
+});