record-screen

Record screen

Video is the reviewer's main evidence for UI work. Record around the part of the run that shows the change, then attach the MP4.

• Linux cloud session: record the whole virtual X display with sections 1–3. Nothing else runs on it, so the whole display is safe to capture.
• macOS: the screen is the user's real desktop, with personal windows and notifications. Never record the full display. Use the macOS section, then continue at section 4.

Linux: 1. Start (just before the app launches)

Run as one command. It reuses a running display, else starts Xvfb on :99; installs ffmpeg if missing (about 30s with apt); records at 15 fps in the background.

REC=/tmp/record-screen; mkdir -p "$REC"; SUDO=$([ "$(id -u)" = 0 ] || echo sudo)
export DISPLAY=${DISPLAY:-:99}; d=${DISPLAY#*:}; d=${d%%.*}
if [ ! -S "/tmp/.X11-unix/X$d" ]; then
  command -v Xvfb >/dev/null || { $SUDO apt-get update -q || true; $SUDO apt-get install -y -q --no-install-recommends xvfb; }
  setsid nohup Xvfb "$DISPLAY" -screen 0 1920x1080x24 -nolisten tcp >"$REC/xvfb.log" 2>&1 &
  timeout 10 sh -c "until [ -S /tmp/.X11-unix/X$d ]; do sleep 0.2; done"
fi
command -v ffmpeg >/dev/null || { $SUDO apt-get update -q || true; $SUDO apt-get install -y -q --no-install-recommends ffmpeg; }
rm -f "$REC/raw.mkv"
setsid nohup ffmpeg -loglevel error -f x11grab -framerate 15 -draw_mouse 0 -i "$DISPLAY" \
  -c:v libx264 -preset ultrafast -crf 18 "$REC/raw.mkv" >"$REC/ffmpeg.log" 2>&1 &
echo $! >"$REC/ffmpeg.pid"; echo "recording $DISPLAY (pid $(cat "$REC/ffmpeg.pid"))"

The app under test must use the same DISPLAY. If you started Xvfb here, prefix later commands with DISPLAY=:99, since shell exports do not carry across tool calls.

Linux: 2. Demonstrate

Drive the app so the change is visible: open the affected screens, pause about 2 seconds on each (waitForTimeout in Playwright is fine for pacing), and show the before and after state where it applies. Nothing but the app appears on a virtual display, and Playwright clicks do not move a pointer, so screens change without a visible cursor.