@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 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>` | directory to write PNGs into |
66
- | `--only <screen>` | shoot one screen instead of every screen |
67
- | `--list` | print the screens the command offers, and stop |
68
- | `--cols` / `--rows` | terminal size (default 110×32) |
69
- | `--settle <ms>` | how long the screen must hold still (default 350) |
70
- | `--jobs <n>` | screens shot at once; defaults to the core count |
71
- | `--keys <sequence>` | keystrokes sent once the screen has drawn |
72
- | `--font <family>` | font to render with; defaults to a Nerd Font |
73
- | `--no-mock` | drive real data instead of fixtures |
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