asciianything 1.1.4 → 1.2.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.
Files changed (3) hide show
  1. package/README.md +56 -61
  2. package/package.json +7 -3
  3. package/src/cli.js +51 -6
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # asciianything
4
4
 
5
- **A video rebuilt from coloured lowercase prose. One command, every frame, at the source's own resolution and frame rate.**
5
+ **A 3D scene, a video, a photo — anything with pixels, rebuilt from coloured lowercase prose. One command, at the source's own resolution and frame rate.**
6
6
 
7
7
  [![Stars](https://img.shields.io/github/stars/sloemo01/asciianything?style=flat-square&color=1d1d1f&logo=github&label=stars)](https://github.com/sloemo01/asciianything/stargazers)
8
8
  [![Forks](https://img.shields.io/github/forks/sloemo01/asciianything?style=flat-square&color=1d1d1f&label=forks)](https://github.com/sloemo01/asciianything/forks)
@@ -18,28 +18,44 @@
18
18
 
19
19
  <sub><b>Night highway</b>, 19.4 s, 1920×1080 &nbsp;·&nbsp; <b>Sunset</b>, 11.6 s, 3840×2160·60</sub>
20
20
 
21
- <sub>Two clips rendered by this package. Click a tile for the MP4.</sub>
21
+ <sub>Two clips rendered by this package — the same command that turns a still photo into a PNG or a folder of three.js frames into a clip.</sub>
22
22
 
23
23
  [**Install it**](#install-it) &nbsp;·&nbsp; [**Run it**](#run-it) &nbsp;·&nbsp; [What is in here](#what-is-in-here) &nbsp;·&nbsp; [How it works](#how-it-works) &nbsp;·&nbsp; [Verification](#verification) &nbsp;·&nbsp; [Credits](#credits)
24
24
 
25
25
  </div>
26
26
 
27
27
  Every cell of the picture holds one stable English character. Close up it is lowercase prose you can read; at normal
28
- viewing distance the same cells add up to the footage — same framing, same colour, same exposure, same motion. Nothing is
29
- painted under the letters: all visible structure comes from glyph ink, weight and colour.
28
+ viewing distance the same cells add up to the source — same framing, same colour, same exposure, and for moving inputs the
29
+ same motion. Nothing is painted under the letters: all visible structure comes from glyph ink, weight and colour.
30
30
 
31
- This is not an `@%#*+=-:.` brightness ramp, and it is not text laid over a video. One source frame goes in, one rendered
31
+ This is not an `@%#*+=-:.` brightness ramp, and it is not text laid over a picture. One source frame goes in, one rendered
32
32
  frame comes out, and the only things that change between frames are scene colour, sampled luminance, glyph weight and
33
33
  emitted colour. No zoom, pan, transition, grain or vignette is ever added.
34
34
 
35
35
  ![source and output, same frame](https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/sunset-comparison.jpg)
36
36
 
37
+ ## What it converts
38
+
39
+ | input | command | output |
40
+ | --- | --- | --- |
41
+ | video — mp4, mov, webm, gif, anything ffmpeg decodes | `asciianything clip.mp4` | `clip-ascii.mp4` |
42
+ | photo — png, jpg, webp, avif, tiff, bmp | `asciianything shot.jpg` | `shot-ascii.png` |
43
+ | frame sequence — a folder of numbered PNGs | `asciianything frames/ --fps 60` | `frames-ascii.mp4` |
44
+
45
+ **3D scenes.** A three.js scene is a frame sequence waiting to happen: render it to PNGs (`renderer.render()` in a loop
46
+ behind Puppeteer or Playwright, or any headless capture), then point the tool at the folder. Frame rate is yours to set
47
+ with `--fps`; resolution comes from the frames. The same path handles Blender renders, stop-motion stills, screen
48
+ recordings split to frames, and anything else that can write `0001.png`.
49
+
50
+ A single photo is rendered and encoded as one PNG — the still path shares the renderer, the atlas and the calibration
51
+ with the video path, so a photo and a frame of a clip at the same size match exactly.
52
+
37
53
  ## What it is
38
54
 
39
- A small Node CLI around a deterministic renderer.
55
+ A small Node CLI around a deterministic renderer, for video, stills and frame sequences alike.
40
56
 
41
57
  - **Prose, not noise.** A sentence bank is shuffled per row with a deterministic hash: every row is a different slice of
42
- the bank, no row repeats the row above it, and each cell keeps the same character for the whole video.
58
+ the bank, no row repeats the row above it, and each cell keeps the same character for the whole input.
43
59
  - **Fidelity first.** One fixed cover transform, one fixed grid, one rendered frame per decoded source frame. Frame
44
60
  count, duration, resolution and frame rate are probed from the source and reproduced exactly.
45
61
  - **Linear light.** sRGB is decoded before any averaging, compensation or comparison, and encoded once on the way out.
@@ -48,46 +64,27 @@ A small Node CLI around a deterministic renderer.
48
64
 
49
65
  ## Install it
50
66
 
51
- Paste this into an agent that can run shell commands. It asks where the copy should live, clones the repository, installs
52
- the dependency, renders a test frame and reports what it measured before it renders anything for you. The published
53
- package is the same code, so the agent can work from either.
67
+ Paste this into an agent that can run shell commands. It installs the published package, proves it on a still, and
68
+ reports what it measured before rendering anything for you.
54
69
 
55
70
  ```text
56
- Install asciianything here, then use it to render a video.
57
-
58
- Repo: https://github.com/sloemo01/asciianything
59
-
60
- 1. Ask me where the folder should go before downloading anything,
61
- and wait for my answer. Propose ~/tools/asciianything as the default.
62
- Do not pick a path silently.
63
- 2. Download the whole repository, not just the README:
64
- git clone https://github.com/sloemo01/asciianything.git "<target>"
65
- Without git:
66
- curl -L -o asciianything.tar.gz \
67
- https://github.com/sloemo01/asciianything/archive/main.tar.gz
68
- tar xzf asciianything.tar.gz && mv asciianything-main "<target>"
69
- 3. Install and prove it:
70
- cd "<target>" && npm ci
71
- node src/cli.js --help
72
- node src/cli.js assets/night-highway-1080p.mp4 --still 8 \
73
- --font-size 10 --calibration 0.76 --halo 1.2 --halo-radius 8 \
74
- -o /tmp/proof.png
75
- Print the commit hash (git -C "<target>" rev-parse --short HEAD), the
76
- grid size the CLI reports, and the size of /tmp/proof.png. If npm ci,
77
- ffmpeg, or the still fails, say so and stop. Never describe this tool
78
- from memory.
79
- 4. Check the machine has ffmpeg and ffprobe on PATH; if not, tell me the
80
- install command for my platform and stop.
81
- 5. Report back in this order: install path and commit, the grid and glyph
82
- settings, the encoder flags, and three rules from "How it works" with
83
- the section each came from.
84
- 6. Then ask me for the video to convert, and for the font size. Ask once;
85
- do not interview me. Render it, probe the output with ffprobe, and show
86
- me the frame count, duration and resolution next to the source's.
71
+ Install asciianything from npm, verify it, then convert a clip or a still.
72
+
73
+ 1. Confirm node 18+ and ffmpeg/ffprobe are on PATH. If either is missing, give
74
+ me the install command for my platform and stop.
75
+ 2. npm i -g asciianything (one-off runs also work with npx asciianything)
76
+ 3. Prove it before describing it:
77
+ asciianything --help
78
+ asciianything <any.mp4> --still 8 -o /tmp/proof.png
79
+ Print the version, the grid the CLI reports and the size of proof.png. If a
80
+ step fails, say so and stop. Never describe the tool from memory.
81
+ 4. Report in this order: version, grid and glyph size, encoder flags, then three
82
+ rules from "How it works" with the section each came from.
83
+ 5. Ask me for the input (video, photo, or a folder of frames) and the font size
84
+ once, render it, and probe the output next to the source: frames, duration,
85
+ resolution.
87
86
  ```
88
87
 
89
- Or skip the repository entirely:
90
-
91
88
  ```bash
92
89
  npx asciianything night-drive.mp4 # one clip, no install
93
90
  npm i -g asciianything # or keep it on PATH
@@ -98,28 +95,24 @@ Node 18+ and `ffmpeg` / `ffprobe` are the only requirements.
98
95
  ### Update it
99
96
 
100
97
  ```text
101
- Update my asciianything install, then report what changed.
102
-
103
- 1. Ask me for the folder before touching anything, and wait.
104
- 2. Print the current commit, then make the update reversible:
105
- git -C "<target>" rev-parse --short HEAD
106
- git -C "<target>" diff > my-changes.patch
107
- cp -R "<target>" "<target>.bak"
108
- 3. Pull the latest main:
109
- git -C "<target>" pull --ff-only
110
- cd "<target>" && npm ci
111
- 4. Diff the CLI help and the README changelog before and after, and tell
112
- me what new flags or defaults appeared. Do not re-render anything yet.
113
- 5. If the build or a test still fails, restore "<target>.bak" and say so.
98
+ Update asciianything, then report what changed.
99
+
100
+ 1. Print the current version and --help.
101
+ 2. npm i -g asciianything@latest
102
+ 3. Diff the old and new --help, list new flags or changed defaults, and stop
103
+ before re-rendering anything. If the install fails, say so.
114
104
  ```
115
105
 
116
106
  ## Run it
117
107
 
118
108
  ```bash
119
- npx asciianything night-drive.mp4
109
+ npx asciianything night-drive.mp4 # video -> night-drive-ascii.mp4
110
+ npx asciianything poster.png # photo -> poster-ascii.png
111
+ npx asciianything frames/ --fps 60 # 3D scene frames -> frames-ascii.mp4
120
112
  ```
121
113
 
122
- That writes `night-drive-ascii.mp4` at the source's resolution, frame rate and duration.
114
+ A video is written at the source's resolution, frame rate and duration; a photo is written as a single PNG at the
115
+ photo's resolution.
123
116
 
124
117
  ```bash
125
118
  # a specific output, larger letters
@@ -152,7 +145,8 @@ npx asciianything clip.mp4 --prose my-words.txt
152
145
  | `--detail <n>` / `--color-detail <n>` | `0.14` / `0.1` | subcell luminance and colour recovery |
153
146
  | `--prose <file>` | bundled bank | `.txt` sentences or a `.json` array |
154
147
  | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed |
155
- | `--still <seconds>` | — | render one PNG instead of a video |
148
+ | `--fps <n>` | `30` | frame rate for an image-sequence input |
149
+ | `--still <seconds>` | — | render one PNG of a video instead of the whole file |
156
150
  | `--limit <n>` | — | stop after n frames |
157
151
  | `--info` | — | print grid, cell size and measured coverage, then exit |
158
152
 
@@ -160,7 +154,7 @@ npx asciianything clip.mp4 --prose my-words.txt
160
154
 
161
155
  ```text
162
156
  asciianything/
163
- src/cli.js argument parsing, ffprobe, the decode → render → encode pipe
157
+ src/cli.js argument parsing, ffprobe, video / photo / frame-sequence input
164
158
  src/render.js sampling, weight choice, coverage division, halo, composite
165
159
  src/atlas.js Skia glyph rasterisation and measured ink coverage
166
160
  src/prose.js sentence bank → the fixed character grid
@@ -208,7 +202,8 @@ reshuffled text.
208
202
 
209
203
  **One frame in, one frame out.** The decoder is asked for raw RGBA at the source's native size, the renderer writes RGB,
210
204
  and the encoder is told the source's frame rate and colour tags. Frame count, duration, resolution and pixel format are
211
- probed on both files afterwards.
205
+ probed on both files afterwards. A photo takes the same path with a single frame; a folder of frames is decoded at the
206
+ `--fps` you give it.
212
207
 
213
208
  ## Verification
214
209
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "asciianything",
3
- "version": "1.1.4",
4
- "description": "Turn any video into a mosaic of coloured lowercase prose, frame-accurate, with ffmpeg.",
3
+ "version": "1.2.0",
4
+ "description": "Turn a 3D scene, a video or a photo into a mosaic of coloured lowercase prose \u2014 frame-accurate, with ffmpeg.",
5
5
  "keywords": [
6
6
  "ascii",
7
7
  "ascii-art",
@@ -10,7 +10,11 @@
10
10
  "text-art",
11
11
  "typography",
12
12
  "ffmpeg",
13
- "terminal"
13
+ "terminal",
14
+ "three.js",
15
+ "photo",
16
+ "image",
17
+ "render"
14
18
  ],
15
19
  "license": "MIT",
16
20
  "author": "sloemo01",
package/src/cli.js CHANGED
@@ -9,10 +9,12 @@ const { createCanvas } = require('@napi-rs/canvas');
9
9
  const { Renderer } = require('./render');
10
10
 
11
11
  const HELP = `
12
- asciianything — turn a video into a mosaic of coloured lowercase prose.
12
+ asciianything — turn anything with pixels into coloured lowercase prose.
13
13
 
14
14
  usage:
15
- asciianything <input.mp4> [-o output.mp4] [options]
15
+ asciianything <video.mp4> [-o out.mp4]
16
+ asciianything <photo.png> [-o out.png]
17
+ asciianything <frames-dir/> [--fps] [-o out.mp4]
16
18
 
17
19
  options:
18
20
  -o, --out <file> output video (default: <input>-ascii.mp4)
@@ -32,6 +34,7 @@ options:
32
34
  --prose <file> sentence bank (.txt or .json) instead of the bundled one
33
35
  --crf <n> x264 quality, lower is better (default 17)
34
36
  --preset <name> x264 preset (default slow)
37
+ --fps <n> frame rate for an image-sequence input (default 30)
35
38
  --still <seconds> render one frame to PNG instead of the whole video
36
39
  --limit <n> only render the first n frames (preview)
37
40
  --info print grid and coverage stats, then exit
@@ -77,6 +80,41 @@ function probe(file) {
77
80
  };
78
81
  }
79
82
 
83
+ const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.tif', '.tiff', '.bmp', '.avif']);
84
+
85
+ function probeImage(file) {
86
+ const res = spawnSync(
87
+ 'ffprobe',
88
+ ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'json', file],
89
+ { encoding: 'utf8' }
90
+ );
91
+ if (res.status !== 0) fail(`ffprobe failed on ${file}`);
92
+ const info = JSON.parse(res.stdout).streams[0];
93
+ if (!info || !info.width) fail(`no image data in ${file}`);
94
+ return { width: info.width, height: info.height, fps: 0, rate: '0/1', frames: 1, duration: 0 };
95
+ }
96
+
97
+ function probeSequence(dir, fps) {
98
+ const files = fs
99
+ .readdirSync(dir)
100
+ .filter((f) => IMAGE_EXT.has(path.extname(f).toLowerCase()))
101
+ .sort();
102
+ if (!files.length) fail(`no images in ${dir}`);
103
+ const first = path.join(dir, files[0]);
104
+ const img = probeImage(first);
105
+ const ext = path.extname(files[0]).toLowerCase();
106
+ const same = files.filter((f) => path.extname(f).toLowerCase() === ext).length;
107
+ return {
108
+ width: img.width,
109
+ height: img.height,
110
+ fps,
111
+ rate: `${fps}/1`,
112
+ frames: same,
113
+ duration: same / fps,
114
+ pattern: path.join(dir, `*${ext}`),
115
+ };
116
+ }
117
+
80
118
  async function* readFrames(stream, frameBytes) {
81
119
  const buf = Buffer.allocUnsafe(frameBytes);
82
120
  let fill = 0;
@@ -138,6 +176,7 @@ async function main() {
138
176
  prose: { type: 'string' },
139
177
  crf: { type: 'string' },
140
178
  preset: { type: 'string' },
179
+ fps: { type: 'string' },
141
180
  still: { type: 'string' },
142
181
  limit: { type: 'string' },
143
182
  info: { type: 'boolean' },
@@ -160,7 +199,10 @@ async function main() {
160
199
 
161
200
  const input = positionals[0];
162
201
  if (!fs.existsSync(input)) fail(`no such file: ${input}`);
163
- const meta = probe(input);
202
+ const isDir = fs.statSync(input).isDirectory();
203
+ const isImage = !isDir && IMAGE_EXT.has(path.extname(input).toLowerCase());
204
+ const seqFps = Number(values.fps || 30);
205
+ const meta = isDir ? probeSequence(input, seqFps) : isImage ? probeImage(input) : probe(input);
164
206
  const quiet = !!values.quiet;
165
207
 
166
208
  const num = (v, d) => (v === undefined ? d : Number(v));
@@ -200,8 +242,8 @@ async function main() {
200
242
  return;
201
243
  }
202
244
 
203
- if (values.still !== undefined) {
204
- const at = Number(values.still);
245
+ if (isImage || values.still !== undefined) {
246
+ const at = isImage ? 0 : Number(values.still);
205
247
  const png = await renderStill(input, at, renderer, meta);
206
248
  const out = values.out || `${path.basename(input, path.extname(input))}-ascii.png`;
207
249
  fs.writeFileSync(out, png);
@@ -212,9 +254,12 @@ async function main() {
212
254
  const out = values.out || `${path.basename(input, path.extname(input))}-ascii.mp4`;
213
255
  const limit = values.limit ? Number(values.limit) : 0;
214
256
 
257
+ const decodeArgs = isDir
258
+ ? ['-v', 'error', '-framerate', String(seqFps), '-pattern_type', 'glob', '-i', meta.pattern]
259
+ : ['-v', 'error', '-i', input];
215
260
  const decoder = spawn(
216
261
  'ffmpeg',
217
- ['-v', 'error', '-i', input, '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
262
+ [...decodeArgs, '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
218
263
  { stdio: ['ignore', 'pipe', 'pipe'] }
219
264
  );
220
265
  let decodeErr = '';