Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs(testing): compare 2.0.0 and main performance on Windows

EtienneLescote92a7527d6be
diff --git a/scripts/perf-ab/analyze_capture.py b/scripts/perf-ab/analyze_capture.py
new file mode 100644
index 000000000..f2af2d7b8
--- /dev/null
+++ b/scripts/perf-ab/analyze_capture.py
@@ -0,0 +1,109 @@
+"""What the screen showed: cursor and screen-frame pacing in a ddagrab capture of the light preview.
+
+The light project's screen video has a white bar that moves 16 source px per frame (60 fps) in its
+top band, and a cursor that sweeps horizontally at constant speed (0.7 width per 2 s). In each
+captured desktop frame we locate both. A preview update = either moved. Reports update intervals,
+screen frames advanced per update (1 = clean, 0 = repeat, 2+ = skipped), and the cursor's deviation
+from a straight line on each constant-speed leg (the "fidget").
+
+usage: python -I analyze_capture.py <cap.mkv> [analyse_seconds]
+"""
+import json
+import subprocess
+import sys
+
+import numpy as np
+
+path = sys.argv[1]
+span = float(sys.argv[2]) if len(sys.argv) > 2 else 18.0
+
+info = json.loads(subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height", "-of", "json", path]))
+W, H = info["streams"][0]["width"], info["streams"][0]["height"]
+pts = np.array([float(x) for x in subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "frame=pts_time", "-of", "csv=p=0", path], text=True).split()])
+# Geometry, not detection: the bar lives in the top quarter of the screen, the cursor at 62% height.
+bar_rows = (int(H * 0.03), int(H * 0.25))
+cur_rows = (int(H * 0.45), int(H * 0.85))
+cols_idx = np.arange(W)
+
+
+def xpos(frame, rr):
+ sub = frame[rr[0] : rr[1], 4 : W - 4] > 190
+ col = sub.sum(axis=0)
+ cnt = col.sum()
+ return (col * cols_idx[4 : W - 4]).sum() / cnt if cnt > 3 else np.nan
+
+
+# Streamed one frame at a time: 30 s at 280 fps would be gigabytes held at once.
+proc = subprocess.Popen(["ffmpeg", "-v", "fatal", "-i", path, "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
+bar, cur = [], []
+size = W * H
+while True:
+ buf = proc.stdout.read(size)
+ if len(buf) < size:
+ break
+ f = np.frombuffer(buf, dtype=np.uint8).reshape(H, W)
+ bar.append(xpos(f, bar_rows))
+ cur.append(xpos(f, cur_rows))
+proc.wait()
+assert len(bar) == len(pts), (len(bar), len(pts))
+n = len(bar)
+bar, cur = np.array(bar), np.array(cur)
+
+# Playback starts at the first frame where the cursor moves.
+moved = np.where(np.abs(np.diff(cur)) > 0.5)[0]
+t_start = pts[moved[0] + 1] if len(moved) else pts[0]
+sel = (pts >= t_start) & (pts <= t_start + span)
+t, bar, cur = pts[sel] - t_start, bar[sel], cur[sel]
+
+# Bar travel across the screen width gives the capture-px per source-px scale.
+bar_range = np.nanmax(bar) - np.nanmin(bar)
+scale = bar_range / (1920 - 8)
+step = 16 * scale
+
+upd_bar = np.abs(np.diff(bar)) > 0.5
+upd_cur = np.abs(np.diff(cur)) > 0.5
+upd = np.where(upd_bar | upd_cur)[0] + 1
+ut = t[upd]
+intervals = np.diff(ut) * 1000
+
+adv = np.diff(bar[np.r_[0, upd]])
+adv = np.where(adv < -bar_range / 2, adv + bar_range + 8 * scale, adv)
+adv = adv[~np.isnan(adv)]
+adv_frames = np.rint(adv / step).astype(int)
+
+# Cursor legs: constant speed between turnarounds every 2 s of programme time. Fit a line per leg
+# on the cursor's own updates, leaving 250 ms at each end for the smoothed turn.
+cu = np.where(upd_cur)[0] + 1
+ct, cx = t[cu], cur[cu]
+resid, backward, legs = [], 0, 0
+for k in range(int(span // 2) + 1):
+ m = (ct > k * 2 + 0.25) & (ct < k * 2 + 1.75)
+ if m.sum() < 20:
+ continue
+ legs += 1
+ p = np.polyfit(ct[m], cx[m], 1)
+ resid.extend((cx[m] - np.polyval(p, ct[m])) / scale)
+ d = np.diff(cx[m])
+ backward += int(np.sum(np.sign(d) == -np.sign(p[0])))
+resid = np.abs(np.array(resid))
+
+
+def q(a, p):
+ return float(np.percentile(a, p)) if len(a) else None
+
+
+out = {
+ "file": path,
+ "frames": int(n),
+ "spanSec": span,
+ "scaleCapturePxPerSourcePx": float(scale),
+ "updates": int(len(upd)),
+ "updateHz": float(len(upd) / (ut[-1] - ut[0])) if len(ut) > 1 else None,
+ "updateIntervalMs": {"p50": q(intervals, 50), "p95": q(intervals, 95), "p99": q(intervals, 99), "max": float(intervals.max()) if len(intervals) else None, "over25ms": int((intervals > 25).sum()), "over34ms": int((intervals > 34).sum())},
+ "screenFramesPerUpdate": {str(k): int(v) for k, v in zip(*np.unique(np.clip(adv_frames, -1, 4), return_counts=True))},
+ "cursorUpdates": int(len(cu)),
+ "cursorResidualSourcePx": {"rms": float(np.sqrt(np.mean(resid**2))) if len(resid) else None, "p95": q(resid, 95), "p99": q(resid, 99), "max": float(resid.max()) if len(resid) else None},
+ "cursorBackwardSteps": backward,
+ "legs": legs,
+}
+print(json.dumps(out))
diff --git a/scripts/perf-ab/analyze_recording.py b/scripts/perf-ab/analyze_recording.py
new file mode 100644
index 000000000..e4cd9d0e3
--- /dev/null
+++ b/scripts/perf-ab/analyze_recording.py
@@ -0,0 +1,64 @@
+"""Dropped and duplicated frames in a take recorded over the 120 fps bar pattern.
+
+Screen: the bar advances 16 px per pattern frame, so each 60 fps recorded frame should advance it
+by 2 pattern frames. 0 = duplicated frame, >= 4 = at least one recorded frame lost.
+Webcam: timestamp gaps, and byte-identical consecutive decoded frames (a live camera never
+repeats a frame exactly, so an identical one is a duplicate the pipeline inserted).
+
+usage: python analyze_recording.py <screen.mp4> [webcam.mp4]
+"""
+import json
+import subprocess
+import sys
+
+import numpy as np
+
+
+def probe(path):
+ j = json.loads(subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=codec_name,width,height,r_frame_rate,avg_frame_rate,bit_rate:format=duration", "-of", "json", path]))
+ pts = np.array(sorted(float(x) for x in subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0", path], text=True).split() if x not in ("", "N/A")))
+ s = j["streams"][0]
+ d = np.diff(pts) * 1000
+ nominal = 1000 / eval(s["r_frame_rate"]) if s["r_frame_rate"] != "0/0" else float(np.median(d))
+ return {
+ "codec": s["codec_name"], "width": s["width"], "height": s["height"], "rFrameRate": s["r_frame_rate"], "avgFrameRate": s["avg_frame_rate"],
+ "bitRate": int(s.get("bit_rate", 0) or 0), "duration": float(j["format"]["duration"]), "frames": int(len(pts)),
+ "fps": float((len(pts) - 1) / (pts[-1] - pts[0])) if len(pts) > 1 else None,
+ "gapsOver1_5x": int((d > 1.5 * nominal).sum()), "maxGapMs": float(d.max()) if len(d) else None,
+ }, s
+
+
+def screen(path):
+ info, s = probe(path)
+ W, H = s["width"], s["height"]
+ w, h = 960, int(960 * H / W) // 2 * 2
+ raw = subprocess.check_output(["ffmpeg", "-v", "fatal", "-i", path, "-fps_mode", "passthrough", "-vf", f"scale={w}:{h}", "-f", "rawvideo", "-pix_fmt", "gray", "-"])
+ f = np.frombuffer(raw, dtype=np.uint8).reshape(-1, h, w)[:, int(h * 0.3) : int(h * 0.7), :]
+ b = f > 190
+ c = b.sum(axis=(1, 2))
+ x = np.where(c > 10, (b.sum(axis=1) * np.arange(w)).sum(axis=1) / np.maximum(c, 1), np.nan)
+ step = 16 * w / 1920
+ rng = 1904 * w / 1920
+ d = np.diff(x)
+ d = np.where(d < -rng / 2, d + rng, d)
+ adv = np.rint(d / step)
+ adv = adv[~np.isnan(adv)].astype(int)
+ vals, cnt = np.unique(np.clip(adv, -1, 8), return_counts=True)
+ info["patternFramesPerFrame"] = {str(k): int(v) for k, v in zip(vals, cnt)}
+ info["duplicated"] = int((adv == 0).sum())
+ info["droppedAtLeast"] = int(np.clip(adv - 3, 0, None).sum())
+ return info
+
+
+def webcam(path):
+ info, s = probe(path)
+ md5 = subprocess.check_output(["ffmpeg", "-v", "fatal", "-i", path, "-fps_mode", "passthrough", "-vf", "scale=320:-2", "-f", "framemd5", "-"], text=True).splitlines()
+ hashes = [l.rsplit(",", 1)[-1].strip() for l in md5 if l and not l.startswith("#")]
+ info["identicalConsecutive"] = int(sum(1 for i in range(1, len(hashes)) if hashes[i] == hashes[i - 1]))
+ return info
+
+
+out = {"screen": screen(sys.argv[1])}
+if len(sys.argv) > 2:
+ out["webcam"] = webcam(sys.argv[2])
+print(json.dumps(out))
diff --git a/scripts/perf-ab/cdp.mjs b/scripts/perf-ab/cdp.mjs
new file mode 100644
index 000000000..ba3effe0f
--- /dev/null
+++ b/scripts/perf-ab/cdp.mjs
@@ -0,0 +1,65 @@
+// Minimal Chrome DevTools Protocol client over Node's global WebSocket.
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function listTargets(port) {
+ try {
+ const res = await fetch(`http://127.0.0.1:${port}/json/list`);
+ return await res.json();
+ } catch {
+ return null;
+ }
+}
+
+/** Polls until `pick(targets)` returns a page target, or throws after timeoutMs. */
+export async function waitTarget(port, pick, timeoutMs = 60000, everyMs = 20) {
+ const end = Date.now() + timeoutMs;
+ while (Date.now() < end) {
+ const targets = await listTargets(port);
+ const t = targets && pick(targets.filter((x) => x.type === "page"));
+ if (t) return t;
+ await sleep(everyMs);
+ }
+ throw new Error("target not found in time");
+}
+
+export async function connect(target) {
+ const ws = new WebSocket(target.webSocketDebuggerUrl);
+ await new Promise((ok, ko) => {
+ ws.onopen = ok;
+ ws.onerror = ko;
+ });
+ let next = 1;
+ const pending = new Map();
+ const listeners = [];
+ ws.onmessage = (ev) => {
+ const msg = JSON.parse(ev.data);
+ if (msg.id && pending.has(msg.id)) {
+ const { ok, ko } = pending.get(msg.id);
+ pending.delete(msg.id);
+ msg.error ? ko(new Error(JSON.stringify(msg.error))) : ok(msg.result);
+ } else if (msg.method) {
+ for (const l of listeners) l(msg);
+ }
+ };
+ const send = (method, params = {}) =>
+ new Promise((ok, ko) => {
+ const id = next++;
+ pending.set(id, { ok, ko });
+ ws.send(JSON.stringify({ id, method, params }));
+ });
+ const evaluate = async (expression) => {
+ const r = await send("Runtime.evaluate", {
+ expression,
+ awaitPromise: true,
+ returnByValue: true,
+ });
+ if (r.exceptionDetails)
+ throw new Error(`eval failed: ${JSON.stringify(r.exceptionDetails).slice(0, 400)}`);
+ return r.result.value;
+ };
+ const key = async (key, code, vk) => {
+ await send("Input.dispatchKeyEvent", { type: "keyDown", key, code, windowsVirtualKeyCode: vk });
+ await send("Input.dispatchKeyEvent", { type: "keyUp", key, code, windowsVirtualKeyCode: vk });
+ };
+ return { send, evaluate, key, on: (fn) => listeners.push(fn), close: () => ws.close() };
+}
diff --git a/scripts/perf-ab/compare.mjs b/scripts/perf-ab/compare.mjs
new file mode 100644
index 000000000..6df627ad2
--- /dev/null
+++ b/scripts/perf-ab/compare.mjs
@@ -0,0 +1,53 @@
+// Markdown rows "metric | 2.0.0 | main | delta | verdict" from an aggregate { "<group>|v200": {...}, "<group>|main": {...} }.
+// A regression is a change over 5% in the bad direction that is real: with 6 runs or more per side,
+// a Mann-Whitney test at p < 0.05 (two-sided); with fewer, [min-max] ranges that do not overlap.
+// Over 5% without that is reported as within noise.
+
+/** Normal approximation of the Mann-Whitney U test: z of "b tends to be larger than a". */
+export function mannWhitneyZ(a, b) {
+ let u = 0;
+ for (const x of b) for (const y of a) u += x > y ? 1 : x === y ? 0.5 : 0;
+ const n1 = a.length;
+ const n2 = b.length;
+ return (u - (n1 * n2) / 2) / Math.sqrt((n1 * n2 * (n1 + n2 + 1)) / 12);
+}
+export function compareRows(agg, group, metrics) {
+ const a = agg[`${group}|v200`];
+ const b = agg[`${group}|main`];
+ const rows = [];
+ for (const [key, label, better, digits = 1] of metrics) {
+ const x = a?.[key];
+ const y = b?.[key];
+ if (!x && !y) continue;
+ const fmt = (v) =>
+ v ? `${v.med.toFixed(digits)} [${v.min.toFixed(digits)}–${v.max.toFixed(digits)}]` : "n/a";
+ let delta = "n/a";
+ let verdict = "n/a";
+ let tested = false;
+ let z = 0;
+ if (x && y) {
+ const d =
+ x.med === 0
+ ? y.med === 0
+ ? 0
+ : Number.POSITIVE_INFINITY
+ : ((y.med - x.med) / Math.abs(x.med)) * 100;
+ delta = Number.isFinite(d)
+ ? `${d >= 0 ? "+" : ""}${d.toFixed(1)}%`
+ : `${x.med.toFixed(digits)} → ${y.med.toFixed(digits)}`;
+ const worse = better === "lower" ? d > 5 : d < -5;
+ const improved = better === "lower" ? d < -5 : d > 5;
+ tested = x.vals?.length >= 6 && y.vals?.length >= 6;
+ z = tested ? mannWhitneyZ(x.vals, y.vals) : 0;
+ const overlap = tested ? Math.abs(z) < 1.96 : !(y.min > x.max || y.max < x.min);
+ if (better === "info") verdict = "info";
+ else if (worse) verdict = overlap ? "within noise" : "**regression**";
+ else if (improved) verdict = overlap ? "within noise" : "improvement";
+ else verdict = tested && Math.abs(z) >= 1.96 ? "under 5%, but significant" : "same";
+ }
+ if (tested && /regression|improvement|noise/.test(verdict))
+ verdict += ` (p ${Math.abs(z) >= 1.96 ? "<" : "≥"} 0.05)`;
+ rows.push(`| ${label} | ${fmt(x)} | ${fmt(y)} | ${delta} | ${verdict} |`);
+ }
+ return rows;
+}
diff --git a/scripts/perf-ab/doc-tables.mjs b/scripts/perf-ab/doc-tables.mjs
new file mode 100644
index 000000000..7e7284dba
--- /dev/null
+++ b/scripts/perf-ab/doc-tables.mjs
@@ -0,0 +1,124 @@
+// The curated tables of the results log, straight from the summaries (no hand copying).
+import fs from "node:fs";
+import { compareRows } from "./compare.mjs";
+
+const [guiSummary, recordSummary, exportResults] = process.argv.slice(2);
+const { agg } = JSON.parse(fs.readFileSync(guiSummary, "utf8"));
+const head = "| Metric | 2.0.0 | main | Delta | Verdict |\n|---|---|---|---|---|";
+const out = [];
+const table = (title, a, group, rows) => {
+ out.push(`#### ${title}\n\n${head}`);
+ out.push(...compareRows(a, group, rows));
+ out.push("");
+};
+table("Preview, light project (3 sessions each)", agg, "light|279", [
+ ["paintFps", "Preview paints per second", "higher"],
+ ["paintP95", "Paint interval p95 (ms)", "lower"],
+ ["paintP99", "Paint interval p99 (ms)", "lower"],
+ ["paintOver25", "Paints later than 25 ms, per 30 s", "lower", 0],
+ ["rafP99", "UI rAF interval p99 (ms)", "lower", 2],
+ ["rafOverBudgetPct", "UI rAF over 1.5 vsync (%)", "lower", 2],
+ ["cpuTotal", "CPU, all processes (% of one core)", "lower"],
+ ["cpuMain", "CPU, main process (%)", "lower"],
+ ["gpuAll", "GPU, all engines of the app (%)", "lower"],
+ ["screenUpdateHz", "On screen: preview updates per second", "higher"],
+ ["screenUpdP99", "On screen: update interval p99 (ms)", "lower"],
+ ["screenSkipPct", "On screen: updates skipping a video frame (%)", "lower", 2],
+ ["cursorRmsPx", "On screen: cursor off its path, RMS (source px)", "lower", 2],
+ ["cursorP99Px", "On screen: cursor off its path, p99 (source px)", "lower", 2],
+ ["cursorBackward", "On screen: cursor steps backwards", "lower", 0],
+]);
+table("Preview, heavy project (12 sessions each; memory on 3)", agg, "heavy|279", [
+ ["paintFps", "Preview paints per second", "higher"],
+ ["paintP95", "Paint interval p95 (ms)", "lower"],
+ ["paintP99", "Paint interval p99 (ms)", "lower"],
+ ["paintOver25", "Paints later than 25 ms, per 30 s", "lower", 0],
+ ["rafP99", "UI rAF interval p99 (ms)", "lower", 2],
+ ["longTasks", "Long tasks over 50 ms, per 30 s", "lower", 0],
+ ["cpuTotal", "CPU, all processes (% of one core)", "lower"],
+ ["cpuMain", "CPU, main process (%)", "lower"],
+ ["cpuGpuProc", "CPU, GPU process (%)", "lower"],
+ ["cpuRenderer", "CPU, renderer (%)", "lower"],
+ ["gpu3dMain", "GPU 3D, main process / compositor (%)", "lower"],
+ ["gpuVideoDecode", "GPU video decode (%)", "lower"],
+ ["gpuAll", "GPU, all engines of the app (%)", "lower"],
+ ["memPrivMB", "Private memory after 2 min (MB)", "lower", 0],
+ ["memMainPrivMB", "Private memory, main process (MB)", "lower", 0],
+ ["memRendererPrivMB", "Private memory, renderer (MB)", "lower", 0],
+ ["gpuDedicatedGpuProcMB", "GPU dedicated memory, GPU process, after 2 min (MB)", "lower", 0],
+ ["editorOpenMs", "Editor open to first preview frame (ms)", "lower", 0],
+]);
+// Startup is the same measurement in every session: pool light and heavy.
+const pooled = {};
+const runs = JSON.parse(fs.readFileSync(guiSummary, "utf8")).runs.filter((r) => r.ok);
+for (const ver of ["v200", "main"]) {
+ const v = runs
+ .filter((r) => r.ver === ver)
+ .map((r) => r.startupToHudMs)
+ .sort((x, y) => x - y);
+ const h = v.length >> 1;
+ pooled[`startup|${ver}`] = {
+ startupToHudMs: {
+ med: v.length % 2 ? v[h] : (v[h - 1] + v[h]) / 2,
+ min: v[0],
+ max: v.at(-1),
+ vals: v,
+ },
+ };
+}
+table("Startup (15 sessions each)", pooled, "startup", [
+ ["startupToHudMs", "Process start to HUD ready (ms)", "lower", 0],
+]);
+const rec = JSON.parse(fs.readFileSync(recordSummary, "utf8")).agg;
+table("Recording, 60 s full screen with the webcam (3 takes each)", rec, "record", [
+ ["screenFps", "Screen video, frames per second", "info", 2],
+ ["screenMaxGapMs", "Screen video, longest gap between frames (ms)", "lower"],
+ ["screenRepeated", "Screen video, frames repeating the previous picture", "lower", 0],
+ ["camFps", "Webcam video, frames per second", "info", 2],
+ ["camMaxGapMs", "Webcam video, longest gap (ms)", "lower"],
+ ["camIdentical", "Webcam video, byte-identical consecutive frames", "lower", 0],
+ ["cpuWgc", "CPU, wgc-capture.exe (% of one core)", "lower"],
+ ["cpuMain", "CPU, main process (%)", "lower"],
+ ["cpuTotal", "CPU, all processes (%)", "lower"],
+]);
+const ex = fs
+ .readFileSync(exportResults, "utf8")
+ .trim()
+ .split("\n")
+ .map(JSON.parse)
+ .filter((r) => r.ok);
+const exAgg = {};
+for (const c of ["mp4-1080p60", "mp4-1080p30", "gif-medium-15"]) {
+ for (const ver of ["v200", "main"]) {
+ let g = ex.filter((r) => r.case === c && r.ver === ver);
+ const warm = g.filter((r) => r.rep > 0);
+ if (warm.length >= 2) g = warm; // the warm-up run counts only where a case has too few others
+ if (!g.length) continue;
+ const stat = (vals) => {
+ const s = [...vals].sort((x, y) => x - y);
+ const h = s.length >> 1;
+ return { med: s.length % 2 ? s[h] : (s[h - 1] + s[h]) / 2, min: s[0], max: s.at(-1) };
+ };
+ exAgg[`${c}|${ver}`] = {
+ wallSec: stat(g.map((r) => r.wallSec)),
+ frames: stat(g.map((r) => r.output.frames)),
+ realtime: stat(g.map((r) => r.output.duration / r.wallSec)),
+ n: g.length,
+ };
+ }
+}
+out.push(`#### Export, heavy project (60 s)\n\n${head}`);
+for (const [c, label] of [
+ ["mp4-1080p60", "MP4 1080p 60 fps"],
+ ["mp4-1080p30", "MP4 1080p 30 fps"],
+ ["gif-medium-15", "GIF 720p 15 fps"],
+]) {
+ out.push(
+ ...compareRows(exAgg, c, [
+ ["wallSec", `${label}: wall time (s)`, "lower"],
+ ["frames", `${label}: frames written`, "info", 0],
+ ["realtime", `${label}: times real time`, "higher", 2],
+ ]),
+ );
+}
+console.log(out.join("\n"));
diff --git a/scripts/perf-ab/export-bench.mjs b/scripts/perf-ab/export-bench.mjs
new file mode 100644
index 000000000..4675cd5b8
--- /dev/null
+++ b/scripts/perf-ab/export-bench.mjs
@@ -0,0 +1,179 @@
+// CLI export benchmark: wall time, output frames/fps, CPU seconds and peak memory of the process tree.
+// node export-bench.mjs <scratch> <reps> — runs interleaved v200/main for each case.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+process.on("uncaughtException", (e) => {
+ console.error(e);
+ process.exit(1);
+});
+
+const [scratch, repsArg] = process.argv.slice(2);
+const reps = Number(repsArg ?? 3);
+const HERE = path.dirname(new URL(import.meta.url).pathname).replace(/^\/([A-Za-z]:)/, "$1");
+const project = fs
+ .readdirSync(path.join(scratch, "projects"))
+ .map((f) => path.join(scratch, "projects", f))
+ .sort((x, y) => fs.statSync(y).size - fs.statSync(x).size)[0]; // heavy
+const outDir = path.join(scratch, "out", "export");
+fs.mkdirSync(outDir, { recursive: true });
+
+const cases = [
+ {
+ id: "mp4-1080p60",
+ ext: "mp4",
+ args: { v200: ["--quality", "good"], main: ["--quality", "good", "--fps", "60"] },
+ },
+ { id: "mp4-1080p30", ext: "mp4", args: { main: ["--quality", "good", "--fps", "30"] } },
+ {
+ id: "gif-medium-15",
+ ext: "gif",
+ args: {
+ v200: ["--format", "gif", "--gif-size", "medium", "--gif-fps", "15"],
+ main: ["--format", "gif", "--gif-size", "medium", "--gif-fps", "15"],
+ },
+ },
+];
+
+const procsnap = (root) =>
+ JSON.parse(
+ execFileSync(
+ "powershell",
+ [
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ path.join(HERE, "procsnap.ps1"),
+ "-Root",
+ root,
+ ],
+ { encoding: "utf8" },
+ ) || "[]",
+ );
+
+const probe = (file) => {
+ const j = JSON.parse(
+ execFileSync(
+ "ffprobe",
+ [
+ "-v",
+ "error",
+ "-count_packets",
+ "-select_streams",
+ "v:0",
+ "-show_entries",
+ "stream=nb_read_packets,avg_frame_rate,r_frame_rate,width,height,duration:format=duration,size",
+ "-of",
+ "json",
+ file,
+ ],
+ { encoding: "utf8" },
+ ),
+ );
+ const s = j.streams[0];
+ return {
+ frames: Number(s.nb_read_packets),
+ avgFps: s.avg_frame_rate,
+ width: s.width,
+ height: s.height,
+ duration: Number(s.duration ?? j.format.duration),
+ size: Number(j.format.size),
+ };
+};
+
+async function runOne(ver, c, rep) {
+ const app = path.join(scratch, `app-${ver}`);
+ const out = path.join(outDir, `${c.id}-${ver}-r${rep}.${c.ext}`);
+ fs.rmSync(out, { force: true });
+ const t0 = performance.now();
+ const p = spawn(
+ path.join(app, "Openscreen.exe"),
+ [
+ `--user-data-dir=${path.join(scratch, "profiles", `export-${ver}`)}`,
+ "export",
+ project,
+ "-o",
+ out,
+ ...c.args[ver],
+ "--json",
+ ],
+ { stdio: ["ignore", "pipe", "ignore"] },
+ );
+ let stdout = "";
+ p.stdout.on("data", (b) => (stdout += b));
+ const seen = new Map();
+ let done = false;
+ p.on("exit", () => (done = true));
+ while (!done) {
+ for (const s of procsnap(app)) {
+ const prev = seen.get(s.pid);
+ seen.set(s.pid, {
+ role: s.role,
+ cpuSec: s.cpuSec,
+ peakWs: Math.max(s.peakWs, prev?.peakWs ?? 0),
+ priv: Math.max(s.priv, prev?.priv ?? 0),
+ });
+ }
+ await new Promise((r) => setTimeout(r, 500));
+ }
+ const wallSec = (performance.now() - t0) / 1000;
+ const last = stdout
+ .trim()
+ .split("\n")
+ .filter(Boolean)
+ .map((l) => {
+ try {
+ return JSON.parse(l);
+ } catch {
+ return null;
+ }
+ })
+ .filter(Boolean)
+ .pop();
+ const procs = [...seen.values()];
+ const r = {
+ case: c.id,
+ ver,
+ rep,
+ wallSec,
+ ok: last?.event === "done" && last.success === true,
+ cpuSec: procs.reduce((s, x) => s + x.cpuSec, 0),
+ cpuByRole: Object.fromEntries(
+ Object.entries(Object.groupBy(procs, (x) => x.role)).map(([k, v]) => [
+ k,
+ v.reduce((s, x) => s + x.cpuSec, 0),
+ ]),
+ ),
+ peakWsSum: procs.reduce((s, x) => s + x.peakWs, 0),
+ maxPriv: Math.max(...procs.map((x) => x.priv)),
+ output: fs.existsSync(out) ? probe(out) : null,
+ };
+ fs.appendFileSync(path.join(outDir, "results.ndjson"), `${JSON.stringify(r)}\n`);
+ console.log(
+ JSON.stringify({
+ case: r.case,
+ ver,
+ rep,
+ ok: r.ok,
+ wallSec: r.wallSec.toFixed(1),
+ cpuSec: r.cpuSec.toFixed(1),
+ frames: r.output?.frames,
+ dur: r.output?.duration,
+ }),
+ );
+ if (c.ext === "mp4" && rep > 1) fs.rmSync(out, { force: true }); // keep one sample per case, C: is tight
+}
+
+// FROM_REP resumes a series; SKIP=case:ver,... leaves out cases already measured enough.
+const fromRep = Number(process.env.FROM_REP ?? 0);
+const skip = new Set((process.env.SKIP ?? "").split(",").filter(Boolean));
+for (let rep = fromRep; rep <= reps; rep++) {
+ // rep 0 = warm-up (shader caches, disk cache), discarded by the analysis
+ for (const c of cases) {
+ const vers = rep % 2 ? ["main", "v200"] : ["v200", "main"];
+ for (const ver of vers)
+ if (c.args[ver] && !skip.has(`${c.id}:${ver}`)) await runOne(ver, c, rep);
+ }
+}
diff --git a/scripts/perf-ab/gen-projects.mjs b/scripts/perf-ab/gen-projects.mjs
new file mode 100644
index 000000000..6bd887eb7
--- /dev/null
+++ b/scripts/perf-ab/gen-projects.mjs
@@ -0,0 +1,309 @@
+// Builds the two benchmark projects (schema 8, readable by v2.0.0 and main) and the cursor sidecar.
+// usage: node gen-projects.mjs <mediaDir> <outDir>
+//
+// The media first, in <mediaDir>:
+// ffmpeg -f lavfi -i "color=c=0x303030:s=1920x1080:r=60:d=60" -f lavfi -i "color=c=white:s=8x80:r=60:d=60"
+// -f lavfi -i "sine=f=440:d=60,volume=-30dB"
+// -filter_complex "[0:v]noise=alls=12:allf=t[bg];[bg][1:v]overlay=x='mod(n*16\,1920)':y=40[v]"
+// -map "[v]" -map 2:a -c:v libx264 -preset fast -profile:v high -pix_fmt yuv420p
+// -b:v 14M -maxrate 16M -bufsize 28M -g 120 -c:a aac -b:a 128k screen.mp4
+// ffmpeg -f lavfi -i "testsrc2=s=1920x1080:r=30:d=60" -vf "noise=alls=10:allf=t" -c:v libx264
+// -preset fast -profile:v high -pix_fmt yuv420p -b:v 16M -maxrate 18M -bufsize 32M -g 60 webcam.mp4
+// ffmpeg -f lavfi -i "sine=f=220:d=60" -f lavfi -i "sine=f=330:d=60"
+// -filter_complex "amix=inputs=2,volume=0.5" -c:a libmp3lame -b:a 128k music.mp3
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const [mediaDir, outDir] = process.argv.slice(2).map((p) => path.resolve(p));
+fs.mkdirSync(outDir, { recursive: true });
+const DUR = 60;
+const screen = path.join(mediaDir, "screen.mp4");
+const webcam = path.join(mediaDir, "webcam.mp4");
+const music = path.join(mediaDir, "music.mp3");
+const now = "2026-10-15T15:00:00.000Z";
+
+// Cursor: horizontal triangle sweep 0.15 -> 0.85 -> 0.15, 4 s period, y fixed, sampled every 8 ms.
+// Constant speed between turns, so any jitter in the preview is a timing error, not the input.
+const samples = [];
+for (let t = 0; t <= DUR * 1000; t += 8) {
+ const phase = (t % 4000) / 2000; // 0..2
+ const u = phase <= 1 ? phase : 2 - phase;
+ samples.push({
+ timeMs: t,
+ cx: 0.15 + 0.7 * u,
+ cy: 0.62,
+ visible: true,
+ cursorType: "arrow",
+ interactionType: "move",
+ });
+}
+fs.writeFileSync(
+ `${screen}.cursor.json`,
+ JSON.stringify({ version: 2, provider: "native", samples, assets: [] }),
+);
+
+const id = (p) => `${p}_${randomUUID()}`;
+const anchor = (clipId, a, b) => ({
+ clipId,
+ sourceStartSec: a,
+ sourceEndSec: b,
+ startMs: a * 1000,
+ endMs: b * 1000,
+});
+
+function baseDoc(title, withCamera) {
+ const assetId = id("asset");
+ const clipId = id("clip");
+ return {
+ assetId,
+ clipId,
+ doc: {
+ schemaVersion: 8,
+ project: { id: id("proj"), title, createdAt: now, updatedAt: now, primaryAssetId: assetId },
+ assets: [
+ {
+ id: assetId,
+ kind: "video",
+ label: "screen.mp4",
+ originalPath: screen,
+ durationSec: DUR,
+ sizeBytes: fs.statSync(screen).size,
+ video: { codec: "h264", width: 1920, height: 1080, fps: 60 },
+ cameraTrack: withCamera
+ ? {
+ sourcePath: webcam,
+ startMs: 0,
+ offsetMs: 0,
+ visible: true,
+ width: 1920,
+ height: 1080,
+ }
+ : null,
+ },
+ ],
+ transcript: null,
+ transcripts: [],
+ timeline: {
+ clips: [
+ {
+ id: clipId,
+ assetId,
+ sourceStartSec: 0,
+ sourceEndSec: DUR,
+ timelineStartSec: 0,
+ timelineEndSec: DUR,
+ wordRefs: [],
+ origin: "user",
+ reason: "bench",
+ },
+ ],
+ gaps: [],
+ trimRanges: [],
+ muteRanges: [],
+ speedRanges: [],
+ captionRanges: [],
+ },
+ annotations: [],
+ zoomRanges: [],
+ audioTracks: [],
+ legacyEditor: null,
+ },
+ };
+}
+
+// Light: one take, one zoom, plain dark wallpaper, no cursor motion blur (keeps the cursor detectable).
+{
+ const { doc, clipId } = baseDoc("bench-light", false);
+ doc.zoomRanges.push({
+ id: id("zoom"),
+ ...anchor(clipId, 20, 26),
+ depth: 2,
+ focus: { cx: 0.5, cy: 0.5 },
+ focusMode: "manual",
+ source: "manual",
+ });
+ doc.legacyEditor = {
+ aspectRatio: "16:9",
+ wallpaper: "#101010",
+ padding: 10,
+ borderRadius: 0,
+ shadowIntensity: 0,
+ motionBlurAmount: 0,
+ autoZoomEnabled: false,
+ cursorSize: 1.5,
+ cursorSmoothing: 0.5,
+ cursorMotionBlur: 0,
+ cursorClickBounce: 0,
+ webcamLayoutPreset: "no-webcam",
+ };
+ fs.writeFileSync(path.join(outDir, `${doc.project.id}.openscreen`), JSON.stringify(doc, null, 1));
+ console.log("light", doc.project.id);
+}
+
+// Heavy: webcam PiP, five zooms (three 3D), text + arrow + blur annotations, captions on, a music bed.
+{
+ const { doc, clipId, assetId } = baseDoc("bench-heavy", true);
+ const z = (a, b, depth, extra) => ({
+ id: id("zoom"),
+ ...anchor(clipId, a, b),
+ depth,
+ focus: { cx: 0.5, cy: 0.5 },
+ focusMode: "manual",
+ source: "manual",
+ ...extra,
+ });
+ doc.zoomRanges.push(
+ z(4, 9, 2, { focus: { cx: 0.3, cy: 0.4 } }),
+ z(12, 17, 3, { rotationPreset: "orbit" }),
+ z(22, 27, 2, { rotationPreset: "left", focus: { cx: 0.7, cy: 0.6 } }),
+ z(35, 41, 4, { focusMode: "auto" }),
+ z(48, 53, 2, { rotationPreset: "right" }),
+ );
+ const style = {
+ color: "#ffffff",
+ backgroundColor: "rgba(0, 0, 0, 0.7)",
+ fontSize: 40,
+ fontFamily: "Inter",
+ fontWeight: "bold",
+ fontStyle: "normal",
+ textDecoration: "none",
+ textAlign: "center",
+ textAnimation: "fade",
+ };
+ doc.annotations.push(
+ {
+ id: id("ann"),
+ ...anchor(clipId, 2, 11),
+ type: "text",
+ content: "Benchmark title",
+ textContent: "Benchmark title",
+ space: "frame",
+ position: { x: 30, y: 8 },
+ size: { width: 40, height: 10 },
+ style,
+ zIndex: 1,
+ },
+ {
+ id: id("ann"),
+ ...anchor(clipId, 18, 30),
+ type: "figure",
+ content: "",
+ space: "frame",
+ position: { x: 60, y: 30 },
+ size: { width: 12, height: 20 },
+ style,
+ zIndex: 2,
+ figureData: { arrowDirection: "down-left", color: "#34B27B", strokeWidth: 14 },
+ },
+ {
+ id: id("ann"),
+ ...anchor(clipId, 30, 45),
+ type: "blur",
+ content: "",
+ position: { x: 10, y: 60 },
+ size: { width: 25, height: 20 },
+ style,
+ zIndex: 3,
+ blurData: { type: "blur", shape: "rectangle", color: "white", intensity: 12, blockSize: 12 },
+ },
+ );
+ // Transcript: one word every 0.5 s, eight words per segment, so captions change twice a second.
+ const words = [];
+ const segments = [];
+ for (let s = 0; s < DUR / 4; s++) {
+ const segId = `seg_${s}`;
+ const ids = [];
+ for (let w = 0; w < 8; w++) {
+ const t = s * 4 + w * 0.5;
+ const wid = `w_${s}_${w}`;
+ ids.push(wid);
+ words.push({
+ id: wid,
+ segmentId: segId,
+ startSec: t,
+ endSec: t + 0.45,
+ text: `word${s * 8 + w}`,
+ });
+ }
+ segments.push({
+ id: segId,
+ kind: "speech",
+ startSec: s * 4,
+ endSec: s * 4 + 3.95,
+ text: ids.map((_, w) => `word${s * 8 + w}`).join(" "),
+ wordIds: ids,
+ });
+ }
+ doc.transcript = { assetId, language: "en", segments, words };
+ doc.transcripts = [doc.transcript];
+ const musicId = id("asset");
+ doc.assets.push({
+ id: musicId,
+ kind: "audio",
+ label: "music.mp3",
+ originalPath: music,
+ durationSec: DUR,
+ sizeBytes: fs.statSync(music).size,
+ cameraTrack: null,
+ });
+ const trackId = id("audio");
+ doc.audioTracks.push({
+ id: trackId,
+ trackId,
+ ...anchor(clipId, 0, DUR),
+ assetId: musicId,
+ kind: "music",
+ durationSec: DUR,
+ offsetMs: 0,
+ gainDb: -18,
+ loop: false,
+ fadeInMs: 1000,
+ fadeOutMs: 1000,
+ muted: false,
+ label: "music.mp3",
+ origin: "user",
+ });
+ doc.legacyEditor = {
+ aspectRatio: "16:9",
+ wallpaper: "/wallpapers/wallpaper15.jpg",
+ wallpaperMotion: "drift",
+ frame: "none",
+ shadowIntensity: 0.6,
+ backgroundBlur: 0.26,
+ motionBlurAmount: 0.2,
+ depthOfField: true,
+ borderRadius: 40,
+ padding: 50,
+ autoZoomEnabled: false,
+ webcamLayoutPreset: "picture-in-picture",
+ webcamMaskShape: "square",
+ webcamRoundness: 0.7,
+ webcamMirrored: false,
+ webcamReactiveZoom: true,
+ webcamSizePreset: 40,
+ cursorSize: 2.25,
+ cursorSmoothing: 0.67,
+ cursorMotionBlur: 0.35,
+ cursorClickBounce: 1,
+ captions: {
+ enabled: true,
+ captionLane: "recording",
+ fontSize: 48,
+ fontFamily: "Inter",
+ fontWeight: "bold",
+ color: "#ffffff",
+ backgroundEnabled: true,
+ backgroundOpacity: 0.55,
+ backgroundColor: "#000000",
+ anchorV: "bottom",
+ insetY: 1.5,
+ anchorH: "center",
+ insetX: 10,
+ minWordsPerLine: 2,
+ maxWordsPerLine: 7,
+ },
+ };
+ fs.writeFileSync(path.join(outDir, `${doc.project.id}.openscreen`), JSON.stringify(doc, null, 1));
+ console.log("heavy", doc.project.id);
+}
diff --git a/scripts/perf-ab/gui-bench.mjs b/scripts/perf-ab/gui-bench.mjs
new file mode 100644
index 000000000..f8067fc11
--- /dev/null
+++ b/scripts/perf-ab/gui-bench.mjs
@@ -0,0 +1,324 @@
+// One measured GUI session of a packaged OpenScreen build, driven over CDP.
+// Startup to HUD, editor open to first preview frame, then playback with rAF / preview-paint
+// probes, CPU per process, GPU per process, optional desktop capture of the preview, and
+// memory after a long playback.
+//
+// node gui-bench.mjs --ver v200 --app <dir> --profile <dir> --project <file> --scenario light|heavy
+// --out <dir> --run <n> [--capture] [--play 30] [--total 0] [--memtrace]
+// --total keeps playing to that many seconds and reads memory; --memtrace also samples GPU memory
+// every 15 s on the way.
+import { execFile, execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { connect, sleep, waitTarget } from "./cdp.mjs";
+
+process.on("uncaughtException", (e) => {
+ console.error(e);
+ process.exit(1);
+});
+
+const { values: a } = parseArgs({
+ options: {
+ ver: { type: "string" },
+ app: { type: "string" },
+ profile: { type: "string" },
+ project: { type: "string" },
+ scenario: { type: "string" },
+ out: { type: "string" },
+ run: { type: "string", default: "0" },
+ capture: { type: "boolean", default: false },
+ play: { type: "string", default: "30" },
+ total: { type: "string", default: "0" },
+ hz: { type: "string", default: "" },
+ memtrace: { type: "boolean", default: false },
+ },
+});
+const HERE = path.dirname(new URL(import.meta.url).pathname).replace(/^\/([A-Za-z]:)/, "$1");
+const exe = path.join(a.app, "Openscreen.exe");
+const tag = `${a.scenario}-${a.ver}-r${a.run}${a.hz ? `-${a.hz}hz` : ""}`;
+fs.mkdirSync(a.out, { recursive: true });
+const outFile = (s) => path.join(a.out, `${tag}${s}`);
+const playSec = Number(a.play);
+const totalSec = Number(a.total);
+
+const procsnap = () =>
+ JSON.parse(
+ execFileSync(
+ "powershell",
+ [
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ path.join(HERE, "procsnap.ps1"),
+ "-Root",
+ a.app,
+ ],
+ { encoding: "utf8" },
+ ) || "[]",
+ );
+
+// Fresh profile state: exactly one project (the editor auto-opens the most recent), maximized editor.
+const projDir = path.join(a.profile, "projects");
+fs.mkdirSync(projDir, { recursive: true });
+for (const f of fs.readdirSync(projDir))
+ fs.rmSync(path.join(projDir, f), { recursive: true, force: true });
+fs.copyFileSync(a.project, path.join(projDir, path.basename(a.project)));
+fs.writeFileSync(
+ path.join(a.profile, "editor-window.json"),
+ JSON.stringify({ x: 0, y: 0, width: 1600, height: 900, maximized: true }),
+);
+
+const port = 9300 + Math.floor(Math.random() * 500);
+const log = fs.openSync(outFile(".app.log"), "w");
+const t0 = performance.now();
+const app = spawn(exe, [`--user-data-dir=${a.profile}`, `--remote-debugging-port=${port}`], {
+ stdio: ["ignore", log, log],
+});
+const since = () => performance.now() - t0;
+const result = { tag, ver: a.ver, scenario: a.scenario, run: Number(a.run), hz: a.hz || null };
+
+const until = async (fn, timeoutMs = 60000, everyMs = 10) => {
+ const end = Date.now() + timeoutMs;
+ while (Date.now() < end) {
+ try {
+ if (await fn()) return true;
+ } catch {
+ // not ready yet, or already gone: either way there is nothing to do
+ }
+ await sleep(everyMs);
+ }
+ throw new Error(`timeout: ${fn}`);
+};
+
+const kill = () => {
+ try {
+ execFileSync("taskkill", ["/T", "/F", "/PID", String(app.pid)], { stdio: "ignore" });
+ } catch {
+ // not ready yet, or already gone: either way there is nothing to do
+ }
+};
+
+try {
+ const hudT = await waitTarget(
+ port,
+ (ts) => ts.find((t) => t.url.includes("hud-overlay")),
+ 60000,
+ 10,
+ );
+ result.hudTargetMs = since();
+ const hud = await connect(hudT);
+ await until(() =>
+ hud.evaluate(`!!document.querySelector('[data-testid="launch-record-button"]')`),
+ );
+ result.startupToHudMs = since();
+ await sleep(1500);
+
+ const tOpen = performance.now();
+ await hud.evaluate("void window.electronAPI.switchToEditor(), true").catch(() => {
+ // the HUD closes as the editor opens, so this evaluation may never answer
+ });
+ const edT = await waitTarget(
+ port,
+ (ts) => ts.find((t) => t.url.includes("windowType=editor")),
+ 60000,
+ 10,
+ );
+ const ed = await connect(edT);
+ await ed.evaluate(fs.readFileSync(path.join(HERE, "probe.js"), "utf8"));
+ await until(() => ed.evaluate("!!document.querySelector('canvas[data-painted]')"), 90000, 5);
+ result.editorOpenToFirstFrameMs = performance.now() - tOpen;
+ await until(
+ () => ed.evaluate("[...document.querySelectorAll('video')].some(v => v.readyState >= 2)"),
+ 60000,
+ );
+ result.topmostWindows = Number(
+ execFileSync(
+ "powershell",
+ [
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ path.join(HERE, "topmost.ps1"),
+ "-ProcessId",
+ String(app.pid),
+ ],
+ { encoding: "utf8" },
+ ).trim(),
+ );
+ await sleep(3000);
+
+ result.videos = await ed.evaluate(
+ "[...document.querySelectorAll('video')].map(v => ({paused: v.paused, t: v.currentTime, d: v.duration, w: v.videoWidth}))",
+ );
+ result.window =
+ await ed.evaluate(`(() => { const c = document.querySelector('canvas[data-painted]'); const r = c.getBoundingClientRect();
+ return { dpr: devicePixelRatio, screenX, screenY, outerWidth, outerHeight, innerWidth, innerHeight, canvas: { left: r.left, top: r.top, width: r.width, height: r.height, bw: c.width, bh: c.height } }; })()`);
+
+ // GPU engines per process for the playback window (typeperf resolves its wildcard at start, so it
+ // starts once every process of the session exists).
+ const gpuCsv = outFile(".gpu.csv");
+ const gpu = spawn(
+ "typeperf",
+ [
+ "\\GPU Engine(*)\\Utilization Percentage",
+ "-si",
+ "1",
+ "-sc",
+ String(playSec + 2),
+ "-o",
+ gpuCsv,
+ "-y",
+ ],
+ { stdio: "ignore" },
+ );
+
+ let capture = null;
+ if (a.capture) {
+ const w = result.window;
+ const d = w.dpr;
+ // Maximized windows overhang the screen by their resize border; the client area starts at
+ // screenX + (outer - inner) / 2 horizontally, and at screenY + (outer - inner) - that border vertically.
+ const border = (w.outerWidth - w.innerWidth) / 2;
+ const x = Math.round((w.screenX + border + w.canvas.left) * d) & ~1;
+ const y =
+ Math.round((w.screenY + (w.outerHeight - w.innerHeight - border) + w.canvas.top) * d) & ~1;
+ const cw = Math.round(w.canvas.width * d) & ~1;
+ const ch = Math.round(w.canvas.height * d) & ~1;
+ result.captureRect = { x, y, w: cw, h: ch };
+ capture = spawn(
+ "ffmpeg",
+ [
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-y",
+ "-f",
+ "lavfi",
+ "-i",
+ `ddagrab=output_idx=0:framerate=560:draw_mouse=0:offset_x=${x}:offset_y=${y}:video_size=${cw}x${ch}`,
+ "-t",
+ String(playSec + 1),
+ "-c:v",
+ "h264_nvenc",
+ "-preset",
+ "p2",
+ "-tune",
+ "ll",
+ "-rc",
+ "constqp",
+ "-qp",
+ "14",
+ "-fps_mode",
+ "passthrough",
+ "-enc_time_base",
+ "1:10000",
+ outFile(".cap.mkv"),
+ ],
+ { stdio: ["ignore", "ignore", "pipe"] },
+ );
+ capture.stderr.on("data", (b) => fs.appendFileSync(outFile(".cap.err"), b));
+ await sleep(700);
+ }
+
+ await sleep(1500);
+ const snap0 = procsnap();
+ const w0 = performance.now();
+ await ed.evaluate("window.__bench.start(), true");
+ const clock0 = await ed.evaluate(
+ "[performance.now(), document.querySelector('video').currentTime]",
+ );
+ await ed.key(" ", "Space", 32);
+ await sleep(300);
+ result.playingAfterKey = await ed.evaluate(
+ "[...document.querySelectorAll('video')].some(v => !v.paused)",
+ );
+ if (!result.playingAfterKey)
+ await ed.evaluate("document.querySelector('video').play().then(() => true)");
+ await sleep(playSec * 1000 - 300);
+ const probe = await ed.evaluate("window.__bench.stop()");
+ result.visibility = await ed.evaluate("document.visibilityState");
+ result.clock = {
+ start: clock0,
+ end: await ed.evaluate("[performance.now(), document.querySelector('video').currentTime]"),
+ };
+ const snap1 = procsnap();
+ const w1 = performance.now();
+ result.playWindowMs = w1 - w0;
+ result.probe = probe;
+ result.cpu = { wallSec: (w1 - w0) / 1000, before: snap0, after: snap1 };
+ await new Promise((r) => (gpu.exitCode !== null ? r() : gpu.on("exit", r)));
+ if (capture) await new Promise((r) => (capture.exitCode !== null ? r() : capture.on("exit", r)));
+
+ if (totalSec > 0) {
+ // Keep playing (looping at the end) until totalSec of playback, then read memory.
+ const endAt = w0 + totalSec * 1000;
+ let nextTrace = 0;
+ result.gpuMemTrace = [];
+ while (performance.now() < endAt) {
+ if (a.memtrace && performance.now() >= nextTrace) {
+ nextTrace = performance.now() + 15000;
+ const t = Math.round((performance.now() - w0) / 1000);
+ const file = outFile(`.gpumem-${t}.csv`);
+ await new Promise((r) =>
+ execFile(
+ "typeperf",
+ ["\\GPU Process Memory(*)\\Dedicated Usage", "-sc", "1", "-o", file, "-y"],
+ () => r(),
+ ),
+ );
+ result.gpuMemTrace.push({ t, file, pids: procsnap().map((p) => [p.pid, p.role]) });
+ }
+ const ended = await ed.evaluate(
+ "(() => { const v = document.querySelector('video'); return v.paused && v.currentTime > v.duration - 0.5; })()",
+ );
+ if (ended) {
+ await ed.evaluate("document.querySelector('video').currentTime = 0; true");
+ await sleep(300);
+ await ed.key(" ", "Space", 32);
+ }
+ await sleep(1000);
+ }
+ result.memory = procsnap();
+ result.jsHeap = await ed.evaluate(
+ "performance.memory ? { used: performance.memory.usedJSHeapSize, total: performance.memory.totalJSHeapSize } : null",
+ );
+ await new Promise((r) =>
+ execFile(
+ "typeperf",
+ [
+ "\\GPU Process Memory(*)\\Dedicated Usage",
+ "\\GPU Process Memory(*)\\Shared Usage",
+ "-sc",
+ "1",
+ "-o",
+ outFile(".gpumem.csv"),
+ "-y",
+ ],
+ () => r(),
+ ),
+ );
+ }
+ result.ok = true;
+} catch (e) {
+ result.ok = false;
+ result.error = String(e?.stack ?? e);
+} finally {
+ kill();
+ fs.writeFileSync(outFile(".json"), JSON.stringify(result));
+ console.log(
+ JSON.stringify({
+ tag,
+ ok: result.ok,
+ error: result.error?.slice(0, 300),
+ startupToHudMs: result.startupToHudMs,
+ editorOpenToFirstFrameMs: result.editorOpenToFirstFrameMs,
+ playing: result.playingAfterKey,
+ draws: result.probe?.draw?.length,
+ rafs: result.probe?.raf?.length,
+ }),
+ );
+ process.exit(0);
+}
diff --git a/scripts/perf-ab/probe.js b/scripts/perf-ab/probe.js
new file mode 100644
index 000000000..39db0d32b
--- /dev/null
+++ b/scripts/perf-ab/probe.js
@@ -0,0 +1,54 @@
+// Injected into the editor renderer. Same code for both versions: rAF timestamps, every paint of
+// the preview canvas (the one `useNativeCompositorView` marks `data-painted`), long tasks.
+(() => {
+ if (window.__bench) return true;
+ const B = { raf: [], draw: [], shared: 0, readback: 0, lt: [], on: false };
+ window.__bench = B;
+ const loop = (t) => {
+ if (!B.on) return;
+ B.raf.push(Math.round(t * 1000) / 1000);
+ requestAnimationFrame(loop);
+ };
+ B.start = () => {
+ B.raf = [];
+ B.draw = [];
+ B.lt = [];
+ B.shared = 0;
+ B.readback = 0;
+ B.t0 = performance.now();
+ B.on = true;
+ requestAnimationFrame(loop);
+ };
+ B.stop = () => {
+ B.on = false;
+ return {
+ t0: B.t0,
+ t1: performance.now(),
+ raf: B.raf,
+ draw: B.draw,
+ shared: B.shared,
+ readback: B.readback,
+ lt: B.lt,
+ };
+ };
+ const drawImage = CanvasRenderingContext2D.prototype.drawImage;
+ CanvasRenderingContext2D.prototype.drawImage = function (src, ...rest) {
+ const c = this.canvas;
+ if (B.on && c && c.dataset && "painted" in c.dataset) {
+ B.draw.push(Math.round(performance.now() * 1000) / 1000);
+ if (typeof VideoFrame !== "undefined" && src instanceof VideoFrame) B.shared++;
+ else B.readback++;
+ }
+ return drawImage.call(this, src, ...rest);
+ };
+ try {
+ new PerformanceObserver((list) => {
+ if (B.on)
+ for (const e of list.getEntries())
+ B.lt.push([Math.round(e.startTime), Math.round(e.duration)]);
+ }).observe({ entryTypes: ["longtask"] });
+ } catch {
+ // no longtask entries in this Chromium: the rAF and paint timings still stand
+ }
+ return true;
+})();
diff --git a/scripts/perf-ab/procsnap.ps1 b/scripts/perf-ab/procsnap.ps1
new file mode 100644
index 000000000..b7ac2896d
--- /dev/null
+++ b/scripts/perf-ab/procsnap.ps1
@@ -0,0 +1,20 @@
+# One JSON snapshot of every process whose executable lives under $Root: CPU seconds, memory, role.
+param([Parameter(Mandatory)][string]$Root)
+$rootFull = [System.IO.Path]::GetFullPath($Root).TrimEnd('\') + '\'
+$procs = Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase) }
+$out = foreach ($p in $procs) {
+ $cl = [string]$p.CommandLine
+ $role = if ($cl -match '--type=([a-z-]+)') { $Matches[1] } elseif ($p.Name -ne 'Openscreen.exe') { $p.Name } else { 'main' }
+ if ($role -eq 'utility' -and $cl -match '--utility-sub-type=([A-Za-z.]+)') { $role = "utility:$($Matches[1])" }
+ [pscustomobject]@{
+ pid = [int]$p.ProcessId
+ ppid = [int]$p.ParentProcessId
+ name = $p.Name
+ role = $role
+ cpuSec = ([double]$p.KernelModeTime + [double]$p.UserModeTime) / 1e7
+ ws = [int64]$p.WorkingSetSize
+ peakWs = [int64]$p.PeakWorkingSetSize * 1024
+ priv = [int64]$p.PrivatePageCount
+ }
+}
+@($out) | ConvertTo-Json -Compress -Depth 3
diff --git a/scripts/perf-ab/record-bench.mjs b/scripts/perf-ab/record-bench.mjs
new file mode 100644
index 000000000..1699dd9cd
--- /dev/null
+++ b/scripts/perf-ab/record-bench.mjs
@@ -0,0 +1,225 @@
+// One 60 s full-screen take with the webcam, driven over CDP on the HUD (synthetic clicks: this
+// measures the recorder, not the HUD's reachability). A full-screen ffplay pattern changes at
+// 120 fps, so every 60 fps recorded frame must advance the bar by two pattern frames.
+//
+// node record-bench.mjs --ver v200 --app <dir> --profile <dir> --out <dir> --run <n> [--sec 60]
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { connect, sleep, waitTarget } from "./cdp.mjs";
+
+process.on("uncaughtException", (e) => {
+ console.error(e);
+ process.exit(1);
+});
+
+const { values: a } = parseArgs({
+ options: {
+ ver: { type: "string" },
+ app: { type: "string" },
+ profile: { type: "string" },
+ out: { type: "string" },
+ run: { type: "string", default: "0" },
+ sec: { type: "string", default: "60" },
+ },
+});
+const HERE = path.dirname(new URL(import.meta.url).pathname).replace(/^\/([A-Za-z]:)/, "$1");
+const tag = `record-${a.ver}-r${a.run}`;
+fs.mkdirSync(a.out, { recursive: true });
+const outFile = (s) => path.join(a.out, `${tag}${s}`);
+const procsnap = () =>
+ JSON.parse(
+ execFileSync(
+ "powershell",
+ [
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ path.join(HERE, "procsnap.ps1"),
+ "-Root",
+ a.app,
+ ],
+ { encoding: "utf8" },
+ ) || "[]",
+ );
+const until = async (fn, timeoutMs = 60000, everyMs = 50) => {
+ const end = Date.now() + timeoutMs;
+ while (Date.now() < end) {
+ try {
+ if (await fn()) return true;
+ } catch {
+ // not ready yet, or already gone: either way there is nothing to do
+ }
+ await sleep(everyMs);
+ }
+ throw new Error(`timeout: ${fn}`);
+};
+
+const recDir = path.join(a.profile, "recordings");
+fs.mkdirSync(recDir, { recursive: true });
+for (const f of fs.readdirSync(recDir))
+ fs.rmSync(path.join(recDir, f), { recursive: true, force: true });
+for (const f of ["projects"]) fs.rmSync(path.join(a.profile, f), { recursive: true, force: true });
+// Same settings for both versions: webcam on at the default quality, no audio, no desktop-icon overlay.
+const settingsPath = path.join(a.profile, "recording-settings.json");
+const prev = fs.existsSync(settingsPath) ? JSON.parse(fs.readFileSync(settingsPath, "utf8")) : {};
+fs.writeFileSync(
+ settingsPath,
+ JSON.stringify(
+ {
+ ...prev,
+ autoZoomEnabled: false,
+ micEnabled: false,
+ systemAudioEnabled: false,
+ camEnabled: true,
+ camDeviceId: "7a598dd6b8baca1cab5ad39e42935353f0a6bc3fa005060d4c193811631255fe",
+ camDeviceName: "Logitech StreamCam (046d:0893)",
+ camQuality: "2160p",
+ cursorCaptureMode: "editable-overlay",
+ hideDesktopIcons: false,
+ },
+ null,
+ 2,
+ ),
+);
+
+const result0 = {};
+const pattern = spawn(
+ "ffplay",
+ [
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-fs",
+ "-an",
+ "-f",
+ "lavfi",
+ "-i",
+ "color=c=0x404040:s=1920x1080:r=120[a];color=c=white:s=24x1080:r=120[b];[a][b]overlay=x='mod(n*16,1904)':y=0[out0]",
+ ],
+ { stdio: "ignore" },
+);
+await sleep(2000);
+// Opened by a background process, the pattern lands behind the foreground window: pin it, or the
+// take films whatever else is on screen.
+result0.patternTopmost = Number(
+ execFileSync(
+ "powershell",
+ [
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ path.join(HERE, "topmost.ps1"),
+ "-ProcessId",
+ String(pattern.pid),
+ ],
+ { encoding: "utf8" },
+ ).trim(),
+);
+if (!result0.patternTopmost) {
+ execFileSync("taskkill", ["/T", "/F", "/PID", String(pattern.pid)], { stdio: "ignore" });
+ throw new Error("pattern window not found");
+}
+
+const port = 9300 + Math.floor(Math.random() * 500);
+const log = fs.openSync(outFile(".app.log"), "w");
+const app = spawn(
+ path.join(a.app, "Openscreen.exe"),
+ [`--user-data-dir=${a.profile}`, `--remote-debugging-port=${port}`],
+ { stdio: ["ignore", log, log] },
+);
+const result = { tag, ver: a.ver, run: Number(a.run), ...result0 };
+try {
+ const hud = await connect(
+ await waitTarget(port, (ts) => ts.find((t) => t.url.includes("hud-overlay"))),
+ );
+ await until(() =>
+ hud.evaluate(`!!document.querySelector('[data-testid="launch-record-button"]')`),
+ );
+ await sleep(2000);
+ result.camPressed = await hud.evaluate(
+ `document.querySelector('[data-testid="launch-webcam-button"]').getAttribute('aria-pressed')`,
+ );
+ if (result.camPressed !== "true") {
+ await hud.evaluate(
+ `document.querySelector('[data-testid="launch-webcam-button"]').click(), true`,
+ );
+ await sleep(1500);
+ }
+ await hud.evaluate(
+ `document.querySelector('[data-testid="launch-source-selector-button"]').click(), true`,
+ );
+ const sel = await connect(
+ await waitTarget(port, (ts) => ts.find((t) => t.url.includes("source-selector"))),
+ );
+ await until(
+ () =>
+ sel.evaluate(
+ `!!document.querySelector('[data-testid="source-selector-card"][data-source-kind="screen"]')`,
+ ),
+ 30000,
+ );
+ await sel.evaluate(
+ `document.querySelector('[data-testid="source-selector-card"][data-source-kind="screen"]').click(), true`,
+ );
+ await sleep(500);
+ await sel
+ .evaluate(
+ `document.querySelector('[data-testid="source-selector-share-button"]').click(), true`,
+ )
+ .catch(() => {
+ // the picker closes on this click, so the evaluation may never answer
+ });
+ await sleep(1500);
+ await hud.evaluate(
+ `document.querySelector('[data-testid="launch-record-button"]').click(), true`,
+ );
+ await until(
+ () => hud.evaluate(`!!document.querySelector('[data-testid="launch-pause-button"]')`),
+ 30000,
+ );
+ await sleep(2000); // countdown overlay, encoder warm-up
+ const snap0 = procsnap();
+ const w0 = performance.now();
+ await sleep(Number(a.sec) * 1000);
+ const snap1 = procsnap();
+ result.cpu = { wallSec: (performance.now() - w0) / 1000, before: snap0, after: snap1 };
+ await hud.evaluate(
+ `document.querySelector('[data-testid="launch-record-button"]').click(), true`,
+ );
+ // Saving ends when the editor opens on the take.
+ await waitTarget(port, (ts) => ts.find((t) => t.url.includes("windowType=editor")), 120000, 100);
+ await sleep(3000);
+ result.files = fs
+ .readdirSync(recDir)
+ .map((f) => ({ f, size: fs.statSync(path.join(recDir, f)).size }));
+ result.ok = true;
+} catch (e) {
+ result.ok = false;
+ result.error = String(e?.stack ?? e);
+} finally {
+ try {
+ execFileSync("taskkill", ["/T", "/F", "/PID", String(app.pid)], { stdio: "ignore" });
+ } catch {
+ // not ready yet, or already gone: either way there is nothing to do
+ }
+ try {
+ execFileSync("taskkill", ["/T", "/F", "/PID", String(pattern.pid)], { stdio: "ignore" });
+ } catch {
+ // not ready yet, or already gone: either way there is nothing to do
+ }
+ fs.writeFileSync(outFile(".json"), JSON.stringify(result));
+ console.log(
+ JSON.stringify({
+ tag,
+ ok: result.ok,
+ error: result.error?.slice(0, 300),
+ cam: result.camPressed,
+ files: result.files,
+ }),
+ );
+ process.exit(0);
+}
diff --git a/scripts/perf-ab/run-gui.sh b/scripts/perf-ab/run-gui.sh
new file mode 100644
index 000000000..f937b9962
--- /dev/null
+++ b/scripts/perf-ab/run-gui.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+# usage: run-gui.sh <scratch> <outdir> <hz> light|heavy...
+# <scratch> holds app-v200/, app-main/ (extracted builds), projects/ and receives profiles/ and out/.
+HERE=$(dirname "$0")
+S="$1"; OUT="$2"; HZ="$3"; shift 3
+W=$(cygpath -m "$S")
+LIGHT=$(cygpath -m "$(ls -S "$S"/projects/*.openscreen | tail -1)")
+HEAVY=$(cygpath -m "$(ls -S "$S"/projects/*.openscreen | head -1)")
+for sc in "$@"; do
+ for run in 1 2 3; do
+ if [ $((run % 2)) = 1 ]; then order="v200 main"; else order="main v200"; fi
+ for v in $order; do
+ if [ "$sc" = light ]; then extra="--capture --play 30"; proj="$LIGHT"; else extra="--play 30 --total 120"; proj="$HEAVY"; fi
+ node "$HERE/gui-bench.mjs" --ver $v --app "$W/app-$v" --profile "$W/profiles/gui-$sc-$v" --project "$proj" --scenario $sc --out "$W/out/$OUT" --run $run --hz $HZ $extra
+ sleep 3
+ done
+ done
+done
diff --git a/scripts/perf-ab/run-record.sh b/scripts/perf-ab/run-record.sh
new file mode 100644
index 000000000..b2144e5c5
--- /dev/null
+++ b/scripts/perf-ab/run-record.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+# usage: run-record.sh <scratch> <outdir> <runs...>
+# Each take is analysed right after it ends, then deleted: it holds the webcam picture.
+HERE=$(dirname "$0")
+S="$1"; OUT="$2"; shift 2
+W=$(cygpath -m "$S")
+mkdir -p "$S/out/$OUT"
+for run in "$@"; do
+ if [ $((run % 2)) = 1 ]; then order="v200 main"; else order="main v200"; fi
+ for v in $order; do
+ node "$HERE/record-bench.mjs" --ver $v --app "$W/app-$v" --profile "$W/profiles/rec-$v" --out "$W/out/$OUT" --run $run
+ rec="$S/profiles/rec-$v/recordings"
+ scr=$(ls "$rec"/recording-* 2>/dev/null | grep -E ".(mp4|webm|mkv)$" | grep -v -- -webcam | head -1)
+ cam=$(ls "$rec"/recording-*-webcam.* 2>/dev/null | grep -E ".(mp4|webm|mkv)$" | head -1)
+ if [ -n "$scr" ]; then
+ python "$HERE/analyze_recording.py" "$(cygpath -m "$scr")" ${cam:+"$(cygpath -m "$cam")"} > "$S/out/$OUT/record-$v-r$run.analysis.json"
+ cat "$S/out/$OUT/record-$v-r$run.analysis.json"; echo
+ fi
+ rm -rf "$rec"
+ sleep 3
+ done
+done
diff --git a/scripts/perf-ab/summarize-gui.mjs b/scripts/perf-ab/summarize-gui.mjs
new file mode 100644
index 000000000..2d3989abc
--- /dev/null
+++ b/scripts/perf-ab/summarize-gui.mjs
@@ -0,0 +1,204 @@
+// Per-run metrics from gui-bench results, then median [min-max] per (scenario, version, hz).
+// node summarize-gui.mjs <dir> [<dir> ...] -> writes <first dir>/summary.json, prints per-run lines
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const HERE = path.dirname(new URL(import.meta.url).pathname).replace(/^\/([A-Za-z]:)/, "$1");
+const dirs = process.argv.slice(2);
+const q = (arr, p) => {
+ if (!arr.length) return null;
+ const s = [...arr].sort((x, y) => x - y);
+ return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
+};
+const median = (a) => {
+ const s = [...a].sort((x, y) => x - y);
+ const h = s.length >> 1;
+ return s.length % 2 ? s[h] : (s[h - 1] + s[h]) / 2;
+};
+const diffs = (a) => a.slice(1).map((v, i) => v - a[i]);
+
+function readCsv(file) {
+ if (!fs.existsSync(file)) return null;
+ const lines = fs
+ .readFileSync(file, "utf8")
+ .trim()
+ .split(/\r?\n/)
+ .map((l) => l.split('","').map((c) => c.replace(/^"|"$/g, "")));
+ return { header: lines[0], rows: lines.slice(1) };
+}
+
+function gpuByRole(file, roleOf) {
+ const csv = readCsv(file);
+ if (!csv) return null;
+ const acc = {};
+ csv.header.forEach((h, i) => {
+ const m = h.match(/pid_(\d+)_.*engtype_([A-Za-z0-9 ]+)\)/);
+ if (!m || !roleOf.has(Number(m[1]))) return;
+ const vals = csv.rows
+ .slice(1)
+ .map((r) => Number(r[i]))
+ .filter((v) => Number.isFinite(v));
+ if (!vals.length) return;
+ const mean = vals.reduce((s, v) => s + v, 0) / vals.length;
+ const key = `${roleOf.get(Number(m[1]))}:${m[2]}`;
+ acc[key] = (acc[key] ?? 0) + mean;
+ });
+ return acc;
+}
+
+function gpuMem(file, roleOf) {
+ const csv = readCsv(file);
+ if (!csv) return null;
+ const out = { dedicatedMB: 0, sharedMB: 0, dedicatedMainMB: 0, dedicatedGpuProcMB: 0 };
+ csv.header.forEach((h, i) => {
+ const m = h.match(/pid_(\d+)_/);
+ if (!m || !roleOf.has(Number(m[1]))) return;
+ const v = Number(csv.rows.at(-1)[i]) / 2 ** 20;
+ if (!Number.isFinite(v)) return;
+ if (h.endsWith("Dedicated Usage")) {
+ out.dedicatedMB += v;
+ if (roleOf.get(Number(m[1])) === "main") out.dedicatedMainMB += v;
+ if (roleOf.get(Number(m[1])) === "gpu-process") out.dedicatedGpuProcMB += v;
+ } else if (h.endsWith("Shared Usage")) out.sharedMB += v;
+ });
+ return out;
+}
+
+function perRun(file) {
+ const r = JSON.parse(fs.readFileSync(file, "utf8"));
+ if (!r.ok) return { tag: r.tag, ok: false, error: r.error };
+ const m = { tag: r.tag, scenario: r.scenario, ver: r.ver, hz: r.hz, run: r.run, ok: true };
+ m.startupToHudMs = r.startupToHudMs;
+ m.editorOpenMs = r.editorOpenToFirstFrameMs;
+ const raf = diffs(r.probe.raf);
+ const vsync = q(raf, 50);
+ m.rafP50 = vsync;
+ m.rafP95 = q(raf, 95);
+ m.rafP99 = q(raf, 99);
+ m.rafMax = Math.max(...raf);
+ m.rafOverBudgetPct = (100 * raf.filter((x) => x > 1.5 * vsync).length) / raf.length;
+ m.rafOver25 = raf.filter((x) => x > 25).length;
+ const dr = diffs(r.probe.draw);
+ m.paintFps = ((r.probe.draw.length - 1) * 1000) / (r.probe.draw.at(-1) - r.probe.draw[0]);
+ m.paintP50 = q(dr, 50);
+ m.paintP95 = q(dr, 95);
+ m.paintP99 = q(dr, 99);
+ m.paintMax = Math.max(...dr);
+ m.paintOver25 = dr.filter((x) => x > 25).length;
+ m.paintOver34 = dr.filter((x) => x > 34).length;
+ m.transport =
+ r.probe.shared > 0 && r.probe.readback === 0
+ ? "shared"
+ : r.probe.readback > 0 && r.probe.shared === 0
+ ? "readback"
+ : "mixed";
+ m.longTasks = r.probe.lt.length;
+ m.longTaskMs = r.probe.lt.reduce((s, [, d]) => s + d, 0);
+ const before = new Map(r.cpu.before.map((p) => [p.pid, p]));
+ const roleOf = new Map(r.cpu.after.map((p) => [p.pid, p.role]));
+ const cpu = {};
+ for (const p of r.cpu.after) {
+ const d = p.cpuSec - (before.get(p.pid)?.cpuSec ?? 0);
+ const role = p.role.startsWith("utility") ? "utility" : p.role;
+ cpu[role] = (cpu[role] ?? 0) + (100 * d) / r.cpu.wallSec;
+ }
+ m.cpuTotal = Object.values(cpu).reduce((s, v) => s + v, 0);
+ m.cpuMain = cpu.main ?? 0;
+ m.cpuGpuProc = cpu["gpu-process"] ?? 0;
+ m.cpuRenderer = cpu.renderer ?? 0;
+ m.cpuOther = m.cpuTotal - m.cpuMain - m.cpuGpuProc - m.cpuRenderer;
+ const base = file.replace(/\.json$/, "");
+ const gpu = gpuByRole(`${base}.gpu.csv`, roleOf);
+ if (gpu) {
+ const sum = (pred) =>
+ Object.entries(gpu)
+ .filter(([k]) => pred(k))
+ .reduce((s, [, v]) => s + v, 0);
+ m.gpu3dMain = sum((k) => k === "main:3D");
+ m.gpu3dGpuProc = sum((k) => k === "gpu-process:3D");
+ m.gpuVideoDecode = sum((k) => k.endsWith(":VideoDecode"));
+ m.gpuCopy = sum((k) => k.endsWith(":Copy"));
+ m.gpuAll = sum(() => true);
+ }
+ if (r.memory) {
+ const mem = r.memory;
+ m.memWsMB = mem.reduce((s, p) => s + p.ws, 0) / 2 ** 20;
+ m.memPrivMB = mem.reduce((s, p) => s + p.priv, 0) / 2 ** 20;
+ m.memMainPrivMB =
+ mem.filter((p) => p.role === "main").reduce((s, p) => s + p.priv, 0) / 2 ** 20;
+ m.memRendererPrivMB =
+ mem.filter((p) => p.role === "renderer").reduce((s, p) => s + p.priv, 0) / 2 ** 20;
+ m.memGpuProcPrivMB =
+ mem.filter((p) => p.role === "gpu-process").reduce((s, p) => s + p.priv, 0) / 2 ** 20;
+ m.jsHeapMB = r.jsHeap ? r.jsHeap.used / 2 ** 20 : null;
+ const gm = gpuMem(`${base}.gpumem.csv`, new Map(mem.map((p) => [p.pid, p.role])));
+ if (gm) {
+ m.gpuDedicatedMB = gm.dedicatedMB;
+ m.gpuDedicatedMainMB = gm.dedicatedMainMB;
+ m.gpuDedicatedGpuProcMB = gm.dedicatedGpuProcMB;
+ m.gpuSharedMB = gm.sharedMB;
+ }
+ }
+ const cap = `${base}.cap.mkv`;
+ if (fs.existsSync(cap)) {
+ const cached = `${base}.cap.json`;
+ if (!fs.existsSync(cached))
+ fs.writeFileSync(
+ cached,
+ execFileSync("python", [path.join(HERE, "analyze_capture.py"), cap, "18"], {
+ encoding: "utf8",
+ maxBuffer: 1 << 26,
+ }),
+ );
+ const c = JSON.parse(fs.readFileSync(cached, "utf8"));
+ m.screenUpdateHz = c.updateHz;
+ m.screenUpdP50 = c.updateIntervalMs.p50;
+ m.screenUpdP95 = c.updateIntervalMs.p95;
+ m.screenUpdP99 = c.updateIntervalMs.p99;
+ m.screenUpdOver25 = c.updateIntervalMs.over25ms;
+ const spu = c.screenFramesPerUpdate;
+ const total = Object.values(spu).reduce((s, v) => s + v, 0);
+ m.screenSkipPct =
+ (100 *
+ Object.entries(spu)
+ .filter(([k]) => Number(k) >= 2)
+ .reduce((s, [, v]) => s + v, 0)) /
+ total;
+ m.screenRepeatPct = (100 * (spu["0"] ?? 0)) / total;
+ m.cursorRmsPx = c.cursorResidualSourcePx.rms;
+ m.cursorP99Px = c.cursorResidualSourcePx.p99;
+ m.cursorBackward = c.cursorBackwardSteps;
+ }
+ return m;
+}
+
+const runs = dirs.flatMap((d) =>
+ fs
+ .readdirSync(d)
+ .filter((f) => /^(light|heavy)-.*\.json$/.test(f) && !f.endsWith(".cap.json"))
+ .map((f) => perRun(path.join(d, f))),
+);
+for (const r of runs) console.log(JSON.stringify(r));
+const groups = Object.groupBy(
+ runs.filter((r) => r.ok),
+ (r) => `${r.scenario}|${r.hz}|${r.ver}`,
+);
+const agg = {};
+for (const [k, rs] of Object.entries(groups)) {
+ agg[k] = { n: rs.length };
+ for (const key of Object.keys(rs[0])) {
+ const vals = rs.map((r) => r[key]).filter((v) => typeof v === "number" && Number.isFinite(v));
+ // Memory is only read on the sessions that played 2 min, so a metric may cover fewer runs.
+ if (vals.length < 2 || ["run"].includes(key)) continue;
+ agg[k][key] = {
+ med: median(vals),
+ min: Math.min(...vals),
+ max: Math.max(...vals),
+ n: vals.length,
+ vals,
+ };
+ }
+}
+fs.writeFileSync(path.join(dirs[0], "summary.json"), JSON.stringify({ runs, agg }, null, 1));
+console.log(JSON.stringify(Object.keys(agg)));
diff --git a/scripts/perf-ab/summarize-record.mjs b/scripts/perf-ab/summarize-record.mjs
new file mode 100644
index 000000000..aa7215a25
--- /dev/null
+++ b/scripts/perf-ab/summarize-record.mjs
@@ -0,0 +1,56 @@
+// CPU per process role during each take, and the recorded files' cadence, median [min-max] per version.
+import fs from "node:fs";
+import path from "node:path";
+
+const dir = process.argv[2];
+const q = (a) => [...a].sort((x, y) => x - y)[Math.floor(a.length / 2)];
+const rows = {};
+for (const f of fs.readdirSync(dir).filter((f) => /^record-.*-r\d+\.json$/.test(f))) {
+ const r = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+ if (!r.ok) continue;
+ const an = JSON.parse(
+ fs.readFileSync(path.join(dir, f.replace(".json", ".analysis.json")), "utf8"),
+ );
+ const before = new Map(r.cpu.before.map((p) => [p.pid, p]));
+ const cpu = {};
+ for (const p of r.cpu.after) {
+ const role = p.role.startsWith("utility") ? "utility" : p.role;
+ cpu[role] =
+ (cpu[role] ?? 0) + (100 * (p.cpuSec - (before.get(p.pid)?.cpuSec ?? 0))) / r.cpu.wallSec;
+ }
+ const m = {
+ cpuTotal: Object.values(cpu).reduce((s, v) => s + v, 0),
+ cpuWgc: cpu["wgc-capture.exe"] ?? 0,
+ cpuCursor: cpu["cursor-sampler.exe"] ?? 0,
+ cpuMain: cpu.main ?? 0,
+ cpuRenderer: cpu.renderer ?? 0,
+ cpuGpuProc: cpu["gpu-process"] ?? 0,
+ screenFps: an.screen.fps,
+ screenMaxGapMs: an.screen.maxGapMs,
+ screenRepeated: an.screen.duplicated,
+ camFps: an.webcam.fps,
+ camMaxGapMs: an.webcam.maxGapMs,
+ camIdentical: an.webcam.identicalConsecutive,
+ roles: Object.keys(cpu).join(","),
+ };
+ console.log(
+ f,
+ JSON.stringify(
+ Object.fromEntries(
+ Object.entries(m).map(([k, v]) => [k, typeof v === "number" ? +v.toFixed(2) : v]),
+ ),
+ ),
+ );
+ if (!rows[r.ver]) rows[r.ver] = [];
+ rows[r.ver].push(m);
+}
+const agg = {};
+for (const [ver, ms] of Object.entries(rows)) {
+ agg[`record|${ver}`] = {};
+ for (const k of Object.keys(ms[0])) {
+ const v = ms.map((m) => m[k]);
+ if (typeof v[0] === "number")
+ agg[`record|${ver}`][k] = { med: q(v), min: Math.min(...v), max: Math.max(...v) };
+ }
+}
+fs.writeFileSync(path.join(dir, "summary.json"), JSON.stringify({ agg }, null, 1));
diff --git a/scripts/perf-ab/topmost.ps1 b/scripts/perf-ab/topmost.ps1
new file mode 100644
index 000000000..cc9ee3fef
--- /dev/null
+++ b/scripts/perf-ab/topmost.ps1
@@ -0,0 +1,36 @@
+# Puts every visible top-level window of process $ProcessId (or of its descendants: a launcher shim
+# owns no window) above all others. A window a background
+# process creates opens behind the foreground one (Windows refuses the focus steal), so without this
+# the desktop capture films whatever covers the editor.
+param([Parameter(Mandatory)][int]$ProcessId)
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class Win {
+ public delegate bool EnumProc(IntPtr h, IntPtr l);
+ [DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc f, IntPtr l);
+ [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+ [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+ [DllImport("user32.dll")] public static extern int GetWindowTextLength(IntPtr h);
+ [DllImport("user32.dll")] public static extern bool SetWindowPos(IntPtr h, IntPtr after, int x, int y, int cx, int cy, uint flags);
+}
+"@
+$all = Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId
+$pids = @{ $ProcessId = $true }
+do {
+ $added = 0
+ foreach ($p in $all) { if ($pids.ContainsKey([int]$p.ParentProcessId) -and -not $pids.ContainsKey([int]$p.ProcessId)) { $pids[[int]$p.ProcessId] = $true; $added++ } }
+} while ($added)
+$done = 0
+[Win]::EnumWindows({
+ param($h, $l)
+ $p = 0
+ [void][Win]::GetWindowThreadProcessId($h, [ref]$p)
+ if ($pids.ContainsKey([int]$p) -and [Win]::IsWindowVisible($h) -and [Win]::GetWindowTextLength($h) -gt 0) {
+ # HWND_TOPMOST, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE
+ [void][Win]::SetWindowPos($h, [IntPtr](-1), 0, 0, 0, 0, 0x0013)
+ $script:done++
+ }
+ return $true
+}, [IntPtr]::Zero) | Out-Null
+$done
diff --git a/technical-documentation/README.md b/technical-documentation/README.md
index 3a8dd9426..a512e8ff3 100644
--- a/technical-documentation/README.md
+++ b/technical-documentation/README.md
@@ -49,6 +49,7 @@ who reads and writes the project document.
| [writing-tests.md](testing/writing-tests.md) | Unit, browser and end-to-end tests: which to write, where, how to run them |
| [manual-e2e-checklist.md](testing/manual-e2e-checklist.md) | What automated tests cannot reach — real capture, a real webcam, the tray, export |
| [native-cursor-diagnostics.md](testing/native-cursor-diagnostics.md) | Windows and macOS cursor sampler tools and how to read their reports |
+| [performance-ab.md](testing/performance-ab.md) | Comparing the smoothness and speed of two packaged builds, and the results log |
## Keeping this current
diff --git a/technical-documentation/testing/performance-ab.md b/technical-documentation/testing/performance-ab.md
new file mode 100644
index 000000000..553dbdd2f
--- /dev/null
+++ b/technical-documentation/testing/performance-ab.md
@@ -0,0 +1,193 @@
+# Performance A/B between two packaged builds
+
+How to compare the smoothness and speed of two OpenScreen builds on one Windows machine, and the
+log of every comparison run so far. The scripts live in [`scripts/perf-ab/`](../../scripts/perf-ab/).
+
+## Results log
+
+### 2.0.0 against main `9dc48b5c7`, Windows, 15/10/2026
+
+**Verdict: main is as smooth and as fast as 2.0.0 at 279 Hz, with one small slowdown to fix.**
+
+- **One regression over 5%**: the editor takes 53 ms longer (+5.2%) to show its first frame on
+ the heavy project. Starting the app to the HUD takes 31 ms longer (+4.9%). Both are
+ significant over 12 and 15 sessions.
+- **No preview regression established.** The light project is identical. On the heavy project,
+ late paints are 17% higher at the median but not significantly so (see below).
+- **Two improvements.** GIF export is 30 times faster. A recorded screen video keeps a regular
+ 60 fps clock, where 2.0.0's timestamps wander.
+- **Two defects both versions share.** The heavy preview alternates between a smooth and a
+ stuttering mode from one session to the next. The GPU process's dedicated GPU memory grows by
+ 80 to 105 MB per second of playback, past the card's 12 GB.
+
+**Setup**
+
+- Machine: Ryzen 7 5800X, RTX 4070 Ti 12 GB, 32 GB RAM, one 1920×1080 display at 279 Hz,
+ Windows 11 build 26200, 100% scaling.
+- 2.0.0: the release's `Openscreen.Setup.2.0.0.exe`. main: `9dc48b5c7`, built by `build.yml` run
+ 38758703830. Both extracted and run side by side, never installed.
+- Sessions interleaved between the two builds. Light project: 3 per build. Heavy: 12 per build,
+ memory read on 3 of them. Exports: 3 per case, 2 for the 2.0.0 GIF (8 min each). Takes: 3.
+- Background load: other sessions' Electron processes (an `openscreen mcp` set and a dev build of
+ #1189) stayed open and idle. Early runs where another window covered the editor were discarded
+ and run again with the editor pinned on top.
+- Not covered: a 60 Hz display, macOS and Linux.
+
+**Flags**
+
+| # | Finding | Status | Likely cause | Next step |
+|---|---|---|---|---|
+| 1 | Editor open +53 ms (1025 → 1078 ms), startup to HUD +31 ms (620 → 651 ms) | Regression, p < 0.05 | More work at launch since 2.0.0: the in-app MCP server (`b81cd3760`, `65444df3e`), the shader effects in the document and the Effects lane (`1b704ff6e`, `74c89035e`), the daily usage ping (`b5ff5a348`). Not bisected. | Bisect editor open on the heavy project |
+| 2 | Heavy preview: 87 → 102 paints later than 25 ms per 30 s (+17%) | Within noise, p ≈ 0.2 | Both builds land in a slow mode (paint p95 28.5 ms instead of 22 ms) in about half the sessions: 2.0.0 6 of 12, main 7 of 12. The mode follows the session, not the build. | Find what sets the mode |
+| 3 | GPU process dedicated memory, one traced session each: 0.8 GB (2.0.0) and 1.4 GB (main) at 11 s of playback, 9.8 GB and 12.8 GB at 2 min | Pre-existing, both builds | Grows linearly with playback, so something per frame is kept: the shared-texture preview path is the first suspect | Trace the shared frames' lifetime |
+
+#### Preview, light project (3 sessions each)
+
+| Metric | 2.0.0 | main | Delta | Verdict |
+|---|---|---|---|---|
+| Preview paints per second | 60.0 [60.0–60.0] | 60.0 [60.0–60.0] | +0.0% | same |
+| Paint interval p95 (ms) | 21.9 [21.8–21.9] | 21.8 [21.8–22.0] | -0.5% | same |
+| Paint interval p99 (ms) | 22.7 [22.7–22.8] | 22.7 [22.4–22.9] | -0.0% | same |
+| Paints later than 25 ms, per 30 s | 2 [0–2] | 1 [0–1] | -50.0% | within noise |
+| UI rAF interval p99 (ms) | 3.70 [3.70–3.70] | 3.70 [3.70–3.70] | +0.0% | same |
+| UI rAF over 1.5 vsync (%) | 0.02 [0.01–0.33] | 0.06 [0.02–0.10] | +150.2% | within noise |
+| CPU, all processes (% of one core) | 148.8 [148.4–151.6] | 145.8 [140.2–155.2] | -2.0% | same |
+| CPU, main process (%) | 18.2 [17.7–19.1] | 16.9 [16.4–18.1] | -7.0% | within noise |
+| GPU, all engines of the app (%) | 9.6 [9.1–9.7] | 9.6 [9.5–9.8] | +0.3% | same |
+| On screen: preview updates per second | 57.5 [46.6–60.0] | 58.4 [51.6–59.9] | +1.5% | same |
+| On screen: update interval p99 (ms) | 30.0 [25.0–39.6] | 29.5 [24.3–37.0] | -1.6% | same |
+| On screen: updates skipping a video frame (%) | 4.36 [0.09–17.88] | 2.86 [0.28–16.27] | -34.4% | within noise |
+| On screen: cursor off its path, RMS (source px) | 5.83 [5.71–31.12] | 5.86 [5.57–7.43] | +0.6% | same |
+| On screen: cursor off its path, p99 (source px) | 20.34 [20.12–128.20] | 20.54 [20.32–22.92] | +1.0% | same |
+| On screen: cursor steps backwards | 0 [0–52] | 0 [0–0] | +0.0% | same |
+
+The cursor follows its recorded path equally closely in both builds: no fidget on Windows. The
+residual of about 6 px RMS is the cursor smoothing's lag, the same in both. The ranges of the
+on-screen rows are wide because the desktop capture itself misses frames now and then (one
+2.0.0 session and one main session).
+
+#### Preview, heavy project (12 sessions each; memory on 3)
+
+| Metric | 2.0.0 | main | Delta | Verdict |
+|---|---|---|---|---|
+| Preview paints per second | 60.0 [59.8–60.0] | 60.0 [59.7–60.0] | +0.0% | same |
+| Paint interval p95 (ms) | 24.7 [22.1–28.5] | 27.9 [22.1–28.5] | +13.0% | within noise (p ≥ 0.05) |
+| Paint interval p99 (ms) | 35.5 [28.8–35.8] | 35.4 [29.0–35.7] | -0.1% | same |
+| Paints later than 25 ms, per 30 s | 87 [53–113] | 102 [54–119] | +16.7% | within noise (p ≥ 0.05) |
+| UI rAF interval p99 (ms) | 3.70 [3.70–3.70] | 3.70 [3.70–3.70] | +0.0% | same |
+| Long tasks over 50 ms, per 30 s | 0 [0–0] | 0 [0–0] | +0.0% | same |
+| CPU, all processes (% of one core) | 141.6 [130.6–162.2] | 144.2 [131.0–161.5] | +1.8% | same |
+| CPU, main process (%) | 19.7 [15.4–23.7] | 18.2 [15.7–20.0] | -7.7% | within noise (p ≥ 0.05) |
+| CPU, GPU process (%) | 45.0 [41.7–51.6] | 47.0 [42.9–50.1] | +4.5% | same |
+| CPU, renderer (%) | 77.2 [72.4–89.5] | 78.9 [72.2–92.4] | +2.2% | same |
+| GPU 3D, main process / compositor (%) | 3.0 [2.4–4.0] | 3.5 [2.6–4.2] | +16.4% | within noise (p ≥ 0.05) |
+| GPU video decode (%) | 10.8 [10.6–10.9] | 10.8 [10.6–20.6] | +0.8% | same |
+| GPU, all engines of the app (%) | 15.8 [14.7–17.4] | 16.7 [15.1–26.8] | +5.7% | within noise (p ≥ 0.05) |
+| Private memory after 2 min (MB) | 1202 [1201–1213] | 1199 [1168–1218] | -0.3% | same |
+| Private memory, main process (MB) | 634 [633–641] | 624 [623–639] | -1.6% | same |
+| Private memory, renderer (MB) | 337 [337–344] | 329 [305–343] | -2.4% | same |
+| GPU dedicated memory, GPU process, after 2 min (MB) | 9252 [8989–12847] | 8567 [8009–11063] | -7.4% | within noise |
+| Editor open to first preview frame (ms) | 1025 [991–1101] | 1078 [1025–1244] | +5.2% | **regression** (p < 0.05) |
+
+Late paints per session, sorted: 2.0.0 `53 61 67 71 76 84 90 105 106 107 111 113`, main
+`54 75 76 83 88 92 111 111 111 112 114 119`. Sessions in the slow mode also use more GPU 3D in
+the main process (about 4% against 2.5 to 3%), in both builds.
+
+#### Startup (15 sessions each)
+
+| Metric | 2.0.0 | main | Delta | Verdict |
+|---|---|---|---|---|
+| Process start to HUD ready (ms) | 620 [595–678] | 651 [635–684] | +4.9% | under 5%, but significant |
+
+#### Recording, 60 s full screen with the webcam (3 takes each)
+
+| Metric | 2.0.0 | main | Delta | Verdict |
+|---|---|---|---|---|
+| Screen video, frames per second | 60.05 [60.04–60.06] | 60.00 [60.00–60.00] | -0.1% | info |
+| Screen video, longest gap between frames (ms) | 25.0 [22.7–26.2] | 18.6 [18.3–18.6] | -25.8% | improvement |
+| Screen video, frames repeating the previous picture | 660 [626–674] | 648 [645–664] | -1.8% | same |
+| Webcam video, frames per second | 29.99 [29.99–30.01] | 30.00 [30.00–30.00] | +0.0% | info |
+| Webcam video, longest gap (ms) | 37.3 [36.9–37.8] | 35.1 [35.0–35.3] | -6.1% | improvement |
+| Webcam video, byte-identical consecutive frames | 2 [2–3] | 2 [1–3] | +0.0% | same |
+| CPU, wgc-capture.exe (% of one core) | 46.8 [46.2–49.8] | 48.5 [47.6–48.6] | +3.8% | same |
+| CPU, main process (%) | 3.0 [2.9–3.5] | 3.4 [2.8–3.5] | +13.8% | within noise |
+| CPU, all processes (%) | 51.3 [50.7–55.4] | 53.2 [52.6–53.6] | +3.8% | same |
+
+No take lost a frame: no gap reaches twice the frame interval. 2.0.0's screen timestamps are
+irregular enough that `ffprobe` guesses its rate as 56 or 120 fps, where main's read a clean 60
+(`13366ebad`, `e8b85444f`, `4ebe3ce7b`). The repeated pictures come from the pattern player, which
+does not present every one of its 120 frames per second; it is the same in both builds. The
+camera, a Logitech StreamCam, delivers 1080p at 30 fps under the default 2160p request.
+
+#### Export, heavy project (60 s)
+
+| Metric | 2.0.0 | main | Delta | Verdict |
+|---|---|---|---|---|
+| MP4 1080p 60 fps: wall time (s) | 12.9 [12.8–13.0] | 12.9 [12.8–13.0] | +0.1% | same |
+| MP4 1080p 60 fps: frames written | 3600 [3600–3600] | 3600 [3600–3600] | +0.0% | info |
+| MP4 1080p 30 fps: wall time (s) | n/a | 11.6 [11.6–12.2] | n/a | n/a |
+| MP4 1080p 30 fps: frames written | n/a | 1800 [1800–1800] | n/a | n/a |
+| GIF 720p 15 fps: wall time (s) | 488.7 [484.3–493.0] | 16.2 [15.9–16.3] | -96.7% | improvement |
+| GIF 720p 15 fps: frames written | 900 [900–900] | 900 [900–900] | +0.0% | info |
+
+2.0.0 exports MP4 at 60 fps only (its CLI has no `--fps`, its dialog no frame rate), so 1080p30 has
+no baseline. Both builds write the same frames at nearly the same size (MP4 144.9 MB each, GIF 475.2
+against 475.5 MB). 2.0.0's GIF runs on one core (492 CPU
+seconds in 493 s); main spreads it over about ten (#952: `0a814fbe7`, `528ce5d9f`).
+
+## What is measured
+
+| Area | Metric | Source |
+|---|---|---|
+| Editor preview | Interval between two paints of the preview canvas: p50, p95, p99, count over 25 ms | `drawImage` on the canvas `useNativeCompositorView` marks `data-painted`, hooked over CDP |
+| Editor UI | rAF interval: p50, p99, share over 1.5 vsync | rAF loop injected over CDP |
+| What the screen showed | Preview updates per second, screen frames skipped or repeated, cursor deviation from its straight path | Desktop capture of the preview (`ddagrab`), analysed by `analyze_capture.py` |
+| Resources | CPU % per process role (main, GPU process, renderer), GPU engine % per process | `Win32_Process` CPU times; `\GPU Engine(*)\Utilization Percentage` |
+| Memory | Private bytes per role and GPU memory after 2 min of playback | `Win32_Process`; `\GPU Process Memory(*)` |
+| Startup | Process start to HUD ready; editor open to first preview frame | CDP polling |
+| Export | Wall time, frames written | `Openscreen.exe export`, `ffprobe` |
+| Recording | Frame cadence and gaps of both videos, CPU of `wgc-capture.exe` and the app | 60 s take over a 120 fps pattern, `analyze_recording.py` |
+
+`window.__uiProbe` is not used: a production build strips `console.*` (`drop_console` in
+`vite.config.ts`), so its reports never reach the console. The injected rAF loop records the same
+intervals as raw data.
+
+A change over 5% in the bad direction is a regression when it is real: a Mann-Whitney test at
+p < 0.05 with 6 sessions or more per build, non-overlapping [min–max] ranges with fewer.
+
+## Inputs
+
+Both builds read the same two projects (schema 8), generated by `gen-projects.mjs` from synthetic
+media, so neither build's recorder decides the input:
+
+- **screen.mp4**: 1920×1080, 60 fps, H.264 High, 14 Mb/s like a real Windows take. Grey noise, and a
+ white bar that moves 16 px per frame in the top band.
+- **screen.mp4.cursor.json**: a horizontal sweep at constant speed, 0.15 → 0.85 → 0.15 of the width
+ every 4 s, sampled every 8 ms.
+- **webcam.mp4**: 1920×1080, 30 fps, 16 Mb/s.
+- **Light project**: the take, one 2× zoom, plain wallpaper, no cursor motion blur.
+- **Heavy project**: webcam picture-in-picture, five zooms of which three are 3D (orbit, left,
+ right), a text, an arrow and a blur annotation, captions on (a word every 0.5 s), a music bed,
+ the wallpaper, shadow, motion blur and depth of field of a real project.
+
+## How to run
+
+1. Extract each build instead of installing it: `7z e <installer> $PLUGINSDIR/app-64.7z`, then
+ `7z x app-64.7z -o<scratch>/app-<label>`. The installed OpenScreen stays untouched, and each
+ build runs with its own `--user-data-dir`, so they never share a profile or the
+ single-instance lock.
+2. Generate the media (commands in the header of `gen-projects.mjs`), then
+ `node gen-projects.mjs <mediaDir> <scratch>/projects`.
+3. Preview sessions: `run-gui.sh <scratch> <outDir> <hz> light heavy`. Each session launches the
+ build with `--remote-debugging-port`, opens the editor through `electronAPI.switchToEditor()`
+ (the editor reopens the profile's only project), pins its window on top, plays with Space and
+ kills the process tree.
+4. `node export-bench.mjs <scratch> 3`, then `run-record.sh <scratch> record 1 2 3`. Each take is
+ analysed and deleted at once: it holds the webcam picture.
+5. `node summarize-gui.mjs <outDir>`, `node summarize-record.mjs <scratch>/out/record`, then
+ `node doc-tables.mjs` on the three summaries prints these tables.
+
+Keep the desktop to the bench while it runs. A window a background process opens lands behind
+the foreground one, which is why `topmost.ps1` pins the editor and the pattern player. A covered
+editor still renders, but the capture films the cover. A fully covered one is throttled to one
+rAF per second, and its session is discarded.