Browser Screenshots

Browser Screenshot & Video Capture

Capture browser screenshots and record videos when the user requests them. This skill uses Playwright-based scripts to automate browser interactions and save screenshots or videos directly to disk.

When to Use

Use this skill when the user asks you to:

• Capture a screenshot of a specific URL
• Document a web page or web application state
• Take screenshots of a locally running development server
• Capture a sequence of browser interactions
• Record a video or GIF of a page with animations
• Create looping videos to showcase animated content

How to Capture

Use the Playwright capture script located at .github/skills/browser-screenshots/scripts/capture.cjs.

Basic Screenshot

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://example.com \
  --output docs/_static/screenshots/example-homepage.png

Common Options

Examples

Capture with dark mode:

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://code.visualstudio.com \
  --dark \
  --output docs/_static/screenshots/vscode-homepage.png

Capture with a browser frame:

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://protomaps.com \
  --chrome \
  --waitForSelector "main" \
  --output docs/_static/screenshots/what-you-will-make/protomaps-home-framed.png

Highlight a specific element:

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://github.com/new \
  --highlight ".repo-name-input" \
  --output docs/_static/screenshots/github-repo-name.png

Capture a specific element only:

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://example.com \
  --element ".hero-section" \
  --output docs/_static/screenshots/hero-only.png

Execute JavaScript before capture (e.g., click a button):

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://example.com \
  --execute "document.querySelector('button').click()" \
  --wait 1000 \
  --output docs/_static/screenshots/after-click.png

Full page screenshot:

node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://example.com \
  --fullpage \
  --output docs/_static/screenshots/full-page.png

Saving Screenshots

For this repo's Sphinx docs, save screenshots under docs/_static/screenshots/ with descriptive kebab-case filenames.

Naming convention: Use kebab-case:

• ✅ github-new-repo.png
• ✅ homepage-hero-section.png
• ❌ GitHubNewRepo.png

Directory structure (recommended):

docs/_static/
  screenshots/
    create-map/
      bare-basemap.png
      storm-tracks-lines.png
    build-tiles/
      download-zip.png

Embedding in Sphinx/MyST Docs

This repo's tutorial docs are written in MyST Markdown and built with Sphinx (see docs/conf.py). For screenshots, embed images using MyST/Sphinx conventions.

Preferred: MyST figure (caption + alt)

Use this in a docs/*.md page:

:::{figure} \_static/screenshots/create-map/bare-basemap.png
:alt: Bare basemap running locally
:width: 100%

Bare basemap running locally.
:::

Notes:

• Paths are relative to the docs/ source root.
• Put the file itself at docs/_static/screenshots/....

Simple inline image (no caption)

![Bare basemap running locally](_static/screenshots/create-map/bare-basemap.png)

Recording Videos

Use the video recording script for pages with animations, GIFs, or dynamic content that needs to be captured over time.

Basic Video Recording

node .github/skills/browser-screenshots/scripts/record-video.cjs \
  --url https://example.com \
  --output docs/_static/screenshots/animation.gif \
  --duration 5

Video Recording Options

Video Examples

Record a 5-second GIF:

node .github/skills/browser-screenshots/scripts/record-video.cjs \
  --url https://example.com \
  --output docs/_static/screenshots/demo.gif \
  --duration 5

Record MP4 video:

node .github/skills/browser-screenshots/scripts/record-video.cjs \
  --url https://example.com \
  --output docs/_static/videos/demo.mp4 \
  --duration 10

Higher framerate GIF for smoother animation:

node .github/skills/browser-screenshots/scripts/record-video.cjs \
  --url https://example.com \
  --output docs/_static/screenshots/smooth.gif \
  --fps 15 \
  --duration 3

Embedding Videos in Tutorials

For GIFs, embed them like screenshots (MyST figure or Markdown image).

For MP4/WebM, use a raw HTML block in a docs/*.md page:

```{raw} html
<video autoplay loop muted playsinline width="100%">
  <source src="_static/videos/demo.mp4" type="video/mp4" />
</video>
```

## Authenticated Sessions

Some pages require login to display certain elements (e.g., the "Use this template" button on GitHub). You can save authenticated sessions and reuse them for captures.

### Saving a Session

Run the session saver script, which opens a browser where you can log in:

```bash
node .github/skills/browser-screenshots/scripts/save-session.cjs \
  --url https://github.com \
  --session github

This opens a browser window. Log in to the site, then press Enter in the terminal to save your session. Sessions are stored in ~/.playwright-sessions/.

Using a Saved Session

Add the --session flag to capture or record commands:

# Screenshot with GitHub session
node .github/skills/browser-screenshots/scripts/capture.cjs \
  --url https://github.com/palewire/cuny-jour-static-site-template \
  --session github \
  --output docs/_static/screenshots/github-repo.png

# Video with GitHub session
node .github/skills/browser-screenshots/scripts/record-video.cjs \
  --url https://github.com/settings \
  --session github \
  --output docs/_static/screenshots/github-settings.gif

Listing Saved Sessions

node .github/skills/browser-screenshots/scripts/save-session.cjs --list

Session Options

Prerequisites

Playwright must be installed. If not already installed:

npm init -y
npm install playwright
npx playwright install chromium

For GIF output, ffmpeg must also be installed:

brew install ffmpeg

Limitations

• Cannot capture: VS Code windows, terminal output, system dialogs (these require manual screenshots)
• Requires network access: URLs must be reachable from the machine running the script
• GIF output requires ffmpeg: Install via brew install ffmpeg on macOS
• Sessions expire: Saved sessions will expire based on the site's cookie policies; re-run save-session when needed

Converted and distributed by TomeVault — claim your Tome and manage your conversions.