Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

fix(media-server): say what differs when a recording fails its packet or timing check

Richie McIlroy2563b2442647
diff --git a/apps/media-server/src/__tests__/lib/recording-verification.integration.test.ts b/apps/media-server/src/__tests__/lib/recording-verification.integration.test.ts
index 8ce747bb6..a8a3b6ef0 100644
--- a/apps/media-server/src/__tests__/lib/recording-verification.integration.test.ts
+++ b/apps/media-server/src/__tests__/lib/recording-verification.integration.test.ts
@@ -720,6 +720,44 @@ describe("encoded recording preservation", () => {
verifyRemuxedRecording(silent, silent, output, { requireAudio: true }),
).rejects.toThrow();
});
+ test("names what differs when the packet proof fails", async () => {
+ const shifted = join(directory, "proof-explained-shift.mp4");
+ await run([
+ "ffmpeg",
+ "-v",
+ "error",
+ "-i",
+ silent,
+ "-itsoffset",
+ "0.5",
+ "-i",
+ silent,
+ "-map",
+ "0:v:0",
+ "-map",
+ "1:a:0",
+ "-c",
+ "copy",
+ shifted,
+ ]);
+ await expect(
+ proveRecordingPackets(silent, silent, shifted, AbortSignal.timeout(5000)),
+ ).rejects.toThrow(
+ /audio does not preserve the source \(.*first difference at packet 0: pts -?[\d.]+ vs [\d.]+, dts/,
+ );
+
+ const changed = join(directory, "proof-explained-data.mp4");
+ const bytes = await readFile(silent);
+ const mdat = bytes.indexOf(Buffer.from("mdat"));
+ if (mdat < 0) throw new Error("Fixture has no media data");
+ bytes[mdat + 64] ^= 0xff;
+ await writeFile(changed, bytes);
+ await expect(
+ proveRecordingPackets(silent, silent, changed, AbortSignal.timeout(5000)),
+ ).rejects.toThrow(
+ /does not preserve the source \(first difference at packet \d+: data differs\)/,
+ );
+ });
test("does not start cancelled packet verification", async () => {
const controller = new AbortController();
controller.abort();
@@ -1123,7 +1161,7 @@ describe("source-preserving recording mux", () => {
const timing = await readRecordingVideoTiming(input, { timeoutMs: 5000 });
expect(timing.terminalPacketCount).toBe(3);
await expect(inspectRecordingSources(input, null)).rejects.toThrow(
- "Recording container timing does not match decoded video",
+ "Recording container timing does not match decoded video (final tied packets 3 vs decoded 2)",
);
});
@@ -1323,7 +1361,7 @@ describe("source-preserving recording mux", () => {
const timing = await readRecordingVideoTiming(input, { timeoutMs: 5000 });
expect(timing.videoPacketCount).toBe(31);
await expect(inspectRecordingSources(input, null)).rejects.toThrow(
- "Recording container timing does not match decoded video",
+ "Recording container timing does not match decoded video (packets 31 vs decoded frames 30)",
);
});
diff --git a/apps/media-server/src/lib/recording-packet-proof.ts b/apps/media-server/src/lib/recording-packet-proof.ts
index 67cf1ace4..0e9d59afb 100644
--- a/apps/media-server/src/lib/recording-packet-proof.ts
+++ b/apps/media-server/src/lib/recording-packet-proof.ts
@@ -203,6 +203,115 @@ export async function readRecordingAudioTail(
}
}
+function seconds(rational: string): number {
+ const [numerator, denominator] = rational.split("/").map(Number);
+ return numerator / denominator;
+}
+
+// A compact per-packet record, kept only so a failed proof can say which packet differs.
+class PacketLog {
+ private capacity = 1024;
+ length = 0;
+ private pts = new Float64Array(this.capacity);
+ private dts = new Float64Array(this.capacity);
+ private sizes = new Uint32Array(this.capacity);
+ private hashes = new Uint32Array(this.capacity);
+ private keyframes = new Uint8Array(this.capacity);
+
+ push(
+ pts: string,
+ dts: string,
+ flags: string | undefined,
+ size: string,
+ dataHash: string,
+ ) {
+ if (this.length === this.capacity) {
+ this.capacity *= 2;
+ const grow = <T extends Float64Array | Uint32Array | Uint8Array>(
+ array: T,
+ ) => {
+ const next = new (array.constructor as new (length: number) => T)(
+ this.capacity,
+ );
+ next.set(array);
+ return next;
+ };
+ this.pts = grow(this.pts);
+ this.dts = grow(this.dts);
+ this.sizes = grow(this.sizes);
+ this.hashes = grow(this.hashes);
+ this.keyframes = grow(this.keyframes);
+ }
+ this.pts[this.length] = seconds(pts);
+ this.dts[this.length] = seconds(dts);
+ this.sizes[this.length] = Number(size);
+ this.hashes[this.length] = Number.parseInt(dataHash.slice(7, 15), 16);
+ this.keyframes[this.length] =
+ (flags?.includes("K") ? 1 : 0) | (flags?.includes("D") ? 2 : 0);
+ this.length++;
+ }
+
+ at(index: number) {
+ return {
+ pts: this.pts[index],
+ dts: this.dts[index],
+ size: this.sizes[index],
+ data: this.hashes[index],
+ flags: this.keyframes[index],
+ };
+ }
+}
+
+function firstPacketDifference(source: PacketLog, output: PacketLog) {
+ const shared = Math.min(source.length, output.length);
+ for (let index = 0; index < shared; index++) {
+ const left = source.at(index);
+ const right = output.at(index);
+ const fields = (Object.keys(left) as (keyof typeof left)[]).filter(
+ (key) => left[key] !== right[key],
+ );
+ if (fields.length === 0) continue;
+ const show = (key: keyof typeof left, value: number) =>
+ key === "pts" || key === "dts" ? value.toFixed(6) : String(value);
+ return `first difference at packet ${index}: ${fields
+ .map((key) =>
+ key === "data"
+ ? "data differs"
+ : `${key} ${show(key, left[key])} vs ${show(key, right[key])}`,
+ )
+ .join(", ")}`;
+ }
+ if (source.length !== output.length)
+ return `packet ${shared} exists only in the ${source.length > output.length ? "source" : "output"}`;
+ return "packets match on timing, size, flags and data; packet side data differs";
+}
+
+function describeTrackDifference(
+ source: Awaited<ReturnType<typeof readTrack>>,
+ output: Awaited<ReturnType<typeof readTrack>>,
+): string {
+ const parts: string[] = [];
+ const left = source.summary.configuration as Record<string, unknown>;
+ const right = output.summary.configuration as Record<string, unknown>;
+ for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
+ if (JSON.stringify(left[key]) === JSON.stringify(right[key])) continue;
+ const value = (raw: unknown) => {
+ const text = JSON.stringify(raw) ?? "none";
+ return text.length > 40 ? "(differs)" : text;
+ };
+ parts.push(`${key} ${value(left[key])} vs ${value(right[key])}`);
+ }
+ if (source.summary.count !== output.summary.count)
+ parts.push(`packets ${source.summary.count} vs ${output.summary.count}`);
+ if (source.summary.startTime !== output.summary.startTime)
+ parts.push(
+ `start ${source.summary.startTime} vs ${output.summary.startTime}`,
+ );
+ if (source.summary.packets !== output.summary.packets)
+ parts.push(firstPacketDifference(source.log, output.log));
+ return parts.join("; ").slice(0, 400) || "track summaries differ";
+}
+
async function readTrack(
path: string,
kind: "video" | "audio",
@@ -260,6 +369,7 @@ async function readTrack(
const tail =
kind === "audio" ? await readRecordingAudioTail(path, signal) : undefined;
const hash = createHash("sha256");
+ const log = new PacketLog();
let count = 0;
let pendingPacket: Record<string, string> | undefined;
const commitPacket = (fields: Record<string, string>, nextDts?: string) => {
@@ -314,6 +424,13 @@ async function readTrack(
throw new Error(
"Recording audio tail does not match its packet inventory",
);
+ log.push(
+ time(pts, base),
+ time(dts, base),
+ packetFlags,
+ content.size ?? "0",
+ content.data_hash ?? "",
+ );
// Interior timing is bound by PTS/DTS; stored terminal durations are compared separately.
hash.update(
JSON.stringify({
@@ -366,7 +483,16 @@ async function readTrack(
);
if (pendingPacket) commitPacket(pendingPacket);
if (!count) throw new Error("Recording stream contains no packets");
- return { configuration, count, packets: hash.digest("hex"), startTime, tail };
+ return {
+ summary: {
+ configuration,
+ count,
+ packets: hash.digest("hex"),
+ startTime,
+ tail,
+ },
+ log,
+ };
}
export async function proveRecordingPackets(
@@ -406,24 +532,28 @@ export async function proveRecordingPackets(
);
let sourceTiming: Awaited<typeof sourceTimingRead>;
let outputTiming: Awaited<typeof outputTimingRead>;
- let sourceVideo: Awaited<typeof sourceVideoRead>;
- let outputVideo: Awaited<typeof outputVideoRead>;
+ let sourceVideo: Awaited<typeof sourceVideoRead>["summary"];
+ let outputVideo: Awaited<typeof outputVideoRead>["summary"];
try {
sourceTiming = await sourceTimingRead;
if (sourceTiming.terminalPacketCount !== 1)
throw new Error("Tied terminal samples require decoded source evidence");
- sourceVideo = await sourceVideoRead;
- outputVideo = await outputVideoRead;
+ const sourceVideoTrack = await sourceVideoRead;
+ const outputVideoTrack = await outputVideoRead;
+ sourceVideo = sourceVideoTrack.summary;
+ outputVideo = outputVideoTrack.summary;
if (JSON.stringify(sourceVideo) !== JSON.stringify(outputVideo))
throw new RecordingPacketMismatchError(
- "Recording encoded video does not preserve the source",
+ `Recording encoded video does not preserve the source (${describeTrackDifference(sourceVideoTrack, outputVideoTrack)})`,
);
if (sourceAudioRead && outputAudioRead) {
- const { tail: sourceTail, ...sourceAudio } = await sourceAudioRead;
- const { tail: outputTail, ...outputAudio } = await outputAudioRead;
+ const sourceAudioTrack = await sourceAudioRead;
+ const outputAudioTrack = await outputAudioRead;
+ const { tail: sourceTail, ...sourceAudio } = sourceAudioTrack.summary;
+ const { tail: outputTail, ...outputAudio } = outputAudioTrack.summary;
if (JSON.stringify(sourceAudio) !== JSON.stringify(outputAudio))
throw new RecordingPacketMismatchError(
- "Recording encoded audio does not preserve the source",
+ `Recording encoded audio does not preserve the source (${describeTrackDifference(sourceAudioTrack, outputAudioTrack)})`,
);
// MP4 edit-list rounding can change the reported AAC tail without changing decoded samples.
if (sourceTail?.duration !== outputTail?.duration)
diff --git a/apps/media-server/src/lib/recording-verification.ts b/apps/media-server/src/lib/recording-verification.ts
index 51e1c69e0..6bbe6442c 100644
--- a/apps/media-server/src/lib/recording-verification.ts
+++ b/apps/media-server/src/lib/recording-verification.ts
@@ -204,14 +204,23 @@ function videoTailIntegrity(
return `end:${relativeVideoNanoseconds(stream, lastVideoEndPts)}\n`;
}
const timeScale = BigInt(timing.timeScale);
- if (
+ const differences = [
(timing.lastTimestampTicks - timing.firstTimestampTicks) *
timeBaseDenominator !==
- (lastVideoPts - firstVideoPts) * timeBaseNumerator * timeScale ||
- timing.videoPacketCount !== stream.frameCount ||
+ (lastVideoPts - firstVideoPts) * timeBaseNumerator * timeScale
+ ? `span ${timing.lastTimestampTicks - timing.firstTimestampTicks}/${timing.timeScale} s vs decoded ${(lastVideoPts - firstVideoPts) * timeBaseNumerator}/${timeBaseDenominator} s`
+ : null,
+ timing.videoPacketCount !== stream.frameCount
+ ? `packets ${timing.videoPacketCount} vs decoded frames ${stream.frameCount}`
+ : null,
timing.terminalPacketCount !== stream.terminalVideoFrameCount
- ) {
- throw new Error("Recording container timing does not match decoded video");
+ ? `final tied packets ${timing.terminalPacketCount} vs decoded ${stream.terminalVideoFrameCount}`
+ : null,
+ ].filter((difference) => difference !== null);
+ if (differences.length > 0) {
+ throw new Error(
+ `Recording container timing does not match decoded video (${differences.join("; ")})`,
+ );
}
if (!/^[a-f0-9]{64}$/.test(timing.packetTimelineSha256)) {
throw new Error("Recording container packet timing is missing");