autokast 0.0.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +29 -0
- package/README.md +165 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +300 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/inspect.d.ts +26 -0
- package/dist/inspect.js +193 -0
- package/dist/record/animations.d.ts +7 -0
- package/dist/record/animations.js +34 -0
- package/dist/record/capture.d.ts +85 -0
- package/dist/record/capture.js +202 -0
- package/dist/record/cast.d.ts +142 -0
- package/dist/record/cast.js +680 -0
- package/dist/record/cursor-style.d.ts +33 -0
- package/dist/record/cursor-style.js +252 -0
- package/dist/record/defaults.d.ts +96 -0
- package/dist/record/defaults.js +125 -0
- package/dist/record/editor.d.ts +11 -0
- package/dist/record/editor.js +48 -0
- package/dist/record/frame-pump.d.ts +91 -0
- package/dist/record/frame-pump.js +306 -0
- package/dist/record/index.d.ts +11 -0
- package/dist/record/index.js +287 -0
- package/dist/record/motion.d.ts +48 -0
- package/dist/record/motion.js +112 -0
- package/dist/record/pace.d.ts +69 -0
- package/dist/record/pace.js +133 -0
- package/dist/record/random.d.ts +12 -0
- package/dist/record/random.js +24 -0
- package/dist/record/scroll.d.ts +71 -0
- package/dist/record/scroll.js +249 -0
- package/dist/record/timeline.d.ts +34 -0
- package/dist/record/timeline.js +44 -0
- package/dist/render/background.d.ts +12 -0
- package/dist/render/background.js +209 -0
- package/dist/render/browser.d.ts +46 -0
- package/dist/render/browser.js +223 -0
- package/dist/render/camera.d.ts +119 -0
- package/dist/render/camera.js +372 -0
- package/dist/render/captions.d.ts +114 -0
- package/dist/render/captions.js +254 -0
- package/dist/render/color.d.ts +23 -0
- package/dist/render/color.js +78 -0
- package/dist/render/compositor.d.ts +185 -0
- package/dist/render/compositor.js +656 -0
- package/dist/render/cursor.d.ts +85 -0
- package/dist/render/cursor.js +314 -0
- package/dist/render/cursors/shapes.d.ts +34 -0
- package/dist/render/cursors/shapes.js +268 -0
- package/dist/render/defaults.d.ts +91 -0
- package/dist/render/defaults.js +139 -0
- package/dist/render/easing.d.ts +13 -0
- package/dist/render/easing.js +40 -0
- package/dist/render/effects.d.ts +39 -0
- package/dist/render/effects.js +91 -0
- package/dist/render/encoder.d.ts +52 -0
- package/dist/render/encoder.js +226 -0
- package/dist/render/index.d.ts +19 -0
- package/dist/render/index.js +138 -0
- package/dist/render/keycaps.d.ts +67 -0
- package/dist/render/keycaps.js +270 -0
- package/dist/render/scene.d.ts +59 -0
- package/dist/render/scene.js +230 -0
- package/dist/render/source.d.ts +21 -0
- package/dist/render/source.js +57 -0
- package/dist/render/spring.d.ts +11 -0
- package/dist/render/spring.js +47 -0
- package/dist/render/stage.d.ts +59 -0
- package/dist/render/stage.js +91 -0
- package/dist/render/timeline.d.ts +70 -0
- package/dist/render/timeline.js +157 -0
- package/dist/session.d.ts +14 -0
- package/dist/session.js +33 -0
- package/dist/types.d.ts +708 -0
- package/dist/types.js +1 -0
- package/package.json +61 -3
- package/skills/autokast/SKILL.md +300 -0
- package/skills/autokast/reference/jupyterlab.md +100 -0
package/package.json
CHANGED
|
@@ -1,7 +1,65 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "autokast",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Automated, polished screencasts of web apps. Built for agents.",
|
|
5
|
+
"license": "BSD-3-Clause",
|
|
6
|
+
"author": "Jeremy Tuloup",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/jtpio/autokast.git"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/jtpio/autokast#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/jtpio/autokast/issues"
|
|
14
|
+
},
|
|
15
|
+
"keywords": [
|
|
16
|
+
"screencast",
|
|
17
|
+
"screen-recording",
|
|
18
|
+
"playwright",
|
|
19
|
+
"video",
|
|
20
|
+
"demo",
|
|
21
|
+
"agent"
|
|
22
|
+
],
|
|
23
|
+
"type": "module",
|
|
24
|
+
"bin": {
|
|
25
|
+
"autokast": "dist/cli.js"
|
|
26
|
+
},
|
|
27
|
+
"main": "dist/index.js",
|
|
28
|
+
"types": "dist/index.d.ts",
|
|
29
|
+
"exports": {
|
|
30
|
+
".": {
|
|
31
|
+
"types": "./dist/index.d.ts",
|
|
32
|
+
"default": "./dist/index.js"
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
"files": [
|
|
36
|
+
"dist",
|
|
37
|
+
"skills",
|
|
38
|
+
"README.md",
|
|
39
|
+
"LICENSE"
|
|
40
|
+
],
|
|
41
|
+
"scripts": {
|
|
42
|
+
"build": "tsc -p tsconfig.build.json",
|
|
43
|
+
"prepare": "npm run build",
|
|
44
|
+
"typecheck": "tsc --noEmit",
|
|
45
|
+
"test": "node --test \"test/**/*.test.ts\"",
|
|
46
|
+
"format": "prettier --write .",
|
|
47
|
+
"format:check": "prettier --check .",
|
|
48
|
+
"prepublishOnly": "npm run build"
|
|
49
|
+
},
|
|
50
|
+
"engines": {
|
|
51
|
+
"node": ">=22.18"
|
|
52
|
+
},
|
|
53
|
+
"peerDependencies": {
|
|
54
|
+
"playwright": ">=1.50.0"
|
|
55
|
+
},
|
|
56
|
+
"dependencies": {
|
|
57
|
+
"@napi-rs/canvas": "^1.1.1"
|
|
58
|
+
},
|
|
59
|
+
"devDependencies": {
|
|
60
|
+
"@types/node": "^22.0.0",
|
|
61
|
+
"playwright": "1.63.0",
|
|
62
|
+
"prettier": "^3.10.0",
|
|
63
|
+
"typescript": "^5.9.0"
|
|
6
64
|
}
|
|
7
65
|
}
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: autokast
|
|
3
|
+
description: Record polished, Screen Studio-style screencasts of web apps with the autokast library (smooth cursor, click effects, eased zooms, framed window). Use when asked to record a screencast, demo video, GIF or feature showcase of a web app or any site that opens in a browser.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# autokast
|
|
7
|
+
|
|
8
|
+
`autokast` turns a script into a finished screencast. You write what happens on the page and
|
|
9
|
+
where the camera looks. The library records the page with Playwright, then renders the cursor,
|
|
10
|
+
the click effects, the zooms and the framed window.
|
|
11
|
+
|
|
12
|
+
You cannot watch a video, so the workflow depends on two commands that show you the result:
|
|
13
|
+
`autokast inspect` (timeline as text plus a contact sheet image) and `autokast frame` (one
|
|
14
|
+
still). Look at their output with your image reader after every recording.
|
|
15
|
+
|
|
16
|
+
## Setup
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install --save-dev autokast playwright
|
|
20
|
+
npx playwright install chromium # skip when Chromium is already installed
|
|
21
|
+
ffmpeg -version # must be on the PATH
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Each Playwright version needs its own Chromium build. When you cannot run
|
|
25
|
+
`playwright install`, use the Playwright version that installed the browser, or pass
|
|
26
|
+
`browser: { executablePath }` in the script.
|
|
27
|
+
|
|
28
|
+
Run the commands as `npx autokast <command>`. Scripts import from `autokast`. In a clone
|
|
29
|
+
of the autokast repository, `node src/cli.ts <command>` runs from source.
|
|
30
|
+
|
|
31
|
+
## Workflow
|
|
32
|
+
|
|
33
|
+
1. **Explore the app first.** Open it with plain Playwright, take screenshots at the recording
|
|
34
|
+
viewport (1280x720 by default), and find stable locators for everything you will touch.
|
|
35
|
+
Run the whole flow once without autokast to learn what needs a wait.
|
|
36
|
+
2. **Write a storyboard.** Four to eight beats, one idea per beat, 30 to 90 seconds in total.
|
|
37
|
+
For each beat: the action, what the viewer must read, and whether the camera zooms.
|
|
38
|
+
3. **Write the script** (template below). Put everything that must not be on video in `setup`.
|
|
39
|
+
4. **Record**: `autokast record script.ts --no-render`. A failure names the failing call and
|
|
40
|
+
saves `error.png` in the session directory; look at it.
|
|
41
|
+
5. **Inspect**: `autokast inspect .autokast/<name> -o sheet.png`, then read `sheet.png`. Check
|
|
42
|
+
the list in "Review" below. For a closer look at one moment:
|
|
43
|
+
`autokast inspect .autokast/<name> --from 10 --to 14 --every 0.25 -o part.png` or
|
|
44
|
+
`autokast frame .autokast/<name> --at 12.4 -o still.png`. Keep a sheet to 16 tiles or
|
|
45
|
+
fewer so the tiles stay readable; `--tile-width 640 --cols 3` gives larger tiles.
|
|
46
|
+
6. **Adjust and repeat** from step 4 until the sheet is right. Look options (backdrop, cursor
|
|
47
|
+
size, output size) need no new recording: pass them to `render` or `inspect`.
|
|
48
|
+
7. **Final recording and render**: record once more with
|
|
49
|
+
`--set capture.mode=frame-perfect` (see "Capture modes"), then
|
|
50
|
+
`autokast render .autokast/<name> -o demo.mp4`. Run `autokast inspect demo.mp4 -o final.png`
|
|
51
|
+
and read it as the last check.
|
|
52
|
+
|
|
53
|
+
## Script template
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import { defineScreencast } from 'autokast';
|
|
57
|
+
|
|
58
|
+
export default defineScreencast({
|
|
59
|
+
name: 'feature-demo',
|
|
60
|
+
url: 'http://localhost:3000',
|
|
61
|
+
viewport: { width: 1280, height: 720 },
|
|
62
|
+
render: { background: 'dusk' },
|
|
63
|
+
|
|
64
|
+
// Not recorded: wait for the app, log in, prepare data, reset state.
|
|
65
|
+
async setup({ page }) {
|
|
66
|
+
await page.getByRole('heading', { name: 'Dashboard' }).waitFor();
|
|
67
|
+
},
|
|
68
|
+
|
|
69
|
+
// Recorded. Use cast for every action the viewer must see.
|
|
70
|
+
async run(cast) {
|
|
71
|
+
const { page } = cast;
|
|
72
|
+
|
|
73
|
+
await cast.click(page.getByRole('button', { name: 'New task' }));
|
|
74
|
+
await cast.zoomTo(page.getByRole('dialog'), { padding: 40 });
|
|
75
|
+
await cast.type('Write the release notes', { into: page.getByLabel('Title') });
|
|
76
|
+
await cast.click(page.getByRole('button', { name: 'Create task' }));
|
|
77
|
+
await cast.zoomOut();
|
|
78
|
+
},
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Scripts are TypeScript or `.mjs`, and Node runs them directly. In a project whose
|
|
83
|
+
`package.json` has no `"type": "module"`, name the script `.mts`: with `.ts`, Node prints a
|
|
84
|
+
module warning (it does no harm).
|
|
85
|
+
|
|
86
|
+
## Cast calls
|
|
87
|
+
|
|
88
|
+
A target is a Playwright locator, a selector string, a point `{ x, y }` or a rectangle
|
|
89
|
+
`{ x, y, width, height }` (viewport pixels). Locators are strict: a locator that matches two
|
|
90
|
+
elements fails, so narrow it.
|
|
91
|
+
|
|
92
|
+
| Call | Use |
|
|
93
|
+
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `cast.click(target)` / `dblclick` / `rightClick` | Cursor moves to the target, then presses. Options: `position: { x, y }` as fractions of the target, `modifiers`, `force`. |
|
|
95
|
+
| `cast.moveTo(target)` / `cast.hover(target, { hold: 800 })` | Cursor move without a press. `position` may go outside 0..1, for example `{ x: 0.5, y: -0.2 }` to arrive from above a target without crossing its neighbours. |
|
|
96
|
+
| `cast.select(target, values)` | Clicks a native `<select>` and chooses options by value or label. The list does not open: the browser draws it outside the page, where the video cannot show it. |
|
|
97
|
+
| `cast.drag(from, to)` | Press on `from`, move, release on `to`. Options: `position` (source), `toPosition` (destination), `dragDuration`. |
|
|
98
|
+
| `cast.scrollTo(target)` / `cast.scroll({ y: 400 }, { at: target })` | Smooth scroll. Targets off screen scroll into view by themselves before an action. |
|
|
99
|
+
| `cast.type(text, { into: target })` | Human typing. Multi-line code keeps its indentation, also in editors that indent by themselves. |
|
|
100
|
+
| `cast.press('Shift+Enter')` | Key combination (Playwright key names). |
|
|
101
|
+
| `cast.goto(url)` | Opens a URL and removes the load from the video. With the browser frame, the address bar first shows the URL as typed text. |
|
|
102
|
+
| `cast.showUrl({ duration })` | Browser frame only: makes the address bar larger for a moment (default 2 s), so that the viewer can read the URL. |
|
|
103
|
+
| `cast.zoomTo(target, { level, scale, padding, follow })` | Frames a target. `level` is a named zoom level (`wide`, `medium`, `close`), `scale` a number; with neither, the target plus `padding` fills the view. `follow` is `off`, `edge` or `cursor`. The next action overlaps the move; `wait: true` waits for its end. |
|
|
104
|
+
| `cast.zoom(level)` | Zooms on the cursor, to a level name or a number, and the camera then travels with the cursor. Use it to guide the eye across the interface without a fixed target. |
|
|
105
|
+
| `cast.zoomOut()` | Back to the full view. |
|
|
106
|
+
| `cast.wait(ms)` | Hold the shot. |
|
|
107
|
+
| `cast.cut(fn)` | Run `fn` and remove that time from the video. |
|
|
108
|
+
| `cast.speed(rate, fn)` | Run `fn` and play that time `rate` times faster. |
|
|
109
|
+
| `cast.spotlight(target, { duration })` | Dim everything except the target. |
|
|
110
|
+
| `cast.caption(text, { duration })` | Optional caption on the backdrop below the window. `**` around words gives them the emphasis. Use only when asked for text in the video. |
|
|
111
|
+
| `cast.marker(label)` | Name a point in time; shown by `inspect`. |
|
|
112
|
+
|
|
113
|
+
`cast.page` is the Playwright page. Use it to wait and to read state
|
|
114
|
+
(`await cast.cut(() => page.getByText('Done').waitFor())`). Never click, type or scroll through
|
|
115
|
+
`cast.page` inside `run`: the page would change but the cursor in the video would not move.
|
|
116
|
+
|
|
117
|
+
## Direction
|
|
118
|
+
|
|
119
|
+
Good screencasts are calm but never idle. The viewer follows one thing at a time, and every
|
|
120
|
+
moment has motion or something new to read.
|
|
121
|
+
|
|
122
|
+
**Structure**
|
|
123
|
+
|
|
124
|
+
- Open on the full view and end on the full view (`zoomOut`). The recording already holds
|
|
125
|
+
0.4 s before the first call and 0.9 s after the last one; do not add more at the start.
|
|
126
|
+
- The cursor starts at the center of the viewport. If that puts it on top of something
|
|
127
|
+
distracting, set `cursor: { start: { x, y } }` to an empty spot.
|
|
128
|
+
- One idea per beat. Show the result of each action before the next action starts.
|
|
129
|
+
- Hold on a result only as long as a reader needs: about 1.2 s for one fact, up to 2 s for a
|
|
130
|
+
table or a plot.
|
|
131
|
+
|
|
132
|
+
**Camera**
|
|
133
|
+
|
|
134
|
+
- Zoom when the viewer must read small text, watch typing, or see a small control. Do not zoom
|
|
135
|
+
for large layout changes or navigation.
|
|
136
|
+
- Scale 1.3 to 1.6 for a panel, 1.6 to 2.2 for a control or a few lines. Above 2.5 is rare.
|
|
137
|
+
`scale` is how much larger the page looks than in the full view. Without `scale`, the target
|
|
138
|
+
plus `padding` fills the video exactly; use that to frame one panel or one output.
|
|
139
|
+
- Call `zoomTo` just before the action. The call returns after about a third of the camera
|
|
140
|
+
move, so the cursor or the typing starts while the camera still travels. Pass
|
|
141
|
+
`{ wait: true }` only when the viewer must see the shot settle before something happens.
|
|
142
|
+
- Go from one zoomed shot to the next with one `zoomTo`: the camera pans and rescales in one
|
|
143
|
+
move, and a target below the fold scrolls into view by itself. Do not zoom out between two
|
|
144
|
+
shots unless the next action needs the full layout.
|
|
145
|
+
- Choose how the camera reacts to the cursor for each shot, with `follow`:
|
|
146
|
+
`edge` (default for `zoomTo`) keeps your framing and pans only when the cursor comes near
|
|
147
|
+
the edge; `cursor` (default for `cast.zoom`) travels with the cursor; `off` never moves.
|
|
148
|
+
Use `off` for a shot that must stay still, and `cursor` when the action crosses the page.
|
|
149
|
+
- Use the named levels so that shots of the same kind have the same size: `wide` (1.3) for a
|
|
150
|
+
panel, `medium` (1.6) for a group of controls, `close` (2.2) for one control or a few
|
|
151
|
+
lines. A render can change these values with `zoom.levels`.
|
|
152
|
+
|
|
153
|
+
**Time**
|
|
154
|
+
|
|
155
|
+
- No dead time. Do not put `cast.wait` between actions: the built-in pauses after a click or
|
|
156
|
+
a key are enough. Use `cast.wait` only to hold on a result. A video that feels slow has too
|
|
157
|
+
many waits.
|
|
158
|
+
- Hide every wait for the app: `await cast.cut(() => locator.waitFor())` for page loads,
|
|
159
|
+
kernels, network. Pass `{ afterClick: 0 }` to the click before a `cut`, so that no loading
|
|
160
|
+
state shows.
|
|
161
|
+
- Typing runs at about 16 characters per second. For code, use `typing: { delay: 30 }` (about
|
|
162
|
+
25 characters per second) and keep cells short; 40 seconds of typing in a one-minute video
|
|
163
|
+
is too much.
|
|
164
|
+
- To show another URL, call `cast.goto(url)`: it opens the page and removes the load from
|
|
165
|
+
the video. Then cut the wait for the content: `await cast.cut(() => locator.waitFor())`.
|
|
166
|
+
For a click that reloads the page, start `const loaded = page.waitForEvent('load')` before
|
|
167
|
+
the click and `await loaded` inside the cut. A camera move continues across a cut, so go to
|
|
168
|
+
the full view first with `cast.zoomOut({ wait: true })`.
|
|
169
|
+
- When the URL is part of the story, set `render: { frame: { chrome: 'browser' } }`. The
|
|
170
|
+
address bar follows the page, and `cast.goto` shows the URL as typed text, in a larger
|
|
171
|
+
field, before the page opens. When the page changes its own URL (a redirect, a new query),
|
|
172
|
+
call `cast.showUrl()` to make the address bar larger for a moment. A zoomed shot hides the
|
|
173
|
+
toolbar, so stay in the full view while the viewer must read the URL.
|
|
174
|
+
|
|
175
|
+
**Captions**
|
|
176
|
+
|
|
177
|
+
- Use captions for a tour of several features: one caption for each feature. Put `**` around
|
|
178
|
+
the words that name the feature: `cast.caption('**Site Drive** shows the site files')`.
|
|
179
|
+
These words keep the full tone and the other words are dimmed.
|
|
180
|
+
- A new caption replaces the one on screen, so give each caption a `duration` longer than its
|
|
181
|
+
part, and let the last one stay until the end.
|
|
182
|
+
- A caption shows one line: write one short sentence of about 60 characters. Do not number
|
|
183
|
+
the captions ("1.", "Step 2"). For more text, use several captions. Text that is too
|
|
184
|
+
long for one line shows as several lines, one at a time, and the lines share the
|
|
185
|
+
`duration`.
|
|
186
|
+
- A viewer needs about 3 s to read a caption and see the action. Make each part at least
|
|
187
|
+
that long; the limit of one fifth for holds does not apply to a captioned tour.
|
|
188
|
+
- While a caption shows, the view above the caption is wider than the video: about 2:1 for
|
|
189
|
+
a 16:9 video. A `zoomTo` without `scale` or `level` keeps the whole target in that view,
|
|
190
|
+
so a 16:9 target shows more of the page at its sides. Give the target the shape of the
|
|
191
|
+
view, for example `{ x: 0, y: 28, width: 960, height: 472 }` with `padding: 0`, or use a
|
|
192
|
+
`level`.
|
|
193
|
+
|
|
194
|
+
**State**
|
|
195
|
+
|
|
196
|
+
- A recording must start from the same state every time. Reset the app in `setup` (URL
|
|
197
|
+
parameters, API calls, deleting files from an earlier run).
|
|
198
|
+
- Choose the theme, window size and data so the feature is the most visible thing on screen.
|
|
199
|
+
|
|
200
|
+
## Review
|
|
201
|
+
|
|
202
|
+
Read the contact sheet and check:
|
|
203
|
+
|
|
204
|
+
- The first and last tiles show the full view, with no loading state and no leftover dialog.
|
|
205
|
+
- In each zoomed tile, the target is inside the view and its text is large enough to read.
|
|
206
|
+
- The cursor is on the control that the timeline says was clicked.
|
|
207
|
+
- No tile shows a spinner, an empty panel or a half-loaded page (add a `cut` around the wait).
|
|
208
|
+
- Add up the `wait` and `hold` times in the timeline. More than about a fifth of the video is
|
|
209
|
+
too slow: trim them. A result that the viewer cannot read in time needs a longer hold.
|
|
210
|
+
- Total length matches the storyboard.
|
|
211
|
+
|
|
212
|
+
## Look and quality
|
|
213
|
+
|
|
214
|
+
Pass these to `record`, `render`, `frame` or `inspect`. None of them needs a new recording.
|
|
215
|
+
|
|
216
|
+
```sh
|
|
217
|
+
autokast render .autokast/demo -o demo.mp4 --background harbor
|
|
218
|
+
autokast render .autokast/demo -o demo-4k.mp4 --size 3840x2160 --set encode.quality=high
|
|
219
|
+
autokast render .autokast/demo -o demo.gif --size 1280x720 --fps 20
|
|
220
|
+
autokast render .autokast/demo -o tall.mp4 --size 1080x1920
|
|
221
|
+
autokast render .autokast/demo --preview -o quick.mp4
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
| Option | Values |
|
|
225
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
226
|
+
| `size`, `fps` | Any size; 24 to 120 fps. Default 1920x1080 at 60. |
|
|
227
|
+
| `encode.quality` | `draft`, `standard` (default), `high`, `max`. Also `encode.crf`, `encode.preset`. |
|
|
228
|
+
| `background` | `paper`, `fog`, `sage`, `dune`, `clay`, `dusk` (default), `harbor`, `graphite`, `ink`, `ember`, a CSS color, or `{ type: 'gradient' \| 'image', ... }`. |
|
|
229
|
+
| `frame.padding`, `frame.radius`, `frame.shadow` | Space around the window, corner radius, shadow. |
|
|
230
|
+
| `frame.chrome` | `none`, `window` (title bar; set `frame.title`) or `browser` (toolbar with an address bar that follows the page URL). |
|
|
231
|
+
| `frame.chromeTheme` | `light` (default) or `dark`, for the title bar and the browser toolbar. |
|
|
232
|
+
| `frame.address`, `frame.origin` | Browser frame: a fixed text for the address bar (`false` for none), and a text that replaces the origin of the page URL. |
|
|
233
|
+
| `cursor.size`, `cursor.smoothing`, `cursor.hideAfter` | Cursor size (default 1.9), path smoothing, hide when idle (ms). |
|
|
234
|
+
| `cursor.click.type` | `ripple`, `ring`, `none`. |
|
|
235
|
+
| `zoom.mode` | `camera` (the window grows past the edges) or `crop` (zoom inside a fixed window). |
|
|
236
|
+
| `zoom.easing`, `zoom.duration`, `zoom.maxScale` | Camera feel. |
|
|
237
|
+
| `zoom.follow`, `zoom.followSpeed` | Follow mode for shots that do not set one (`off`, `edge`, `cursor`), and how fast the camera catches up (default 1). |
|
|
238
|
+
| `zoom.levels` | Scale of each named level, for example `--set 'zoom.levels={"close":2.6}'`. |
|
|
239
|
+
| `zoom.auto` | `true` adds zooms on clicks and typing when the script has none. |
|
|
240
|
+
| `zoom.edges` | `fill` (default: a zoomed shot is all page) or `keep` (the window edge and backdrop stay in view). |
|
|
241
|
+
| `cursor.tilt` | How much the cursor leans into its travel (default 1; 0 turns it off). |
|
|
242
|
+
| `cursor.motionBlur`, `zoom.motionBlur` | 0 to 1. The cursor has motion blur by default; camera moves have none unless you set it. |
|
|
243
|
+
| `keystrokes.show` | `none` (default), `shortcuts` (key combinations from `cast.press` as keycaps) or `all`. |
|
|
244
|
+
| `keystrokes.labels` | `mac` (⌘ Cmd, ⌥ Opt) or `pc` (Ctrl, Alt). Default: `mac` when the render runs on macOS. |
|
|
245
|
+
| `captions.position` | `bottom` (default) or `top`, for `cast.caption`. |
|
|
246
|
+
|
|
247
|
+
Backdrops, light to dark: `paper` (warm white), `fog` (cool gray), `sage` (muted green), `dune`
|
|
248
|
+
(sand), `clay` (terracotta), `dusk` (slate blue with a warm corner), `harbor` (deep teal),
|
|
249
|
+
`graphite` (dark gray), `ink` (blue-black), `ember` (dark brown). Pick one that does not fight
|
|
250
|
+
the app's own colors, and check it with `autokast frame <session> --at 1 --background <name>`.
|
|
251
|
+
|
|
252
|
+
The capture scale is `deviceScaleFactor: 2` by default. For deep zooms or 4K output, record
|
|
253
|
+
with `deviceScaleFactor: 3`.
|
|
254
|
+
|
|
255
|
+
Camera moves across a page with much text make most of the file size. When a file must be
|
|
256
|
+
below an upload limit (GitHub accepts 10 MB), render with a higher `encode.crf`:
|
|
257
|
+
`--set encode.crf=23` gives about half the size of `standard`, and text stays sharp.
|
|
258
|
+
|
|
259
|
+
To change a camera move without a new recording, edit the `zoom` events in
|
|
260
|
+
`.autokast/<name>/session.json` (`focus` rectangle, `scale`, `t` in milliseconds) and render
|
|
261
|
+
again.
|
|
262
|
+
|
|
263
|
+
## Capture modes
|
|
264
|
+
|
|
265
|
+
- `realtime` (default): the recording takes as long as the video. The page is captured as fast
|
|
266
|
+
as it paints. On a machine without a GPU, a heavy page paints only 20 to 25 frames per
|
|
267
|
+
second while it scrolls or animates.
|
|
268
|
+
- `frame-perfect`: the library controls the page clock and captures one frame for each 1/60 s
|
|
269
|
+
of page time. Scrolls, drags and animations are exact at 60 fps on any machine, and the
|
|
270
|
+
result does not change with the machine load. The recording takes 3 to 4 times longer.
|
|
271
|
+
|
|
272
|
+
Work in `realtime` while you write and adjust the script. Make the final recording with
|
|
273
|
+
`--set capture.mode=frame-perfect` (or `capture: { mode: 'frame-perfect' }` in the script).
|
|
274
|
+
|
|
275
|
+
Rules for `frame-perfect`:
|
|
276
|
+
|
|
277
|
+
- It needs the default headless Chromium: no `--headed`, no `browser.channel`.
|
|
278
|
+
- Only the recorded page gets frames. Do not open a second tab in `setup` or `run`.
|
|
279
|
+
- A native popup, such as a date or color picker, stops the capture: the recording fails
|
|
280
|
+
after 30 s. For a `<select>`, use `cast.select`.
|
|
281
|
+
- `cast.wait` and all Cast pauses are page time. `page.waitForTimeout` is real time.
|
|
282
|
+
- Waits inside `cast.cut` cost little: no frames are captured there.
|
|
283
|
+
- Answers from a server arrive early in page time, so a loading state can be very short.
|
|
284
|
+
|
|
285
|
+
## Problems
|
|
286
|
+
|
|
287
|
+
| Symptom | Fix |
|
|
288
|
+
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
289
|
+
| `strict mode violation` | The locator matches several elements. Narrow it or use `.first()`. |
|
|
290
|
+
| `intercepts pointer events` | Something covers the target (dialog, toast). Close it or wait. |
|
|
291
|
+
| Timeout on a Cast call | The target is not visible. Look at `error.png`. Wait for it inside `cast.cut`. |
|
|
292
|
+
| Cursor does not move but the page changes | The script uses `page.click` or `page.keyboard`. Use `cast`. |
|
|
293
|
+
| Blurry text when zoomed | Lower the zoom scale or record with `deviceScaleFactor: 3`. |
|
|
294
|
+
| Choppy scroll, drag or page animation | The page paints slowly on this machine. Record with `--set capture.mode=frame-perfect`. |
|
|
295
|
+
|
|
296
|
+
## More
|
|
297
|
+
|
|
298
|
+
- [reference/jupyterlab.md](reference/jupyterlab.md): server setup and known problems of
|
|
299
|
+
JupyterLab, Notebook and JupyterLite. Read it only for these apps.
|
|
300
|
+
- `dist/types.d.ts` in the autokast package: every option with its type.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# JupyterLab, Notebook and JupyterLite
|
|
2
|
+
|
|
3
|
+
Setup and known problems only. Find the locators when you explore the app, as for any other
|
|
4
|
+
app.
|
|
5
|
+
|
|
6
|
+
Verified with JupyterLab 4.6 and JupyterLite 0.9.
|
|
7
|
+
|
|
8
|
+
## Server and start state
|
|
9
|
+
|
|
10
|
+
Start a server without a token, on a copy of your files, with clean settings:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
export JUPYTERLAB_SETTINGS_DIR="$(mktemp -d)" # theme changes stay out of the user settings
|
|
14
|
+
export JUPYTERLAB_WORKSPACES_DIR="$(mktemp -d)"
|
|
15
|
+
mkdir -p "$JUPYTERLAB_SETTINGS_DIR/@jupyterlab/apputils-extension"
|
|
16
|
+
echo '{ "fetchNews": "false", "checkForUpdates": false }' \
|
|
17
|
+
> "$JUPYTERLAB_SETTINGS_DIR/@jupyterlab/apputils-extension/notification.jupyterlab-settings"
|
|
18
|
+
jupyter lab --no-browser --port 8888 --IdentityProvider.token='' --ServerApp.root_dir="$WORK"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- The notification setting removes the "Jupyter news" prompt, which otherwise appears in the
|
|
22
|
+
recording.
|
|
23
|
+
- Open `http://localhost:8888/lab?reset`, and wait for the app in `setup`:
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
await page.locator('.jp-Launcher').waitFor();
|
|
27
|
+
await page.locator('#jupyterlab-splash').waitFor({ state: 'detached' });
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- `?reset` restores the layout only. The theme, the running kernels and the files from an
|
|
31
|
+
earlier run stay, so names such as `Untitled.ipynb` do not repeat. Reset them through the
|
|
32
|
+
REST API in `setup`. The API needs the XSRF cookie:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
const xsrf = (await page.context().cookies()).find((c) => c.name === '_xsrf')?.value ?? '';
|
|
36
|
+
await page.request.delete('http://localhost:8888/api/contents/Untitled.ipynb', {
|
|
37
|
+
headers: { 'X-XSRFToken': xsrf },
|
|
38
|
+
failOnStatusCode: false,
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- [`examples/jupyterlab`](https://github.com/jtpio/autokast/tree/main/examples/jupyterlab)
|
|
43
|
+
in the autokast repository has `serve.sh` and `reset.ts`, which do all of this. The npm
|
|
44
|
+
package does not include them.
|
|
45
|
+
- The same server serves Notebook at `/tree`. A notebook opens at `/notebooks/<path>`.
|
|
46
|
+
|
|
47
|
+
## Known problems
|
|
48
|
+
|
|
49
|
+
- **Kernel start.** After a new notebook opens, cut until the kernel is ready:
|
|
50
|
+
`await cast.cut(() => page.locator('.jp-Notebook-ExecutionIndicator[data-status="idle"]').waitFor())`.
|
|
51
|
+
- **Kernel time.** In frame-perfect mode, the kernel runs in real time, but the page clock
|
|
52
|
+
runs 3 to 4 times slower. A cell that takes 2 s finishes after about half a second of
|
|
53
|
+
video. To show a running cell, make it run longer, and cut the wait for its end.
|
|
54
|
+
- **Cell output.** After `Shift+Enter`, cut until the output exists, for example
|
|
55
|
+
`page.locator('.jp-OutputArea-output img').waitFor()`. The idle indicator can still show
|
|
56
|
+
the earlier idle state for a moment.
|
|
57
|
+
- **A document that opens** shows a blank panel or a spinner first. Pass `{ afterClick: 0 }`
|
|
58
|
+
to the click, then cut until the content is there and `.jp-Spinner` is detached.
|
|
59
|
+
- **Cell toolbar.** The toolbar of the active cell covers the right end of its editor. Click
|
|
60
|
+
an editor at `position: { x: 0.75, y: 0.5 }` or further left.
|
|
61
|
+
- **Figures.** Keep them small enough for the viewport, for example `figsize=(9, 3.2)` at
|
|
62
|
+
1280x720. A trailing `;` on the last line hides the text representation of a plot call.
|
|
63
|
+
- **Theme change.** It shows the splash screen for a moment. Cut it:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
await cast.cut(async () => {
|
|
67
|
+
await page.locator('body[data-jp-theme-light="false"]').waitFor({ state: 'attached' });
|
|
68
|
+
await page.locator('#jupyterlab-splash').waitFor({ state: 'detached' });
|
|
69
|
+
});
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`body` needs `{ state: 'attached' }`: Playwright does not see it as visible. In the command
|
|
73
|
+
palette, use the query `jupyterlab dark`: the query `dark` alone selects another command.
|
|
74
|
+
|
|
75
|
+
- **Split view.** Drag a document tab to the right third of the main area:
|
|
76
|
+
`cast.drag(tab, '#jp-main-dock-panel', { toPosition: { x: 0.85, y: 0.5 } })`. Close the
|
|
77
|
+
sidebar first (click its active tab): in a narrow panel, the notebook toolbar wraps over
|
|
78
|
+
the content.
|
|
79
|
+
- **Empty notebook.** A notebook that is scrolled down and then hidden behind another tab can
|
|
80
|
+
be empty when it shows again in a split view. Scroll it to the top first.
|
|
81
|
+
|
|
82
|
+
## JupyterLite
|
|
83
|
+
|
|
84
|
+
- Build and serve a site: `jupyter lite build --contents <dir> --output-dir <site>`, then serve
|
|
85
|
+
`<site>` with any static server and open `/lab/index.html`. The build writes a cache file
|
|
86
|
+
into the current directory, so run it in a temporary directory. `--contents` needs
|
|
87
|
+
`jupyter-server` in the same environment.
|
|
88
|
+
[`examples/jupyterlite/serve.sh`](https://github.com/jtpio/autokast/blob/main/examples/jupyterlite/serve.sh)
|
|
89
|
+
in the autokast repository does this.
|
|
90
|
+
- The kernel indicator shows `idle` before the kernel exists. Wait for the output, not for
|
|
91
|
+
the indicator.
|
|
92
|
+
- The first kernel start loads Pyodide, and each first import loads its package: several
|
|
93
|
+
seconds each. Cut these waits.
|
|
94
|
+
- Each recording uses a new browser profile with an empty cache. To make the recorded part
|
|
95
|
+
fast, warm the cache in `setup` on the same page: start a Console from the launcher, run
|
|
96
|
+
the imports the video needs, wait for the output, then load `/lab/index.html?reset` again.
|
|
97
|
+
- Pyodide comes from a CDN. When the browser needs a proxy, pass it in the definition:
|
|
98
|
+
`browser: { launchOptions: { proxy: { server: process.env.HTTPS_PROXY, bypass: 'localhost,127.0.0.1' } } }`.
|
|
99
|
+
- The notebook has no empty space after its last cell, so the last cell cannot scroll to the
|
|
100
|
+
center of the panel.
|