Cloud Screencast

cloud-screencast — reproducible UI demo videos on a throwaway VM

Records a web UI on a headless cloud box instead of the user's desktop. You get a pristine app state, a chosen viewport, no personal data in frame, and a scripted take you can re-run until it's right — none of which is true of a hand-recorded local screen capture.

Cost + lifecycle: this creates a billable VM. Always tell the user it exists, and delete it when the recording is downloaded (§8). An e2-standard-4 left running is roughly $95/month.

Config

Fill once per project, then run.

PROJECT   = <gcp-project-id>
ZONE      = <zone, e.g. us-central1-a>
VM        = <instance-name, e.g. app-record>
APP_REPO  = <git url of the app, or an npm package name>
APP_START = <command that serves the UI, e.g. node dist/cli.js serve --web --port 5757>
APP_URL   = <local url the browser opens, e.g. http://127.0.0.1:5757/>
SECRETS   = <local env file the app needs, e.g. ~/.app/config.env>

1. Pick the geometry first

Everything downstream depends on this, and getting it wrong means re-recording.

Chrome's --force-device-scale-factor=N divides the X display into CSS pixels:

CSS viewport = Xvfb resolution / DSF

Record at 2× the delivery resolution and downscale in post — supersampling is what makes small UI text look sharp in an H.264 clip.

Do not just use 1280×720. A real user's browser window is far taller than 720 CSS px, so a 720-tall viewport clips panels that never clip in real life — and the clipped part is usually the payoff (the final state, the confirm button). Probe the actual content height before committing (§4) and go taller if it overflows.

Keep integer DSF values. Fractional scale factors make Chrome's text rendering noticeably softer.

2. Provision

gcloud compute instances create <VM> --project=<PROJECT> --zone=<ZONE> \
  --machine-type=e2-standard-4 \
  --image-family=ubuntu-2404-lts-amd64 --image-project=ubuntu-os-cloud \
  --boot-disk-size=50GB --boot-disk-type=pd-balanced \
  --labels=purpose=demo-recording

4 vCPU is the floor — x11grab at 2880×1620/30fps plus Chrome plus the app will saturate 2 cores. Copy reference/setup.sh over and run it: it installs Xvfb, ffmpeg, Chrome, xdotool, ImageMagick, Node, and — critically — fonts.

Fonts are the whole ballgame for "does this look right". Most web UIs specify -apple-system, BlinkMacSystemFont, "SF Pro Text" and ui-monospace, "SF Mono", Menlo. None of those exist on Linux, so you get DejaVu fallback and the app looks subtly wrong in a way reviewers notice but can't name. Install fonts-inter (a near-exact SF Pro substitute, and often already in the CSS fallback chain), fonts-jetbrains-mono, fonts-noto-color-emoji (UIs lean on ❤️ 🌙 ★ far more than you expect), and fonts-noto-cjk. Then fc-cache -f.

gcloud compute ssh is flaky under load. It intermittently dies with RemoteDisconnected. Fall back to plain SSH against the external IP with the key gcloud already provisioned:

ssh -i ~/.ssh/google_compute_engine -o StrictHostKeyChecking=no <user>@<EXTERNAL_IP>

3. Deploy the app + secrets

Prefer building from source at the version you want to show — a published package often lags the current version.

Never put secrets in instance metadata or in a command line. Metadata is readable by anyone with project viewer, and argv shows up in ps and shell history. Pipe them over SSH's stdin instead:

grep -E '^(API_KEY|BASE_URL)=' <SECRETS> | \
  ssh ... "mkdir -p ~/.app && cat > ~/.app/config.env && chmod 600 ~/.app/config.env"

Snapshot the pristine state before the app ever runs. First-run flows — onboarding, setup wizards, a birth ritual — happen exactly once, and you will need three or four takes to get one good one:

cp -r ~/.app ~/.app-pristine     # BEFORE first launch
# each retake starts with:  rm -rf ~/.app && cp -r ~/.app-pristine ~/.app

4. Bring the stack up

reference/stack.sh does Xvfb → app → Chrome, idempotently. Chrome flags that matter for a clean frame:

--kiosk                      no tabs, no URL bar, no bookmarks
--hide-scrollbars            scrollbars read as clutter on video
--force-device-scale-factor  see §1
--lang=en-US                 UIs branch on navigator.language; pin it
--remote-debugging-port=9222 so Playwright can attach
--user-data-dir=/tmp/...     fresh profile, no first-run bubbles
--disable-features=Translate,TranslateUI,AutofillServerCommunication,MediaRouter

Also xsetroot -solid '<app-bg-color>' so any gap looks deliberate, and xset -dpms s off s noblank so the screen never blanks mid-take.

Then probe before recording — check the content actually fits:

await page.evaluate(() => ({
  viewport: [innerWidth, innerHeight], dpr: devicePixelRatio,
  overflow: document.querySelector('<container>').scrollHeight,
  clientH:  document.querySelector('<container>').clientHeight,
}))

If scrollHeight > clientHeight on something that shouldn't scroll, go back to §1.

5. Drive it

Attach to the running Chrome rather than letting Playwright launch its own — the browser then survives a script crash, so a failed drive doesn't cost you the whole recording:

const b = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = b.contexts()[0].pages()[0];

Use playwright-core (no bundled browser download). Rules that make takes usable:

• Print a MARK <label> <seconds> timeline. The edit is driven entirely by these timestamps; without them you are scrubbing a 6-minute file by hand.
• Record -draw_mouse 0. A programmatically driven cursor never moves, so a visible pointer just looks frozen.
• Type with { delay: 40-60 }. Instant fill() looks like a bug.
• Hold 2–3s on each payoff state. You can always cut time out in post; you cannot add a frame that was never captured.
• Poll for real completion, not fixed sleeps — watch for text length going stable, a class appearing, an element count changing.
• Scroll cinematically: for (i=0..N) el.scrollTop = total*i/N with a ~50ms gap reads as a deliberate camera move; a single jump reads as a glitch.

6. Record

ffmpeg runs for the whole take; you cut afterwards.

ffmpeg -y -f x11grab -draw_mouse 0 -framerate 30 -video_size <W>x<H> -i :99.0 \
  -c:v libx264 -preset ultrafast -crf 16 -pix_fmt yuv420p /tmp/raw.mp4

ultrafast + crf 16 keeps capture real-time on 4 vCPU; quality is recovered in the encode pass. Stop it with SIGINT (not SIGKILL) so the container finalizes.

Beware orphaned ffmpeg. If the drive script dies, its ffmpeg child keeps recording and holds the output file — every later take then silently writes nowhere. Start each take with pkill -f x11grab.

Launch long takes detached or the SSH session ending kills them:

ssh ... 'setsid bash ~/take.sh > ~/take.log 2>&1 < /dev/null & disown; exit 0'

Do not try to chain sed/mv/launch in one backgrounded compound — the & breaks the chain and you get a half-applied state that looks like it worked. Write the script to a file, scp it, run it.