Browser Video Recording

Browser Video Recording

Dependency Model

Separate the workflow into three layers:

1. Browser control and source frames: Use the Codex in-app browser through the Browser skill/MCP. Do not use Chrome when the user asks for Codex browser or the project says not to. The browser layer supplies real screenshots and real click/scroll/navigation states.

2. Local video renderer: Use the bundled Python script to render screenshots into an MP4 with a natural macOS cursor, subtle click scale, and calm zoom-follow framing. This does not require a screen-recording MCP.

3. Optional native recorder integration: Use a native recording MCP only when callable and explicitly useful for starting/stopping an actual app recording or opening a generated project. If unavailable, blocked, or unable to capture the Codex browser surface, fall back to the screenshot-to-video renderer and explain the fallback.

Self-Contained Execution

This skill is enough for another Codex instance to perform the Python rendering as long as the full skill folder is installed, including scripts/render_browser_demo.py. Codex should run the bundled script instead of recreating the renderer.

Required local tools:

• python3

• Python package Pillow

• ffmpeg and ffprobe

Optional macOS cursor extraction uses swift and /usr/sbin/screencapture. If those are unavailable, provide a transparent PNG through cursor_asset and set cursor_hotspot in the config.

The Browser skill/MCP is still needed for fresh Codex in-app browser screenshots. If it is unavailable, use the best available browser automation screenshot source and state the fallback.

Optional Native Recorder Support

For native app recording, verify the MCP supports:

• Use frameRate: 60.

• Use resolutionRawValue: "4K".

• Use ratioPresetRawValue: "4:3" for region recordings.

• Use an explicit selectedRegionOnScreen when cropping to an embedded browser viewport.

For the local renderer, 4K 4:3 means 3840x2880. If a native recorder exposes a 4K enum, treat it as an app-side resolution preset and pair it with 4:3 region selection when recording through that MCP.

Capture Workflow

Use browser:control-in-app-browser first. After loading its docs, drive the in-app browser with the Node/browser API:

• Set viewport to 1920x1440 for 4:3 4K output, then reset it before finishing.

• Navigate to the requested page and perform actual clicks, backs, searches, and scrolls.

• Save browser-only screenshots after each important state change. Use names like 01-results-top.png, 02-after-card-click.png, 03-back-results.png.

• Record the viewport coordinates of each click/scroll target. The final cursor path should land on those points, pause, click, then move to the next meaningful point.

Avoid desktop coordinate automation unless the user explicitly needs system UI. Codex browser visibility may not expose a capturable macOS surface; screenshots from the browser API are the reliable source.

Motion Rules

Make the cursor feel purposeful:

• Use sparse, mostly straight cursor paths.

• Pause briefly on a target before clicking.

• Do not wander over unrelated UI.

• Let the page transition happen after the click, not before.

• Use only subtle click feedback: scale dip/rebound, not decorative rings unless requested.

• Keep zoom-follow calmer than the cursor. The camera should frame the clicked content, not chase every small mouse move.

Default visual target:

• Real macOS pointer extracted from the compositor, or an existing transparent cursor asset.

• Cursor scale 3.0, matching the large cursor style commonly used in edited demo recordings.

• Click animation strength 15 for a subtle click scale dip.

• Rotation strength up to 8deg, only from horizontal velocity.

Render Script

Use scripts/render_browser_demo.py for deterministic 60 fps 4:3 4K output:

python3 /path/to/browser-video-recording/scripts/render_browser_demo.py \
  --config /tmp/browser-demo-config.json \
  --output /tmp/browser-demo-4x3-4k-60fps.mp4

Generate a starter config:

python3 /path/to/browser-video-recording/scripts/render_browser_demo.py --write-template

The config supplies:

• shots: map of state names to screenshot PNG paths.

• scene_starts: [time, shotName, transition] entries.

• cursor_keys: [time, x, y] viewport-coordinate entries.

• camera_keys: [time, x, y, zoom] entries.

• click_times: click timestamps.

• duration, fps, output_size, source_size, cursor_scale.

Preferred defaults:

{
  "fps": 60,
  "output_size": [3840, 2880],
  "source_size": [1920, 1440]
}

If cursor_asset is omitted, the script briefly shows a solid-color overlay and uses screencapture to extract the real current macOS cursor into a transparent PNG. This is local rendering support, not an MCP dependency.

Verification

Always verify the delivered video:

ffprobe -v error \
  -show_entries stream=codec_name,width,height,r_frame_rate \
  -show_entries format=duration,size \
  -of json /path/to/output.mp4

Extract at least one mid-video thumbnail and inspect it:

ffmpeg -y -ss 8 -i /path/to/output.mp4 -frames:v 1 -update 1 /tmp/browser-demo-thumb.png

Confirm:

• Resolution is the requested output, usually 3840x2880 for 4:3 4K.

• Frame rate is 60/1 or equivalent.

• Duration matches the request.

• Cursor is visible, natural, and on-target.

• The video is cropped to browser content, not the desktop.

• The browser viewport override has been reset.