Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

43.5 KB
Raw Blame
#!/usr/bin/env python3

import atexit
import argparse
import csv
import ctypes
import hashlib
import json
import platform
import re
import statistics
import subprocess
import sys
import time
import urllib.parse
from datetime import datetime
from pathlib import Path


REPO_ROOT = Path(__file__).resolve().parent.parent
DEFAULT_RECORDINGS_DIR = (
	Path.home()
	/ "Library"
	/ "Application Support"
	/ "so.cap.desktop.dev"
	/ "recordings"
)
NUMERIC_COLUMNS = {
	"user_ns",
	"system_ns",
	"rss_bytes",
	"phys_footprint_bytes",
	"max_phys_footprint_bytes",
	"neural_footprint_bytes",
	"energy_nj",
	"disk_read_bytes",
	"disk_write_bytes",
	"logical_writes",
	"pageins",
	"idle_wakeups",
	"interrupt_wakeups",
	"instructions",
	"cycles",
	"runnable_ns",
	"threads",
	"context_switches",
	"mach_syscalls",
	"unix_syscalls",
	"faults",
}
DELTA_COLUMNS = {
	"energy_nj",
	"disk_read_bytes",
	"disk_write_bytes",
	"logical_writes",
	"pageins",
	"idle_wakeups",
	"interrupt_wakeups",
	"instructions",
	"cycles",
	"runnable_ns",
	"context_switches",
	"mach_syscalls",
	"unix_syscalls",
	"faults",
}


def run(command, check=True, timeout=30):
	result = subprocess.run(
		[str(part) for part in command],
		capture_output=True,
		text=True,
		timeout=timeout,
	)
	if check and result.returncode != 0:
		raise RuntimeError(
			f"Command failed ({result.returncode}): {' '.join(map(str, command))}\n"
			f"{result.stderr.strip()}"
		)
	return result


def capture_area(value):
	try:
		x, y, width, height = (float(part) for part in value.split(","))
	except ValueError as error:
		raise argparse.ArgumentTypeError(
			"--area must be x,y,width,height"
		) from error
	if width <= 0 or height <= 0:
		raise argparse.ArgumentTypeError("--area width and height must be positive")
	return {"x": x, "y": y, "width": width, "height": height}


def parse_args():
	parser = argparse.ArgumentParser(
		description="Profile the local macOS Instant Mode pipeline with real camera and microphone devices.",
		epilog=(
			"This starts and uploads real Instant recordings through the running "
			"development app. See scripts/instant-mode-performance.md."
		),
	)
	parser.add_argument("--label", default="baseline")
	parser.add_argument("--repetitions", type=int, default=3)
	parser.add_argument(
		"--idle-seconds",
		"--preview-seconds",
		dest="idle_seconds",
		type=float,
		default=10.0,
	)
	parser.add_argument("--start-seconds", type=float, default=6.0)
	parser.add_argument("--recording-seconds", type=float, default=30.0)
	parser.add_argument("--stop-seconds", type=float, default=8.0)
	parser.add_argument("--post-stop-seconds", type=float, default=10.0)
	parser.add_argument("--cooldown-seconds", type=float, default=5.0)
	parser.add_argument("--camera-warmup-seconds", type=float, default=8.0)
	parser.add_argument("--interval-ms", type=int, default=1000)
	parser.add_argument("--screen-name")
	capture_target = parser.add_mutually_exclusive_group()
	capture_target.add_argument("--window-name")
	capture_target.add_argument("--area", type=capture_area)
	parser.add_argument("--camera-id")
	parser.add_argument("--no-camera", action="store_true")
	parser.add_argument(
		"--camera-blur",
		choices=("off", "light", "heavy"),
	)
	parser.add_argument(
		"--expected-preview-format",
		choices=("RGBA", "NV12"),
		default="NV12",
	)
	parser.add_argument("--mic-name")
	parser.add_argument("--system-audio", action="store_true")
	parser.add_argument("--pause-seconds", type=float, default=0.0)
	parser.add_argument("--resume-seconds", type=float, default=5.0)
	parser.add_argument(
		"--cap-binary",
		type=Path,
		default=REPO_ROOT / "target" / "debug" / "cap",
	)
	parser.add_argument(
		"--recordings-dir",
		type=Path,
		default=DEFAULT_RECORDINGS_DIR,
	)
	parser.add_argument("--artifacts-dir", type=Path)
	parser.add_argument("--app-pid", type=int)
	parser.add_argument("--prepare-only", action="store_true")
	args = parser.parse_args()
	if args.repetitions < 1:
		parser.error("--repetitions must be at least 1")
	for name in (
		"idle_seconds",
		"start_seconds",
		"recording_seconds",
		"stop_seconds",
		"post_stop_seconds",
	):
		if getattr(args, name) < 2.0:
			parser.error(f"--{name.replace('_', '-')} must be at least 2 seconds")
	if args.interval_ms < 100:
		parser.error("--interval-ms must be at least 100")
	if args.camera_warmup_seconds < 0:
		parser.error("--camera-warmup-seconds must not be negative")
	if args.pause_seconds < 0:
		parser.error("--pause-seconds must not be negative")
	if 0 < args.pause_seconds < 2:
		parser.error("--pause-seconds must be at least 2 seconds when enabled")
	if args.pause_seconds > 0 and args.resume_seconds < 2:
		parser.error("--resume-seconds must be at least 2 seconds when pause is enabled")
	return args


def find_app_pid(explicit_pid):
	if explicit_pid is not None:
		if run(["kill", "-0", explicit_pid], check=False).returncode != 0:
			raise RuntimeError(f"Cap process {explicit_pid} is not running")
		return explicit_pid
	result = run(["pgrep", "-x", "cap-desktop"], check=False)
	pids = [int(value) for value in result.stdout.split() if value.isdigit()]
	if not pids:
		raise RuntimeError(
			"cap-desktop is not running. Start the existing desktop build, then rerun the harness."
		)
	if len(pids) == 1:
		return pids[0]
	by_elapsed = []
	for pid in pids:
		elapsed = run(["ps", "-p", pid, "-o", "etimes="], check=False).stdout.strip()
		if elapsed.isdigit():
			by_elapsed.append((int(elapsed), pid))
	if not by_elapsed:
		raise RuntimeError(f"Could not choose between cap-desktop processes: {pids}")
	return min(by_elapsed)[1]


def compile_sampler(artifacts_dir):
	source = REPO_ROOT / "scripts" / "instant-mode-process-sampler.c"
	binary = artifacts_dir / "instant-mode-process-sampler"
	run(
		[
			"xcrun",
			"clang",
			"-std=c11",
			"-O2",
			"-Wall",
			"-Wextra",
			"-Werror",
			str(source),
			"-o",
			str(binary),
		],
		timeout=60,
	)
	return binary


def compile_action_sender(artifacts_dir):
	source = REPO_ROOT / "scripts" / "instant-mode-action-macos.swift"
	binary = artifacts_dir / "instant-mode-action-macos"
	run(
		[
			"xcrun",
			"swiftc",
			"-O",
			str(source),
			"-o",
			str(binary),
		],
		timeout=60,
	)
	return binary


def load_targets(cap_binary):
	if not cap_binary.exists():
		raise RuntimeError(f"Cap CLI not found at {cap_binary}")
	result = run([cap_binary, "targets", "--json"], timeout=60)
	return json.loads(result.stdout)


def choose_target(items, requested, keys, preferred):
	if not items:
		raise RuntimeError("No matching capture devices were found")
	if requested:
		for item in items:
			if any(str(item.get(key)) == requested for key in keys):
				return item
		raise RuntimeError(f"Requested target not found: {requested}")
	for item in items:
		value = " ".join(str(item.get(key, "")) for key in keys)
		if preferred.lower() in value.lower():
			return item
	return items[0]


def choose_targets(targets, args):
	screens = targets.get("screens", [])
	screen = None
	if args.screen_name:
		screen = choose_target(screens, args.screen_name, ("name", "id"), "")
	else:
		screen = next((item for item in screens if item.get("primary")), None)
		screen = screen or choose_target(screens, None, ("name",), "")
	camera = choose_target(
		targets.get("cameras", []),
		args.camera_id,
		("deviceId", "displayName"),
		"MacBook Pro Camera",
	)
	mic = choose_target(
		targets.get("mics", []),
		args.mic_name,
		("name",),
		"MacBook Pro Microphone",
	)
	window = (
		choose_target(
			targets.get("windows", []),
			args.window_name,
			("name", "id"),
			"",
		)
		if args.window_name
		else None
	)
	return {
		"screen": screen,
		"window": window,
		"camera": camera,
		"mic": mic,
	}


def expected_preview_backend(recordings_dir):
	store_path = recordings_dir.parent / "store"
	if not store_path.exists():
		raise RuntimeError(f"Cap settings store not found at {store_path}")
	store = json.loads(store_path.read_text())
	settings = store.get("general_settings", {})
	return (
		"native-gpu"
		if settings.get("enableNativeCameraPreview", False)
		else "legacy-websocket"
	)


def deep_link(action, app_pid, action_sender):
	query = urllib.parse.urlencode(
		{"value": json.dumps(action, separators=(",", ":"))}
	)
	run(
		[
			action_sender,
			app_pid,
			f"cap-desktop://action?{query}",
		]
	)


def app_windows(app_pid, action_sender):
	result = run([action_sender, app_pid, "--windows"])
	return json.loads(result.stdout)


def visible_camera_windows(snapshot):
	return [
		window
		for window in snapshot["windows"]
		if window["name"] == "Cap Camera"
		and window["on_screen"]
		and window["bounds"].get("Width", 0) > 0
		and window["bounds"].get("Height", 0) > 0
	]


def wait_for_camera_window(app_pid, action_sender, timeout=8):
	deadline = time.monotonic() + timeout
	latest = None
	while time.monotonic() < deadline:
		latest = app_windows(app_pid, action_sender)
		if visible_camera_windows(latest):
			return latest
		time.sleep(0.25)
	names = [window["name"] for window in latest["windows"]] if latest else []
	raise RuntimeError(
		f"Cap Camera window is not on-screen for PID {app_pid}; windows={names}"
	)


def capture_mode(targets, args):
	if targets["window"]:
		return {"window": targets["window"]["name"]}
	if args.area:
		return {
			"area": {
				"screen": targets["screen"]["name"],
				**args.area,
			}
		}
	return {"screen": targets["screen"]["name"]}


def start_action(targets, args):
	return {
		"start_recording": {
			"capture_mode": capture_mode(targets, args),
			"camera": (
				None
				if args.no_camera
				else {"DeviceID": targets["camera"]["deviceId"]}
			),
			"mic_label": targets["mic"]["name"],
			"capture_system_audio": args.system_audio,
			"mode": "instant",
		}
	}


def open_camera_action(targets):
	return {
		"open_camera": {
			"camera": {"DeviceID": targets["camera"]["deviceId"]},
		}
	}


def set_camera_preview_state_action(state):
	return {"set_camera_preview_state": {"state": state}}


def load_camera_preview_state(recordings_dir):
	state_path = recordings_dir.parent / "cameraPreview"
	if not state_path.exists():
		return {
			"size": 230.0,
			"shape": "round",
			"mirrored": False,
			"background_blur": "off",
		}
	store = json.loads(state_path.read_text())
	return store.get("state", {})


def project_snapshot(recordings_dir):
	if not recordings_dir.exists():
		return {}
	return {
		str(project): project.stat().st_mtime_ns
		for project in recordings_dir.glob("*.cap")
		if project.is_dir()
	}


def wait_for_project(recordings_dir, before, started_ns, timeout=30):
	deadline = time.monotonic() + timeout
	while time.monotonic() < deadline:
		candidates = []
		for project in recordings_dir.glob("*.cap"):
			if not project.is_dir():
				continue
			mtime = project.stat().st_mtime_ns
			if mtime >= started_ns and before.get(str(project)) != mtime:
				candidates.append((mtime, project))
		if candidates:
			return max(candidates)[1]
		time.sleep(0.25)
	raise RuntimeError("No new .cap project appeared after the Instant Mode start action")


def process_executable(pid):
	libproc = ctypes.CDLL("/usr/lib/libproc.dylib")
	libproc.proc_pidpath.argtypes = [
		ctypes.c_int,
		ctypes.c_void_p,
		ctypes.c_uint32,
	]
	libproc.proc_pidpath.restype = ctypes.c_int
	path_buffer = ctypes.create_string_buffer(4096)
	path_length = libproc.proc_pidpath(pid, path_buffer, len(path_buffer))
	if path_length <= 0:
		raise RuntimeError(f"Could not resolve the cap-desktop executable for PID {pid}")
	executable = Path(path_buffer.value.decode())
	if not executable.exists():
		raise RuntimeError(f"Could not resolve the cap-desktop executable for PID {pid}")
	return executable


def executable_identity(executable):
	digest = hashlib.sha256()
	with executable.open("rb") as handle:
		for block in iter(lambda: handle.read(1024 * 1024), b""):
			digest.update(block)
	metadata = executable.stat()
	return {
		"path": str(executable),
		"sha256": digest.hexdigest(),
		"size_bytes": metadata.st_size,
		"modified_ns": metadata.st_mtime_ns,
	}


def associated_pids(app_pid):
	result = run(["lsappinfo", "list"])
	blocks = re.split(r"(?=^\s*\d+\) \")", result.stdout, flags=re.MULTILINE)
	app_block_index = next(
		(
			index
			for index, block in enumerate(blocks)
			if re.search(rf"\bpid = {app_pid}\b", block)
		),
		None,
	)
	if app_block_index is None:
		raise RuntimeError(f"Could not find cap-desktop PID {app_pid} in lsappinfo")
	app_name_match = re.search(r'^\s*\d+\) "([^"]+)"', blocks[app_block_index])
	if not app_name_match:
		raise RuntimeError(f"Could not resolve the application name for PID {app_pid}")
	app_name = app_name_match.group(1)
	pids = [app_pid]
	processes = [{"pid": app_pid, "role": "app", "command": "cap-desktop"}]
	for block in blocks[app_block_index + 1 :]:
		name_match = re.search(r'^\s*\d+\) "([^"]+)"', block)
		if not name_match or not name_match.group(1).startswith(f"{app_name} "):
			break
		pid_match = re.search(r"\bpid = (\d+)\b", block)
		bundle_match = re.search(r'bundleID="([^"]+)"', block)
		if not pid_match or not bundle_match:
			continue
		command = bundle_match.group(1)
		if not command.startswith("com.apple.WebKit."):
			continue
		pid = int(pid_match.group(1))
		role_match = re.search(r"com\.apple\.WebKit\.([^.]+)", command)
		role = f"webkit-{role_match.group(1).lower()}" if role_match else "webkit"
		pids.append(pid)
		processes.append({"pid": pid, "role": role, "command": command})
	process_rows = [
		line.split(None, 2)
		for line in run(["ps", "-axo", "pid=,ppid=,comm="]).stdout.splitlines()
	]
	known_pids = set(pids)
	while True:
		children = [
			(int(row[0]), row[2])
			for row in process_rows
			if len(row) == 3
			and int(row[1]) in known_pids
			and int(row[0]) not in known_pids
		]
		if not children:
			break
		for pid, command in children:
			known_pids.add(pid)
			pids.append(pid)
			processes.append({"pid": pid, "role": "child", "command": command})
	if len(pids) > 64:
		raise RuntimeError(f"Too many associated processes to sample: {len(pids)}")
	return pids, processes


def integer(value):
	try:
		return int(value)
	except (TypeError, ValueError):
		return 0


def nettop_snapshot(app_pid):
	result = run(
		[
			"nettop",
			"-n",
			"-L",
			"1",
			"-J",
			"bytes_in,bytes_out,interface,state",
			"-p",
			app_pid,
		],
		check=False,
		timeout=15,
	)
	aggregate = {"bytes_in": 0, "bytes_out": 0}
	connections = {}
	for row in csv.reader(result.stdout.splitlines()):
		if len(row) < 5 or not row[0]:
			continue
		if row[0].startswith("cap-desktop."):
			aggregate = {
				"bytes_in": integer(row[3]),
				"bytes_out": integer(row[4]),
			}
		elif row[0].startswith(("tcp", "udp")):
			connections[row[0]] = {
				"interface": row[1],
				"state": row[2],
				"bytes_in": integer(row[3]),
				"bytes_out": integer(row[4]),
			}
	return {
		"aggregate": aggregate,
		"connections": connections,
		"raw": result.stdout,
	}


def counter_delta(after, before, key):
	return max(0, integer(after.get(key)) - integer(before.get(key)))


def network_delta(before, after, elapsed):
	aggregate = {
		key: counter_delta(after["aggregate"], before["aggregate"], key)
		for key in ("bytes_in", "bytes_out")
	}
	connection_deltas = []
	for endpoint in set(before["connections"]) | set(after["connections"]):
		before_item = before["connections"].get(endpoint, {})
		after_item = after["connections"].get(endpoint, {})
		connection_deltas.append(
			{
				"endpoint": endpoint,
				"interface": after_item.get("interface")
				or before_item.get("interface"),
				"state": after_item.get("state") or before_item.get("state"),
				"bytes_in": counter_delta(after_item, before_item, "bytes_in"),
				"bytes_out": counter_delta(after_item, before_item, "bytes_out"),
			}
		)
	local = {
		key: sum(
			item[key]
			for item in connection_deltas
			if item["interface"] == "lo0"
		)
		for key in ("bytes_in", "bytes_out")
	}
	remote = {
		key: max(0, aggregate[key] - local[key])
		for key in ("bytes_in", "bytes_out")
	}
	camera_connection = max(
		(
			item
			for item in connection_deltas
			if item["interface"] == "lo0" and item["state"] == "Established"
		),
		key=lambda item: item["bytes_in"] + item["bytes_out"],
		default=None,
	)
	camera_bytes = (
		camera_connection["bytes_in"] + camera_connection["bytes_out"]
		if camera_connection
		else 0
	)
	if elapsed <= 0 or camera_bytes / elapsed < 64 * 1024:
		camera_connection = None
		camera_bytes = 0
	aggregate_bytes = aggregate["bytes_in"] + aggregate["bytes_out"]
	return {
		"aggregate": aggregate,
		"localhost": local,
		"remote": remote,
		"camera_preview_connection": camera_connection,
		"camera_preview_bytes_per_second": (
			camera_bytes / elapsed
			if elapsed > 0
			else 0.0
		),
		"non_preview_bytes_per_second": (
			max(0, aggregate_bytes - camera_bytes) / elapsed
			if elapsed > 0
			else 0.0
		),
		"remote_bytes_per_second": (
			(remote["bytes_in"] + remote["bytes_out"]) / elapsed
			if elapsed > 0
			else 0.0
		),
		"connections": connection_deltas,
	}


def wait_for_preview_traffic(app_pid, timeout=12):
	deadline = time.monotonic() + timeout
	latest = None
	while time.monotonic() < deadline:
		before = nettop_snapshot(app_pid)
		started = time.monotonic()
		time.sleep(1)
		after = nettop_snapshot(app_pid)
		latest = network_delta(before, after, time.monotonic() - started)
		if latest["camera_preview_bytes_per_second"] >= 64 * 1024:
			return latest
	raise RuntimeError(
		"Legacy camera preview did not begin transferring frames; "
		f"latest={latest}"
	)


def gpu_snapshot():
	result = run(
		["ioreg", "-r", "-d", "1", "-c", "AGXAccelerator"],
		check=False,
		timeout=15,
	)
	match = re.search(r'"PerformanceStatistics" = \{([^}]*)\}', result.stdout)
	if not match:
		return {}
	values = {
		key: int(value)
		for key, value in re.findall(r'"([^"]+)"=(\d+)', match.group(1))
	}
	return {
		"device_utilization_pct": values.get("Device Utilization %"),
		"renderer_utilization_pct": values.get("Renderer Utilization %"),
		"tiler_utilization_pct": values.get("Tiler Utilization %"),
		"in_use_system_memory_bytes": values.get("In use system memory"),
		"allocated_system_memory_bytes": values.get("Alloc system memory"),
	}


def system_snapshot():
	thermal = run(["pmset", "-g", "therm"], check=False).stdout.strip()
	memory_pressure = run(
		["sysctl", "-n", "vm.memory_pressure"], check=False
	).stdout.strip()
	return {
		"thermal": thermal,
		"vm_memory_pressure": integer(memory_pressure),
	}


def sampled_cpu_seconds(rows):
	previous_elapsed = 0.0
	cpu_seconds = 0.0
	for row in rows:
		interval = row["elapsed_s"] - previous_elapsed
		cpu_seconds += row["cpu_pct"] * interval / 100
		previous_elapsed = row["elapsed_s"]
	return cpu_seconds


def summarize_process_csv(csv_path, app_pid, expected_pids=None):
	rows = []
	with csv_path.open(newline="") as handle:
		for row in csv.DictReader(handle):
			row["sample"] = integer(row["sample"])
			row["pid"] = integer(row["pid"])
			row["elapsed_s"] = float(row["elapsed_s"])
			row["cpu_pct"] = float(row["cpu_pct"])
			for column in NUMERIC_COLUMNS:
				row[column] = integer(row[column])
			rows.append(row)
	if not rows:
		raise RuntimeError(f"No process samples were collected in {csv_path}")
	by_sample = {}
	for row in rows:
		by_sample.setdefault(row["sample"], []).append(row)
	expected_pids = set(expected_pids or (row["pid"] for row in rows))
	complete_samples = list(by_sample) == list(range(1, len(by_sample) + 1)) and all(
		len(sample_rows) == len(expected_pids)
		and {row["pid"] for row in sample_rows} == expected_pids
		for sample_rows in by_sample.values()
	)
	group_samples = []
	for sample_rows in by_sample.values():
		group_samples.append(
			{
				"elapsed_s": max(row["elapsed_s"] for row in sample_rows),
				"cpu_pct": sum(row["cpu_pct"] for row in sample_rows),
				"rss_bytes": sum(row["rss_bytes"] for row in sample_rows),
				"phys_footprint_bytes": sum(
					row["phys_footprint_bytes"] for row in sample_rows
				),
				"threads": sum(row["threads"] for row in sample_rows),
			}
		)
	app_rows = [row for row in rows if row["pid"] == app_pid]
	first_by_pid = {}
	last_by_pid = {}
	for row in rows:
		first_by_pid.setdefault(row["pid"], row)
		last_by_pid[row["pid"]] = row
	process_breakdown = []
	for pid in sorted(last_by_pid):
		pid_rows = [row for row in rows if row["pid"] == pid]
		process_breakdown.append(
			{
				"pid": pid,
				"name": pid_rows[-1]["name"],
				"cpu_median_pct": statistics.median(
					row["cpu_pct"] for row in pid_rows
				),
				"cpu_average_pct": (
					sampled_cpu_seconds(pid_rows)
					/ max(pid_rows[-1]["elapsed_s"], 0.001)
					* 100
				),
				"physical_footprint_mib_median": statistics.median(
					row["phys_footprint_bytes"] for row in pid_rows
				)
				/ 1024
				/ 1024,
			}
		)
	deltas = {}
	for column in DELTA_COLUMNS:
		deltas[column] = sum(
			max(0, last_by_pid[pid][column] - first_by_pid[pid][column])
			for pid in last_by_pid
		)
	elapsed = max(item["elapsed_s"] for item in group_samples)
	counter_elapsed = elapsed - group_samples[0]["elapsed_s"]
	cpu_time_seconds = sampled_cpu_seconds(group_samples)

	def counter_rate(column, divisor=1):
		return deltas[column] / divisor / counter_elapsed if counter_elapsed > 0 else None

	return {
		"sample_count": len(group_samples),
		"process_count": len(last_by_pid),
		"complete_samples": complete_samples,
		"elapsed_seconds": elapsed,
		"counter_elapsed_seconds": counter_elapsed,
		"cpu_median_pct": statistics.median(
			item["cpu_pct"] for item in group_samples
		),
		"cpu_min_pct": min(item["cpu_pct"] for item in group_samples),
		"cpu_max_pct": max(item["cpu_pct"] for item in group_samples),
		"cpu_time_seconds": cpu_time_seconds,
		"cpu_average_pct": cpu_time_seconds / elapsed * 100 if elapsed > 0 else 0,
		"app_cpu_median_pct": (
			statistics.median(row["cpu_pct"] for row in app_rows)
			if app_rows
			else None
		),
		"process_breakdown": process_breakdown,
		"rss_median_bytes": statistics.median(
			item["rss_bytes"] for item in group_samples
		),
		"rss_peak_bytes": max(item["rss_bytes"] for item in group_samples),
		"phys_footprint_median_bytes": statistics.median(
			item["phys_footprint_bytes"] for item in group_samples
		),
		"phys_footprint_peak_bytes": max(
			item["phys_footprint_bytes"] for item in group_samples
		),
		"phys_footprint_growth_bytes": (
			group_samples[-1]["phys_footprint_bytes"]
			- group_samples[0]["phys_footprint_bytes"]
		),
		"thread_median": statistics.median(
			item["threads"] for item in group_samples
		),
		"disk_read_bytes_per_second": counter_rate("disk_read_bytes"),
		"disk_write_bytes_per_second": counter_rate("disk_write_bytes"),
		"energy_millijoules_per_second": counter_rate("energy_nj", 1_000_000),
		"instructions_per_second": counter_rate("instructions"),
		"cycles_per_second": counter_rate("cycles"),
		"faults_per_second": counter_rate("faults"),
		"wakeups_per_second": (
			(deltas["idle_wakeups"] + deltas["interrupt_wakeups"]) / counter_elapsed
			if counter_elapsed > 0 else None
		),
		"context_switches_per_second": counter_rate("context_switches"),
		"mach_syscalls_per_second": counter_rate("mach_syscalls"),
		"unix_syscalls_per_second": counter_rate("unix_syscalls"),
		"deltas": deltas,
	}


def summarize_gpu(samples):
	summary = {"scope": "system-wide AGX counters"}
	for key in (
		"device_utilization_pct",
		"renderer_utilization_pct",
		"tiler_utilization_pct",
		"in_use_system_memory_bytes",
		"allocated_system_memory_bytes",
	):
		values = [sample[key] for sample in samples if sample.get(key) is not None]
		if values:
			summary[f"{key}_median"] = statistics.median(values)
			summary[f"{key}_max"] = max(values)
	return summary


def measure_phase(
	name,
	duration,
	artifact_dir,
	sampler_binary,
	app_pid,
	interval_ms,
	trigger=None,
):
	pids, processes = associated_pids(app_pid)
	csv_path = artifact_dir / f"{name}-processes.csv"
	network_before = nettop_snapshot(app_pid)
	(artifact_dir / f"{name}-network-before.txt").write_text(
		network_before["raw"]
	)
	system_before = system_snapshot()
	gpu_samples = [gpu_snapshot()]
	with csv_path.open("w") as output:
		process = subprocess.Popen(
			[
				str(sampler_binary),
				str(duration),
				str(interval_ms),
				*[str(pid) for pid in pids],
			],
			stdout=output,
			stderr=subprocess.PIPE,
			text=True,
		)
		phase_started = time.monotonic()
		if trigger:
			trigger()
		for fraction in (0.5, 0.9):
			target = phase_started + duration * fraction
			delay = target - time.monotonic()
			if delay > 0:
				time.sleep(delay)
			gpu_samples.append(gpu_snapshot())
		stderr = process.communicate(timeout=max(5, duration + 5))[1]
		if process.returncode != 0:
			raise RuntimeError(f"Process sampler failed in {name}: {stderr.strip()}")
	elapsed = time.monotonic() - phase_started
	network_after = nettop_snapshot(app_pid)
	(artifact_dir / f"{name}-network-after.txt").write_text(
		network_after["raw"]
	)
	system_after = system_snapshot()
	after_pids, after_processes = associated_pids(app_pid)
	process_summary = summarize_process_csv(csv_path, app_pid, pids)
	processes_stable = set(pids) == set(after_pids)
	return {
		"name": name,
		"duration_seconds": elapsed,
		"processes": processes,
		"processes_after": after_processes,
		"processes_stable": processes_stable,
		"valid_for_comparison": processes_stable and process_summary["complete_samples"],
		"process_metrics": process_summary,
		"network": network_delta(network_before, network_after, elapsed),
		"gpu": summarize_gpu(gpu_samples),
		"system_before": system_before,
		"system_after": system_after,
		"raw_process_csv": str(csv_path),
	}


def wait_for_recording_complete(project, timeout=45):
	meta_path = project / "recording-meta.json"
	deadline = time.monotonic() + timeout
	last_meta = None
	while time.monotonic() < deadline:
		if meta_path.exists():
			try:
				last_meta = json.loads(meta_path.read_text())
			except json.JSONDecodeError:
				last_meta = None
			if (
				last_meta
				and last_meta.get("upload", {}).get("state") == "Complete"
			):
				return last_meta
		time.sleep(0.5)
	return last_meta


def directory_size(path):
	return sum(
		item.stat().st_size
		for item in path.rglob("*")
		if item.is_file()
	)


def validate_project(project):
	meta_path = project / "recording-meta.json"
	log_path = project / "recording-logs.log"
	manifest_path = project / "content" / "display" / "manifest.json"
	meta = json.loads(meta_path.read_text()) if meta_path.exists() else {}
	manifest = json.loads(manifest_path.read_text()) if manifest_path.exists() else {}
	codec = manifest.get("codec_info", {})
	segments = manifest.get("segments", [])
	log = log_path.read_text(errors="replace") if log_path.exists() else ""
	drop_matches = re.findall(
		r"Screen capture stats frames=(\d+) drops=(\d+) "
		r'drop_rate_pct="([^"]+)%" total_frames=(\d+)',
		log,
	)
	captured_frame_matches = re.findall(
		r"Capturer stopping after creating (\d+) video frames",
		log,
	)
	ws_matches = re.findall(
		r'WS frame stats fps=(\d+) mb_per_sec="([^"]+)" .* '
		r'dims="(\d+)x(\d+)" format="([^"]+)"',
		log,
	)
	active_ws_matches = [match for match in ws_matches if int(match[0]) > 0]
	camera_capture = {
		"selected": "Selected camera locked for recording camera_selected=true" in log,
		"native_sender_attached": "CameraFeed: Adding new native sender" in log,
		"availability_checks": len(
			re.findall(r"is_camera_available: looking for DeviceID", log)
		),
	}
	error_lines = [line for line in log.splitlines() if " ERROR " in line]
	audio_paths = [
		str(path.relative_to(project))
		for path in (project / "content").rglob("*")
		if path.is_file() and "display" not in path.parts
	]
	audio_manifest_path = project / "content" / "audio" / "manifest.json"
	audio_manifest = (
		json.loads(audio_manifest_path.read_text())
		if audio_manifest_path.exists()
		else {}
	)
	audio_segments = audio_manifest.get("segments", [])
	return {
		"project": str(project),
		"project_size_bytes": directory_size(project),
		"sharing": meta.get("sharing"),
		"upload_state": meta.get("upload", {}).get("state"),
		"metadata_fps": meta.get("fps"),
		"sample_rate": meta.get("sample_rate"),
		"microphone_present": bool(audio_segments),
		"audio_codec": audio_manifest.get("codec_info"),
		"audio_segments_complete": bool(audio_segments)
		and all(segment.get("is_complete") for segment in audio_segments),
		"codec": codec,
		"segment_count": len(segments),
		"segments_complete": bool(segments)
		and all(segment.get("is_complete") for segment in segments),
		"duration_seconds": manifest.get("total_duration"),
		"manifest_complete": manifest.get("is_complete"),
		"audio_paths": audio_paths,
		"last_capture_health": (
			{
				"frames": int(drop_matches[-1][0]),
				"drops": int(drop_matches[-1][1]),
				"drop_rate_pct": float(drop_matches[-1][2]),
				"total_frames": int(drop_matches[-1][3]),
			}
			if drop_matches
			else None
		),
		"captured_frames_on_stop": (
			int(captured_frame_matches[-1]) if captured_frame_matches else None
		),
		"camera_capture": camera_capture,
		"preview_backend": (
			"legacy-websocket"
			if active_ws_matches
			else "native-gpu"
			if camera_capture["selected"]
			else "none"
		),
		"webcam_preview": (
			{
				"fps": statistics.median(
					int(match[0]) for match in active_ws_matches
				),
				"megabytes_per_second": statistics.median(
					float(match[1]) for match in active_ws_matches
				),
				"width": int(active_ws_matches[-1][2]),
				"height": int(active_ws_matches[-1][3]),
				"format": active_ws_matches[-1][4],
			}
			if active_ws_matches
			else None
		),
		"error_lines": error_lines,
	}


def project_validation_errors(
	validation,
	no_camera,
	phases,
	camera_window_checks,
	expected_backend,
	expected_preview_format,
):
	errors = []
	codec = validation["codec"]
	if validation["upload_state"] != "Complete":
		errors.append(f"upload state is {validation['upload_state']!r}")
	if not validation["sharing"]:
		errors.append("sharing metadata is missing")
	if validation["metadata_fps"] != 30:
		errors.append(f"metadata frame rate is {validation['metadata_fps']!r}")
	if not validation["microphone_present"]:
		errors.append("microphone track is missing")
	if not validation["audio_segments_complete"]:
		errors.append("audio segments are incomplete")
	if not validation["segments_complete"] or not validation["manifest_complete"]:
		errors.append("video segments or manifest are incomplete")
	if codec.get("width", 0) <= 0 or codec.get("height", 0) <= 0:
		errors.append("video dimensions are missing")
	if codec.get("frame_rate_num") != 30 or codec.get("frame_rate_den") != 1:
		errors.append(f"video frame rate is {codec.get('frame_rate_num')}/{codec.get('frame_rate_den')}")
	if codec.get("pixel_format") != "NV12":
		errors.append(f"video pixel format is {codec.get('pixel_format')!r}")
	if validation["error_lines"]:
		errors.append(f"recording log contains {len(validation['error_lines'])} errors")
	health = validation["last_capture_health"]
	if not health:
		if not validation["captured_frames_on_stop"]:
			errors.append("screen capture health metrics are missing")
	elif health["drop_rate_pct"] > 0.5:
		errors.append(f"screen capture drop rate is {health['drop_rate_pct']}%")
	webcam = validation["webcam_preview"]
	camera_capture = validation["camera_capture"]
	idle_phase = next(phase for phase in phases if phase["name"] == "idle")
	recording_phase = next(phase for phase in phases if phase["name"] == "recording")
	idle_preview_bytes = idle_phase["network"]["camera_preview_bytes_per_second"]
	preview_bytes = recording_phase["network"]["camera_preview_bytes_per_second"]
	if no_camera:
		if camera_capture["selected"] or camera_capture["native_sender_attached"]:
			errors.append("camera capture was active during a camera-off run")
		if webcam and webcam["fps"] > 0:
			errors.append("webcam preview was active during a camera-off run")
		if preview_bytes >= 64 * 1024:
			errors.append("webcam preview IPC was active during a camera-off run")
	else:
		if validation["preview_backend"] != expected_backend:
			errors.append(
				f"camera preview backend is {validation['preview_backend']!r}, "
				f"expected {expected_backend!r}"
			)
		for name, snapshot in camera_window_checks.items():
			if not visible_camera_windows(snapshot):
				errors.append(f"Cap Camera window was not on-screen at {name}")
		if not camera_capture["selected"]:
			errors.append("the selected camera was not locked into the Instant pipeline")
		if not camera_capture["native_sender_attached"]:
			errors.append("the native camera sender was not attached")
		if camera_capture["availability_checks"] < 1:
			errors.append("camera availability was not monitored during recording")
		if webcam:
			if idle_preview_bytes < 64 * 1024:
				errors.append("legacy webcam preview IPC was not active before recording")
			if webcam["fps"] <= 0:
				errors.append("webcam preview frame rate is zero")
			if webcam["width"] <= 0 or webcam["height"] <= 0:
				errors.append("webcam preview dimensions are missing")
			if webcam["format"] != expected_preview_format:
				errors.append(
					f"webcam preview format is {webcam['format']!r}, "
					f"expected {expected_preview_format!r}"
				)
			if preview_bytes < 64 * 1024:
				errors.append("legacy webcam preview IPC was not active during recording")
	return errors


def aggregate_runs(runs):
	phase_names = []
	for run_result in runs:
		for phase in run_result["phases"]:
			if phase["name"] not in phase_names:
				phase_names.append(phase["name"])
	metrics = (
		("cpu_median_pct", "process_metrics"),
		("cpu_average_pct", "process_metrics"),
		("app_cpu_median_pct", "process_metrics"),
		("phys_footprint_median_bytes", "process_metrics"),
		("phys_footprint_peak_bytes", "process_metrics"),
		("phys_footprint_growth_bytes", "process_metrics"),
		("rss_median_bytes", "process_metrics"),
		("disk_read_bytes_per_second", "process_metrics"),
		("disk_write_bytes_per_second", "process_metrics"),
		("energy_millijoules_per_second", "process_metrics"),
		("instructions_per_second", "process_metrics"),
		("cycles_per_second", "process_metrics"),
		("faults_per_second", "process_metrics"),
		("wakeups_per_second", "process_metrics"),
		("context_switches_per_second", "process_metrics"),
		("mach_syscalls_per_second", "process_metrics"),
		("unix_syscalls_per_second", "process_metrics"),
		("camera_preview_bytes_per_second", "network"),
		("non_preview_bytes_per_second", "network"),
		("remote_bytes_per_second", "network"),
	)
	output = {}
	for phase_name in phase_names:
		phase_output = {}
		for metric, section in metrics:
			values = [
				phase[section][metric]
				for run_result in runs
				for phase in run_result["phases"]
				if phase["name"] == phase_name
				and phase.get("valid_for_comparison", True)
				and phase[section].get(metric) is not None
			]
			if values:
				phase_output[metric] = {
					"median": statistics.median(values),
					"min": min(values),
					"max": max(values),
				}
		output[phase_name] = phase_output
	return output


def print_summary(summary):
	print(f"Artifacts: {summary['artifacts_dir']}")
	target = (
		summary["targets"]["window"]["name"]
		if summary["targets"]["window"]
		else (
			f"area {summary['configuration']['area']}"
			if summary["configuration"]["area"]
			else summary["targets"]["screen"]["name"]
		)
	)
	print(
		f"Target: {target} | "
		f"{'camera off' if summary['configuration']['no_camera'] else summary['targets']['camera']['displayName']} | "
		f"{summary['targets']['mic']['name']}"
	)
	print(
		"phase          cpu median    footprint    disk write    preview IPC     other net"
	)
	for name, phase in summary["aggregate"].items():
		if not phase:
			print(f"{name:<14} incomplete process coverage; inspect raw phase results")
			continue
		cpu = phase.get("cpu_median_pct", {}).get("median", 0)
		memory = (
			phase.get("phys_footprint_median_bytes", {}).get("median", 0)
			/ 1024
			/ 1024
		)
		preview = (
			phase.get("camera_preview_bytes_per_second", {}).get("median", 0)
			/ 1024
			/ 1024
		)
		disk_write = (
			phase.get("disk_write_bytes_per_second", {}).get("median", 0)
			/ 1024
			/ 1024
		)
		non_preview = (
			phase.get("non_preview_bytes_per_second", {}).get("median", 0)
			/ 1024
			/ 1024
		)
		print(
			f"{name:<14} {cpu:>8.1f}% {memory:>9.1f} MiB "
			f"{disk_write:>8.2f} MiB/s {preview:>8.2f} MiB/s "
			f"{non_preview:>8.2f} MiB/s"
		)
	for run_result in summary["runs"]:
		validation = run_result["validation"]
		print(
			f"run {run_result['index']}: "
			f"{validation['codec'].get('width')}x"
			f"{validation['codec'].get('height')} "
			f"{validation['codec'].get('frame_rate_num')}fps, "
			f"audio={validation['microphone_present']}, "
			f"camera={validation['preview_backend']}, "
			f"upload={validation['upload_state']}, "
			f"errors={len(validation['error_lines'])}, "
			f"{validation['project']}"
		)


def main():
	args = parse_args()
	if platform.system() != "Darwin":
		raise RuntimeError("This harness requires macOS")
	timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
	safe_label = re.sub(r"[^A-Za-z0-9_.-]+", "-", args.label).strip("-")
	artifacts_dir = args.artifacts_dir or Path(
		f"/private/tmp/cap-instant-mode-{safe_label}-{timestamp}"
	)
	artifacts_dir.mkdir(parents=True, exist_ok=False)
	sampler_binary = compile_sampler(artifacts_dir)
	action_sender = compile_action_sender(artifacts_dir)
	app_pid = find_app_pid(args.app_pid)
	app_executable = process_executable(app_pid)
	expected_executable = (REPO_ROOT / "target" / "debug" / "cap-desktop").resolve()
	if app_executable.resolve() != expected_executable:
		raise RuntimeError(
			f"PID {app_pid} is {app_executable}, expected the local app at {expected_executable}"
		)
	targets = choose_targets(load_targets(args.cap_binary), args)
	preview_backend = expected_preview_backend(args.recordings_dir)
	expected_preview_format = (
		"RGBA"
		if args.camera_blur and args.camera_blur != "off"
		else args.expected_preview_format
	)
	preview_state_override = None
	if args.camera_blur:
		original_preview_state = load_camera_preview_state(args.recordings_dir)
		preview_state_override = {
			**original_preview_state,
			"background_blur": args.camera_blur,
		}
		atexit.register(
			deep_link,
			set_camera_preview_state_action(original_preview_state),
			app_pid,
			action_sender,
		)
	configuration = {
		"label": args.label,
		"repetitions": args.repetitions,
		"idle_seconds": args.idle_seconds,
		"start_seconds": args.start_seconds,
		"recording_seconds": args.recording_seconds,
		"stop_seconds": args.stop_seconds,
		"post_stop_seconds": args.post_stop_seconds,
		"cooldown_seconds": args.cooldown_seconds,
		"camera_warmup_seconds": args.camera_warmup_seconds,
		"interval_ms": args.interval_ms,
		"system_audio": args.system_audio,
		"no_camera": args.no_camera,
		"camera_blur": args.camera_blur,
		"expected_preview_format": expected_preview_format,
		"window_name": args.window_name,
		"area": args.area,
		"pause_seconds": args.pause_seconds,
		"resume_seconds": args.resume_seconds,
		"app_pid": app_pid,
		"app_executable": str(app_executable),
		"cap_binary": str(args.cap_binary),
		"recordings_dir": str(args.recordings_dir),
		"expected_preview_backend": preview_backend,
	}
	prepared = {
		"schema_version": 1,
		"created_at": datetime.now().astimezone().isoformat(),
		"repository_root": str(REPO_ROOT),
		"git_commit": run(["git", "rev-parse", "HEAD"]).stdout.strip(),
		"git_status": run(["git", "status", "--porcelain"]).stdout.strip(),
		"app_binary": executable_identity(app_executable),
		"cap_binary": executable_identity(args.cap_binary),
		"configuration": configuration,
		"targets": targets,
		"artifacts_dir": str(artifacts_dir),
	}
	(artifacts_dir / "prepared.json").write_text(
		json.dumps(prepared, indent=2) + "\n"
	)
	if args.prepare_only:
		print(json.dumps(prepared, indent=2))
		return

	args.recordings_dir.mkdir(parents=True, exist_ok=True)
	runs = []
	for index in range(1, args.repetitions + 1):
		camera_window_checks = {}
		preview_readiness = {}
		if not args.no_camera:
			print(f"run {index}/{args.repetitions}: open camera", flush=True)
			deep_link(open_camera_action(targets), app_pid, action_sender)
			if preview_state_override:
				deep_link(
					set_camera_preview_state_action(preview_state_override),
					app_pid,
					action_sender,
				)
			time.sleep(args.camera_warmup_seconds)
			camera_window_checks["idle_start"] = wait_for_camera_window(
				app_pid,
				action_sender,
			)
			preview_readiness["idle_start"] = wait_for_preview_traffic(app_pid)
		print(f"run {index}/{args.repetitions}: idle", flush=True)
		run_dir = artifacts_dir / f"run-{index:02d}"
		run_dir.mkdir()
		phases = [
			measure_phase(
				"idle",
				args.idle_seconds,
				run_dir,
				sampler_binary,
				app_pid,
				args.interval_ms,
			)
		]
		before = project_snapshot(args.recordings_dir)
		started_ns = time.time_ns()
		print(f"run {index}/{args.repetitions}: start", flush=True)
		phases.append(
			measure_phase(
				"start",
				args.start_seconds,
				run_dir,
				sampler_binary,
					app_pid,
					args.interval_ms,
					trigger=lambda: deep_link(
						start_action(targets, args),
						app_pid,
						action_sender,
					),
				)
		)
		project = wait_for_project(args.recordings_dir, before, started_ns)
		if not args.no_camera:
			print(f"run {index}/{args.repetitions}: verify camera", flush=True)
			camera_window_checks["recording_start"] = wait_for_camera_window(
				app_pid,
				action_sender,
			)
			preview_readiness["recording_start"] = wait_for_preview_traffic(
				app_pid
			)
		print(f"run {index}/{args.repetitions}: recording", flush=True)
		phases.append(
			measure_phase(
				"recording",
				args.recording_seconds,
				run_dir,
				sampler_binary,
				app_pid,
				args.interval_ms,
			)
		)
		if args.pause_seconds > 0:
			print(f"run {index}/{args.repetitions}: pause", flush=True)
			phases.append(
				measure_phase(
					"paused",
					args.pause_seconds,
					run_dir,
					sampler_binary,
					app_pid,
					args.interval_ms,
					trigger=lambda: deep_link(
						"pause_recording",
						app_pid,
						action_sender,
					),
				)
			)
			print(f"run {index}/{args.repetitions}: resume", flush=True)
			phases.append(
				measure_phase(
					"resumed",
					args.resume_seconds,
					run_dir,
					sampler_binary,
					app_pid,
					args.interval_ms,
					trigger=lambda: deep_link(
						"resume_recording",
						app_pid,
						action_sender,
					),
				)
			)
		if not args.no_camera:
			camera_window_checks["recording_end"] = app_windows(
				app_pid,
				action_sender,
			)
		print(f"run {index}/{args.repetitions}: stop", flush=True)
		phases.append(
			measure_phase(
				"stop",
				args.stop_seconds,
				run_dir,
				sampler_binary,
				app_pid,
				args.interval_ms,
				trigger=lambda: deep_link(
					"stop_recording",
					app_pid,
					action_sender,
				),
			)
		)
		meta = wait_for_recording_complete(project)
		print(f"run {index}/{args.repetitions}: post-stop", flush=True)
		phases.append(
			measure_phase(
				"post_stop",
				args.post_stop_seconds,
				run_dir,
				sampler_binary,
				app_pid,
				args.interval_ms,
			)
		)
		validation = validate_project(project)
		if meta and not validation["upload_state"]:
			validation["upload_state"] = meta.get("upload", {}).get("state")
		validation_errors = project_validation_errors(
			validation,
			args.no_camera,
			phases,
			camera_window_checks,
			preview_backend,
			expected_preview_format,
		)
		run_result = {
			"index": index,
			"phases": phases,
			"camera_window_checks": camera_window_checks,
			"preview_readiness": preview_readiness,
			"validation": validation,
			"validation_errors": validation_errors,
		}
		(run_dir / "result.json").write_text(
			json.dumps(run_result, indent=2) + "\n"
		)
		if validation_errors:
			raise RuntimeError(
				f"run {index} failed validation: {'; '.join(validation_errors)}"
			)
		runs.append(run_result)
		if index < args.repetitions and args.cooldown_seconds > 0:
			time.sleep(args.cooldown_seconds)

	summary = {
		**prepared,
		"runs": runs,
		"aggregate": aggregate_runs(runs),
	}
	summary_path = artifacts_dir / "summary.json"
	summary_path.write_text(json.dumps(summary, indent=2) + "\n")
	print_summary(summary)


if __name__ == "__main__":
	try:
		main()
	except (RuntimeError, subprocess.TimeoutExpired, json.JSONDecodeError) as error:
		print(f"error: {error}", file=sys.stderr)
		sys.exit(1)