@kud/cli-shot 0.2.1 → 0.3.0
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/README.md +110 -12
- package/dist/chunk-ISLF4ISU.js +599 -0
- package/dist/cli.js +95 -5
- package/dist/index.d.ts +193 -4
- package/dist/index.js +1 -1
- package/package.json +16 -3
- package/player/chrome.css +273 -0
- package/player/fonts/LICENSE +21 -0
- package/player/fonts/README.md +21 -0
- package/player/fonts/SymbolsNerdFontMono-Regular.woff2 +0 -0
- package/player/index.html +37 -0
- package/player/player.js +267 -0
- package/dist/chunk-TKCXCDP2.js +0 -202
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
<img src="https://img.shields.io/badge/licence-MIT-blue?style=flat-square" alt="MIT licence" />
|
|
7
7
|
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="Node >=20" />
|
|
8
8
|
|
|
9
|
-
**Automatic screenshots of interactive CLIs — pty capture, terminal emulation, PNG out.**
|
|
9
|
+
**Automatic screenshots and recordings of interactive CLIs — pty capture, terminal emulation, PNG, asciicast, a web player, GIF or MP4 out.**
|
|
10
10
|
|
|
11
11
|
[Website](https://kud.io/projects/cli-shot) ·
|
|
12
12
|
[Documentation](https://kud.io/projects/cli-shot/docs) ·
|
|
@@ -25,6 +25,7 @@ window captures that go stale the next time the UI moves.
|
|
|
25
25
|
- **Fixtures by default** — `--mock` is on unless you opt out, because a screenshot outlives the moment it was taken
|
|
26
26
|
- **Deterministic and headless** — fixed size, fixed data, no window manager, runnable in CI
|
|
27
27
|
- **Scriptable last mile** — `--keys` reaches state a screen name can't address
|
|
28
|
+
- **Recordings too** — `--format cast` writes asciicast v2, `--format web` a static replay page ready for Vercel, and `--format gif` / `mp4` that page's window as a moving image
|
|
28
29
|
|
|
29
30
|
## Install
|
|
30
31
|
|
|
@@ -60,17 +61,113 @@ cli-shot --out shots --keys $'jjj\r' -- pcloud # drive deeper first
|
|
|
60
61
|
cli-shot --out shots --no-mock -- pcloud # real data (careful)
|
|
61
62
|
```
|
|
62
63
|
|
|
63
|
-
| flag
|
|
64
|
-
|
|
|
65
|
-
| `-o, --out <dir>`
|
|
66
|
-
| `--
|
|
67
|
-
| `--
|
|
68
|
-
| `--
|
|
69
|
-
| `--
|
|
70
|
-
| `--
|
|
71
|
-
| `--
|
|
72
|
-
| `--
|
|
73
|
-
| `--
|
|
64
|
+
| flag | |
|
|
65
|
+
| -------------------- | --------------------------------------------------- |
|
|
66
|
+
| `-o, --out <dir>` | directory to write into |
|
|
67
|
+
| `--format <list>` | `png`, `cast`, `web`, `gif`, `mp4`, comma-separated |
|
|
68
|
+
| `--only <screen>` | shoot one screen instead of every screen |
|
|
69
|
+
| `--list` | print the screens the command offers, and stop |
|
|
70
|
+
| `--cols` / `--rows` | terminal size (default 110×32) |
|
|
71
|
+
| `--settle <ms>` | how long the screen must hold still (default 350) |
|
|
72
|
+
| `--jobs <n>` | screens shot at once; defaults to the core count |
|
|
73
|
+
| `--keys <sequence>` | keystrokes sent once the screen has drawn |
|
|
74
|
+
| `--font <family>` | font to render with; defaults to a Nerd Font |
|
|
75
|
+
| `--title <text>` | page title for `web`, window title for `gif`/`mp4` |
|
|
76
|
+
| `--base <path>` | `<base href>` for the web page, see below |
|
|
77
|
+
| `--fps <n>` | `gif`/`mp4` frames per second (default 15) |
|
|
78
|
+
| `--speed <n>` | `gif`/`mp4` playback speed (default 1) |
|
|
79
|
+
| `--max-duration <s>` | `gif`/`mp4` longest replay; sped up to fit |
|
|
80
|
+
| `--loop <n>` | `gif` plays, 0 for forever (default 0) |
|
|
81
|
+
| `--scale <n>` | `gif`/`mp4` pixel density, 2 for retina (default 1) |
|
|
82
|
+
| `--no-mock` | drive real data instead of fixtures |
|
|
83
|
+
|
|
84
|
+
## Recordings and the web player
|
|
85
|
+
|
|
86
|
+
The same capture that becomes a PNG can be kept as a recording. The pty
|
|
87
|
+
stream is written as it arrived, timed, up to the moment the screen settled —
|
|
88
|
+
so a cast always ends on the frame its PNG shows.
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
cli-shot --out demo --format cast -- pcloud # demo/<screen>.cast
|
|
92
|
+
cli-shot --out demo --format png,cast -- pcloud # both, from one capture
|
|
93
|
+
cli-shot --out demo --format web -- pcloud # casts + a replay page
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`.cast` files are [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/),
|
|
97
|
+
so `asciinema play demo/sync.cast` and any asciicast player read them.
|
|
98
|
+
|
|
99
|
+
`--format web` writes the casts plus a static page that replays them, one
|
|
100
|
+
window per screen, into the same folder:
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
demo/
|
|
104
|
+
├── index.html
|
|
105
|
+
├── vercel.json
|
|
106
|
+
├── <screen>.cast
|
|
107
|
+
└── assets/ player.js · chrome.css · xterm.js · Symbols Nerd Font
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The folder deploys as it stands — `vercel deploy demo` — with no build step.
|
|
111
|
+
The page replays through xterm.js, the browser build of the emulator that
|
|
112
|
+
resolved the capture, and bundles the Symbols Nerd Font so icons draw as they
|
|
113
|
+
do in a real terminal. Each recording sits in a dark macOS-style window,
|
|
114
|
+
whatever the page's light or dark mode (pin one with `?theme=light` or
|
|
115
|
+
`?theme=dark`). A window shows its final frame first, plays once when it
|
|
116
|
+
scrolls into view (never on its own under `prefers-reduced-motion`), and has
|
|
117
|
+
play/pause, restart and 1×/2× speed controls. On a narrow screen the terminal is scaled down
|
|
118
|
+
rather than re-wrapped, so a phone sees the same layout, smaller. Replay only:
|
|
119
|
+
nothing on the page accepts input.
|
|
120
|
+
|
|
121
|
+
The look lives in one file, `assets/chrome.css` (`player/chrome.css` in this
|
|
122
|
+
repository): page, window frame and the terminal palette, all as CSS custom
|
|
123
|
+
properties that the player reads.
|
|
124
|
+
|
|
125
|
+
When a site serves the page under another path — a rewrite from
|
|
126
|
+
`kud.io/projects/<name>/demo` to the deployment, say — pass that path so the
|
|
127
|
+
page's relative URLs resolve against it:
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
cli-shot --out demo --format web --base /projects/pcloud/demo/ -- pcloud
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
To try it locally, from a clone:
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
npm install && npm run build
|
|
137
|
+
npm run example:web # drives examples/harbour.mjs, an invented TUI
|
|
138
|
+
npx serve examples/web # or any static server
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`examples/casts/` holds recordings of the same fixture, made with
|
|
142
|
+
`npm run example:casts`.
|
|
143
|
+
|
|
144
|
+
## GIF and MP4
|
|
145
|
+
|
|
146
|
+
Where a moving image has to travel on its own — a social post, a slide, a
|
|
147
|
+
README — the same capture can be filmed as a GIF or an MP4:
|
|
148
|
+
|
|
149
|
+
```sh
|
|
150
|
+
cli-shot --out demo --format gif -- pcloud # demo/<screen>.gif
|
|
151
|
+
cli-shot --out demo --format png,web,gif,mp4 -- pcloud # all from one capture
|
|
152
|
+
cli-shot --out demo --format gif --speed 2 --max-duration 6 -- pcloud
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The frames are the web player's own window — the macOS chrome from
|
|
156
|
+
`chrome.css`, the bundled Symbols Nerd Font, xterm.js — rendered in headless
|
|
157
|
+
Chromium and encoded with ffmpeg, so a GIF looks like the web demo it sits
|
|
158
|
+
beside. The recording is stepped on its own clock rather than played in real
|
|
159
|
+
time, and only frames where something changed are kept, so the output is
|
|
160
|
+
identical on a slow machine and a fast one, and small: a single palette, no
|
|
161
|
+
dithering, only the changed rectangle stored per frame. The last frame, the
|
|
162
|
+
one the PNG shows, holds for two seconds before the loop.
|
|
163
|
+
|
|
164
|
+
`--max-duration` speeds a long recording up to fit rather than cutting it,
|
|
165
|
+
so a GIF still ends on the settled screen. `--loop` counts plays, `0` meaning
|
|
166
|
+
forever; an MP4 ignores it.
|
|
167
|
+
|
|
168
|
+
Filming needs two things the PNG path does not: `ffmpeg` on `PATH`, and
|
|
169
|
+
Playwright with its Chromium (`npm install playwright && npx playwright install chromium`).
|
|
170
|
+
Both are only looked for when `gif` or `mp4` is asked for.
|
|
74
171
|
|
|
75
172
|
## The contract
|
|
76
173
|
|
|
@@ -94,6 +191,7 @@ than they usually intend, and a screenshot outlives the moment it was taken.
|
|
|
94
191
|
|
|
95
192
|
```
|
|
96
193
|
node-pty → @xterm/headless → serialize → freeze → png
|
|
194
|
+
└────────────── timed stream ──────────────────→ cast → web page
|
|
97
195
|
```
|
|
98
196
|
|
|
99
197
|
The middle step is the one that isn't obvious. A pty hands back **every redraw
|