Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
import { spawn } from "node:child_process";
import { createHash } from "node:crypto";
import { lstat } from "node:fs/promises";
import { isAbsolute } from "node:path";
import { fileURLToPath } from "node:url";
import { z } from "zod";
import {
RecordingTimingError,
readRecordingVideoTiming,
} from "./recording-timing";
import { registerSubprocess, unregisterSubprocess } from "./subprocess";
export class RecordingPacketMismatchError extends Error {}
interface PacketStream {
index: number;
codec_type: "video" | "audio";
time_base: string;
[key: string]: unknown;
}
const STREAM_FIELDS =
"index,start_pts,codec_type,codec_name,profile,level,codec_tag_string,width,height,sample_aspect_ratio,pix_fmt,color_range,color_space,color_transfer,color_primaries,chroma_location,field_order,refs,sample_fmt,sample_rate,channels,channel_layout,time_base,extradata_hash";
async function runInspector(
command: string,
args: string[],
signal: AbortSignal,
line: (value: string) => void,
) {
signal.throwIfAborted();
const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
let error = "";
child.stderr.setEncoding("utf8");
child.stderr.on("data", (chunk: string) => {
error = (error + chunk).slice(-8192);
});
const exited = new Promise<number>((resolve, reject) => {
child.once("error", reject);
child.once("close", (code) => resolve(code ?? -1));
});
if (!child.pid) {
await exited;
throw new Error("Recording packet inspector could not start");
}
const managed = registerSubprocess({
pid: child.pid,
exited,
get exitCode() {
return child.exitCode;
},
kill: (signal?: NodeJS.Signals | number) => child.kill(signal),
});
const stop = () => {
child.kill("SIGKILL");
};
signal.addEventListener("abort", stop, { once: true });
child.stdout.setEncoding("utf8");
let pending = "";
try {
if (signal.aborted) stop();
for await (const chunk of child.stdout) {
if (typeof chunk !== "string")
throw new Error("Recording packet metadata is invalid");
pending += chunk;
let newline = pending.indexOf("\n");
while (newline !== -1) {
if (newline > 65536)
throw new Error("Recording packet metadata exceeds its bound");
signal.throwIfAborted();
line(pending.slice(0, newline).replace(/\r$/, ""));
pending = pending.slice(newline + 1);
newline = pending.indexOf("\n");
}
if (pending.length > 65536)
throw new Error("Recording packet metadata exceeds its bound");
}
if (pending) line(pending);
const code = await exited;
signal.throwIfAborted();
return { code, hasDiagnostics: Boolean(error) };
} finally {
stop();
signal.removeEventListener("abort", stop);
await exited.catch(() => {});
unregisterSubprocess(managed);
}
}
async function probe(
path: string,
args: string[],
signal: AbortSignal,
line: (value: string) => void,
) {
const result = await runInspector(
"ffprobe",
[
"-v",
"error",
"-err_detect",
"explode",
"-protocol_whitelist",
"file",
...args,
path,
],
signal,
line,
);
if (result.code !== 0 || result.hasDiagnostics)
throw new Error("Recording packet inspection failed");
}
function time(value: string | undefined, base: string) {
if (!value || !/^-?\d+$/.test(value))
throw new Error("Recording packet timestamp is missing");
const match = /^(\d+)\/(\d+)$/.exec(base);
if (!match || BigInt(match[1]) <= 0n || BigInt(match[2]) <= 0n)
throw new Error("Recording packet timebase is invalid");
const numerator = BigInt(value) * BigInt(match[1]);
let a = numerator < 0n ? -numerator : numerator;
let b = BigInt(match[2]);
while (b) [a, b] = [b, a % b];
return `${numerator / a}/${BigInt(match[2]) / a}`;
}
const positiveInteger = z
.number()
.int()
.positive()
.max(Number.MAX_SAFE_INTEGER);
const audioTailSchema = z.object({
packetCount: positiveInteger.optional(),
durationTicks: positiveInteger,
timeScale: positiveInteger,
size: positiveInteger,
hash: z.string().regex(/^SHA256:[a-f0-9]{64}$/),
});
export async function readRecordingAudioTail(
path: string,
signal: AbortSignal,
countPackets = false,
) {
try {
if (!isAbsolute(path))
throw new RecordingTimingError(
"Recording audio timing is invalid",
false,
);
let output = "";
const result = await runInspector(
process.execPath,
[
fileURLToPath(new URL("./recording-audio-timing.ts", import.meta.url)),
path,
countPackets ? "count" : "tail",
],
signal,
(line) => {
output += line;
if (output.length > 65536)
throw new Error("Audio timing metadata exceeds its bound");
},
);
const decoded: unknown = JSON.parse(output);
if (
result.code === 1 &&
typeof decoded === "object" &&
decoded !== null &&
"error" in decoded &&
decoded.error === "invalid"
)
throw new RecordingTimingError(
"Recording audio timing is invalid",
false,
);
const parsed = audioTailSchema.safeParse(decoded);
if (
result.code !== 0 ||
result.hasDiagnostics ||
!parsed.success ||
(countPackets && parsed.data.packetCount === undefined)
)
throw new Error("Recording audio timing response is invalid");
return {
...parsed.data,
duration: time(
String(parsed.data.durationTicks),
`1/${parsed.data.timeScale}`,
),
};
} catch (error) {
if (error instanceof RecordingTimingError) throw error;
const failure = new RecordingTimingError(
"Recording audio timing inspection was interrupted",
true,
);
failure.cause = error;
throw failure;
}
}
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 "packet proof differs, but the compact packet log did not capture the difference";
}
const MISMATCH_EXPLANATION_TIMEOUT_MS = 20_000;
// Packet logs are only collected in this second read, after a mismatch, so passing recordings pay nothing.
async function explainTrackMismatch(
sourcePath: string,
outputPath: string,
kind: "video" | "audio",
signal: AbortSignal,
): Promise<string> {
// Bounded so explaining a mismatch cannot run the verification into its deadline and hide the mismatch.
const explainSignal = AbortSignal.any([
signal,
AbortSignal.timeout(MISMATCH_EXPLANATION_TIMEOUT_MS),
]);
try {
const [source, output] = await Promise.all([
readTrack(sourcePath, kind, explainSignal, true),
readTrack(outputPath, kind, explainSignal, true),
]);
return describeTrackDifference(source, output);
} catch {
return "details unavailable";
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function configurationDifferences(
left: Record<string, unknown>,
right: Record<string, unknown>,
path = "",
): string[] {
const parts: string[] = [];
const value = (raw: unknown) => {
const text = JSON.stringify(raw) ?? "none";
return text.length > 40 ? `${text.slice(0, 37)}...` : text;
};
for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
if (JSON.stringify(left[key]) === JSON.stringify(right[key])) continue;
const [a, b] = [left[key], right[key]];
if (!path && (isRecord(a) || isRecord(b)))
parts.push(
...configurationDifferences(
isRecord(a) ? a : {},
isRecord(b) ? b : {},
`${key}.`,
),
);
else parts.push(`${path}${key} ${value(a)} vs ${value(b)}`);
}
return parts;
}
export function describeTrackDifference(
source: Pick<
Awaited<ReturnType<typeof readTrack>>,
"summary" | "log" | "timeBase"
>,
output: Pick<
Awaited<ReturnType<typeof readTrack>>,
"summary" | "log" | "timeBase"
>,
): string {
// Short, specific details go first so many changed tags cannot push them past the length cap.
const parts: string[] = [];
if (source.timeBase !== output.timeBase)
parts.push(`time base ${source.timeBase} vs ${output.timeBase}`);
if (
source.summary.packets !== output.summary.packets &&
source.log &&
output.log
)
parts.push(firstPacketDifference(source.log, output.log));
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}`,
);
parts.push(
...configurationDifferences(
source.summary.configuration as Record<string, unknown>,
output.summary.configuration as Record<string, unknown>,
),
);
return parts.join("; ").slice(0, 400) || "track summaries differ";
}
async function readTrack(
path: string,
kind: "video" | "audio",
signal: AbortSignal,
keepLog = false,
) {
if (!isAbsolute(path) || !(await lstat(path)).isFile())
throw new Error("Recording packet proof requires local regular files");
const selection = kind === "video" ? "v" : "a";
let metadata = "";
await probe(
path,
[
"-select_streams",
selection,
"-show_streams",
"-show_data_hash",
"sha256",
"-show_entries",
`stream=${STREAM_FIELDS}:stream_side_data`,
"-of",
"json",
],
signal,
(line) => {
metadata += line;
if (metadata.length > 65536)
throw new Error("Recording stream metadata exceeds its bound");
},
);
const parsed: unknown = JSON.parse(metadata);
if (
!parsed ||
typeof parsed !== "object" ||
!("streams" in parsed) ||
!Array.isArray(parsed.streams) ||
parsed.streams.length !== 1
)
throw new Error("Recording stream selection is ambiguous");
const stream = parsed.streams[0] as PacketStream;
if (
stream.codec_type !== kind ||
typeof stream.time_base !== "string" ||
!Number.isSafeInteger(stream.index) ||
typeof stream.extradata_hash !== "string" ||
!/^SHA256:[a-f0-9]{64}$/.test(stream.extradata_hash)
)
throw new Error("Recording codec configuration is incomplete");
const { index, time_base: base, start_pts: startPts, tags, ...rest } = stream;
// Remuxing a fragmented source into a regular MP4 drops its track creation_time, which is
// container metadata rather than anything in the encoded stream.
const { creation_time: _creationTime, ...keptTags } =
tags && typeof tags === "object" ? (tags as Record<string, unknown>) : {};
const start = time(String(startPts), base);
const configuration = {
...rest,
...(Object.keys(keptTags).length > 0 ? { tags: keptTags } : {}),
start,
};
const [startNumerator, startDenominator] = start.split("/").map(Number);
const startTime = startNumerator / startDenominator;
if (!Number.isFinite(startTime))
throw new Error("Recording start time is invalid");
const tail =
kind === "audio" ? await readRecordingAudioTail(path, signal) : undefined;
const hash = createHash("sha256");
const log = keepLog ? new PacketLog() : undefined;
let count = 0;
let pendingPacket: Record<string, string> | undefined;
const commitPacket = (fields: Record<string, string>, nextDts?: string) => {
let {
stream_index: _index,
pts,
dts,
duration,
flags,
...content
} = fields;
const skipSamples = Object.entries(content).find(
([key]) => key === "skip_samples" || key.endsWith(":skip_samples"),
)?.[1];
// FFmpeg can omit only the fully skipped first AAC packet's duration in fragmented MP4.
if (
duration === "N/A" &&
count === 0 &&
kind === "audio" &&
stream.codec_name === "aac" &&
pts === dts &&
/^-?\d+$/.test(dts ?? "") &&
typeof nextDts === "string" &&
/^-?\d+$/.test(nextDts) &&
/^[1-9]\d*$/.test(skipSamples ?? "") &&
typeof stream.sample_rate === "string" &&
/^[1-9]\d*$/.test(stream.sample_rate)
) {
const inferred = String(BigInt(nextDts) - BigInt(dts));
if (time(skipSamples, `1/${stream.sample_rate}`) === time(inferred, base))
duration = inferred;
}
// MP4 can mark an AAC priming packet discardable while retaining identical skip-sample metadata.
const packetFlags =
kind === "audio" &&
Object.entries(content).some(
([key, value]) =>
(key === "skip_samples" || key.endsWith(":skip_samples")) &&
/^\d+$/.test(value) &&
typeof stream.sample_rate === "string" &&
/^\d+$/.test(stream.sample_rate) &&
time(value, `1/${stream.sample_rate}`) === time(duration, base),
)
? flags?.replaceAll("D", "_")
: flags;
// FFmpeg 7 can replace a fragmented AAC tail's stored duration with its nominal frame duration.
if (
tail &&
nextDts === undefined &&
(String(tail.size) !== content.size || tail.hash !== content.data_hash)
)
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({
n: count++,
pts: time(pts, base),
dts: time(dts, base),
flags: packetFlags,
content,
}),
);
hash.update("\n");
};
await probe(
path,
[
"-select_streams",
selection,
"-show_packets",
"-show_data_hash",
"sha256",
"-show_entries",
"packet=stream_index,pts,dts,duration,size,flags,data_hash:packet_side_data",
"-of",
"compact",
],
signal,
(line) => {
if (!line.startsWith("packet|"))
throw new Error("Unexpected recording packet metadata");
const fields = Object.fromEntries(
line
.slice(7)
.split("|")
.map((field) => {
const separator = field.indexOf("=");
if (separator < 1)
throw new Error("Invalid recording packet metadata");
return [field.slice(0, separator), field.slice(separator + 1)];
}),
);
if (
Number(fields.stream_index) !== index ||
!/^[1-9]\d*$/.test(fields.size ?? "") ||
!/^SHA256:[a-f0-9]{64}$/.test(fields.data_hash ?? "")
)
throw new Error("Recording packet content is incomplete");
if (pendingPacket) commitPacket(pendingPacket, fields.dts);
pendingPacket = fields;
},
);
if (pendingPacket) commitPacket(pendingPacket);
if (!count) throw new Error("Recording stream contains no packets");
return {
summary: {
configuration,
count,
packets: hash.digest("hex"),
startTime,
tail,
},
log,
timeBase: base,
};
}
export async function proveRecordingPackets(
videoPath: string,
audioPath: string | null,
outputPath: string,
signal: AbortSignal,
) {
const paths = [
...new Set([videoPath, ...(audioPath ? [audioPath] : []), outputPath]),
];
const before = await Promise.all(
paths.map((path) => lstat(path, { bigint: true })),
);
// Every read below is independent and the files are pinned by `before`, so
// run them together and still check their results in the original order.
const reads = new AbortController();
const readSignal = AbortSignal.any([signal, reads.signal]);
const settled = <T>(promise: Promise<T>) => {
promise.catch(() => {});
return promise;
};
const timingOptions = { abortSignal: readSignal, timeoutMs: 45 * 60_000 };
const sourceTimingRead = settled(
readRecordingVideoTiming(videoPath, timingOptions),
);
const sourceVideoRead = settled(readTrack(videoPath, "video", readSignal));
const outputVideoRead = settled(readTrack(outputPath, "video", readSignal));
const sourceAudioRead = audioPath
? settled(readTrack(audioPath, "audio", readSignal))
: null;
const outputAudioRead = audioPath
? settled(readTrack(outputPath, "audio", readSignal))
: null;
const outputTimingRead = settled(
readRecordingVideoTiming(outputPath, timingOptions),
);
let sourceTiming: Awaited<typeof sourceTimingRead>;
let outputTiming: Awaited<typeof outputTimingRead>;
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).summary;
outputVideo = (await outputVideoRead).summary;
if (JSON.stringify(sourceVideo) !== JSON.stringify(outputVideo))
throw new RecordingPacketMismatchError(
`Recording encoded video does not preserve the source (${await explainTrackMismatch(videoPath, outputPath, "video", signal)})`,
);
if (audioPath && sourceAudioRead && outputAudioRead) {
const { tail: sourceTail, ...sourceAudio } = (await sourceAudioRead)
.summary;
const { tail: outputTail, ...outputAudio } = (await outputAudioRead)
.summary;
if (JSON.stringify(sourceAudio) !== JSON.stringify(outputAudio))
throw new RecordingPacketMismatchError(
`Recording encoded audio does not preserve the source (${await explainTrackMismatch(audioPath, outputPath, "audio", signal)})`,
);
// MP4 edit-list rounding can change the reported AAC tail without changing decoded samples.
if (sourceTail?.duration !== outputTail?.duration)
throw new Error(
"Recording audio tail requires decoded source evidence",
);
}
outputTiming = await outputTimingRead;
} finally {
reads.abort();
}
const normalizeTiming = (timing: typeof sourceTiming) => ({
packets: timing.packetTimelineSha256,
terminalPackets: timing.terminalPacketCount,
terminalContent: timing.terminalPacketSha256,
duration: time(String(timing.lastDurationTicks), `1/${timing.timeScale}`),
});
if (
JSON.stringify(normalizeTiming(sourceTiming)) !==
JSON.stringify(normalizeTiming(outputTiming))
)
throw new RecordingPacketMismatchError(
"Recording terminal packet timing changed",
);
const assertUnchanged = async () => {
for (const [index, path] of paths.entries()) {
const after = await lstat(path, { bigint: true });
const initial = before[index];
if (
!after.isFile() ||
after.dev !== initial.dev ||
after.ino !== initial.ino ||
after.size !== initial.size ||
after.mtimeNs !== initial.mtimeNs ||
after.ctimeNs !== initial.ctimeNs
)
throw new RecordingTimingError(
"Recording changed during packet verification",
false,
);
}
signal.throwIfAborted();
};
await assertUnchanged();
return {
hasAudio: Boolean(audioPath),
videoPackets: sourceVideo.count,
videoStartTime: outputVideo.startTime,
outputTiming,
assertUnchanged,
};
}