shot-scraper¶

shot-scraper is a tool to automate the process of updating screenshots.

Installation¶

$ uv add --group docs shot-scraper
$ uv run shot-scraper install

Note

The second line installs the required browser.

Use¶

shot-scraper can be used in several ways

…for single screenshots on the command line:

$ uv run shot-scraper https://jupyter-tutorial.readthedocs.io/de/latest/clean-prep/index.html -o ~/Downloads/clean-prep.png

…or with additional options, for example for JavaScript and CSS selectors:

$ uv run shot-scraper https://jupyter-tutorial.readthedocs.io/de/latest/clean-prep/index.html -s '#overview' -o ~/Downloads/clean-prep.png

…for a set of screenshots configured in a YAML file:

- url: https://jupyter-tutorial.readthedocs.io/de/latest/clean-prep/index.html
  output: ~/Downloads/clean-prep.png
- url: https://www.example.org/
  width: 736
  quality: 40
  output: example.jpg

Afterwards shot-scraper multi can be used, for example:

$ shot-scraper multi shots.yaml
Screenshot of 'https://jupyter-tutorial.readthedocs.io/de/latest/clean-prep/index.html' written to '~(Downloads/clean-prep.png'
Screenshot of 'https://www.example.org/' written to 'example.jpg'

See also

Taking multiple screenshots

…for videos:

The shot-scraper video command captures a WebM video based on a YAML storyboard. Storyboards describe the video as a sequence of scenes. Each scene can open a page, wait for content, perform actions and pause between steps, for example:

storyboard.yml¶

output: demo.webm
url: https://python-basics-tutorial.readthedocs.io/en/latest/

viewport:
  width: 1280
  height: 720

cursor: true
wait_for: "text=Python für Data Science"

scenes:
- name: Home
  do:
  - pause: 1

- name: Introduction
  do:
  - click: ".sidebar-tree a[href='intro.html']"
  - wait_for: 'h1:has-text("Introduction")'
  - screenshot: intro.png
  - pause: 1

- name: Search
  do:
  - click: "input.sidebar-search"
  - type:
      into: "input.sidebar-search"
      text: "shot-scraper"
      delay_ms: 25
  - press:
      selector: "input.sidebar-search"
      key: Enter
  - wait_for: "text=Search Results"
  - pause: 2

Then run the following command:

$ uv run shot-scraper video storyboard.yml

This opens url, records the scenes and saves the video as demo.webm.

As long as FFmpeg is installed, you can use the --mp4 option to convert the recorded WebM video to MP4 as well.

GitHub Actions¶

shot-scraper can be easily integrated into GitHub Actions. The shot-scraper-demo repository also contains an exemplary shots.yml. Once a day, two screenshots are created and transferred back to the repository. Note, however, that saving image files that change frequently can make the revision history very unreadable. Therefore, you should use shot-scraper with caution together with GitHub Actions.