Experimental video support

Author: simonw

README.md

@@ -38,6 +38,40 @@ This will create a screenshot in a file called `datasette-io.png`.
 
 Many more options are available, see [Taking a screenshot](https://shot-scraper.datasette.io/en/stable/screenshots.html) for details.
 
+## Recording videos
+
+You can record videos of web pages with interactive elements:
+
+    shot-scraper video https://example.com/ -o video.webm --duration 10
+
+Pass actions directly via the command line:
+
+    shot-scraper video https://example.com/ -o video.webm \
+      --actions '[{"action": "click", "selector": "#button"}]'
+
+Or reference a file (JSON or YAML):
+
+    shot-scraper video https://example.com/ -o video.webm --actions actions.json
+
+For more complex workflows, create a YAML file with action sequences:
+
+```yaml
+- output: demo.webm
+  video: true
+  url: https://example.com/
+  actions:
+    - action: click
+      selector: "#menu"
+    - action: scroll
+      y: 500
+    - action: javascript
+      code: document.querySelector('h1').style.color = 'red';
+```
+
+Then run: `shot-scraper multi config.yml`
+
+See [Recording videos](https://shot-scraper.datasette.io/en/stable/video.html) for full documentation.
+
 ## Examples
 
 - The [shot-scraper-demo](https://github.com/simonw/shot-scraper-demo) repository uses this tool to capture recently spotted owls in El Granada, CA according to [this page](https://www.owlsnearme.com/?place=127871), and to  generate an annotated screenshot illustrating a Datasette feature as described [in my blog](https://simonwillison.net/2022/Mar/10/shot-scraper/#a-complex-example).

docs/index.md

@@ -23,6 +23,7 @@ installation
 screenshots
 authentication
 multi
+video
 javascript
 pdf
 html

docs/multi.md

@@ -167,6 +167,26 @@ With that server configured, you can now take screenshots of `http://localhost:8
 ```
 The server process will be automatically terminated when the `shot-scraper multi` command completes, unless you pass the `--leave-server` option to `shot-scraper multi` in which case it will be left running - you can terminate it using `kill PID` with the PID displayed in the console output.
 
+## Recording videos
+
+You can record videos instead of screenshots by adding `video: true` to a YAML block. Videos support an `actions:` list for defining interactions to perform during recording:
+
+```yaml
+- output: demo.webm
+  video: true
+  url: https://example.com/
+  duration: 5
+  actions:
+    - action: click
+      selector: "#menu"
+    - action: wait
+      ms: 1000
+    - action: scroll
+      y: 500
+```
+
+See {ref}`video` for full documentation on video recording and available actions.
+
 ## Running custom code between steps
 
 If you are taking screenshots of a single application, you may find it useful to run additional steps between shots that modify that application in some way.