asciianything 1.1.5 → 1.2.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.
Files changed (3) hide show
  1. package/README.md +49 -16
  2. package/package.json +7 -3
  3. package/src/cli.js +74 -10
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,51 @@
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
+ **Exact by construction.** A photo is one frame of the same pipeline: the decoder flags, the renderer call, the atlas and
51
+ the calibration are the video path with a single frame in it. `asciianything shot.png` and frame 0 of a clip made from
52
+ `shot.png` are byte-identical — measured at 0 differing pixels on a 3840×2160 frame.
53
+
54
+ Output size always equals input size, odd dimensions included: a 1001×667 frame encodes as 1001×667, with the encoder
55
+ switching to `yuv444p` automatically because `yuv420p` needs even dimensions. Video at the default `--crf 17` is lossy on
56
+ purpose (that is what makes a 19-second 1080p clip 54 MB); `--crf 0 --pix-fmt yuv444p` keeps the decoded frame within ±2
57
+ levels of the rendered RGB, which is the rounding of the RGB→YUV→RGB matrix and nothing else. Photos are always written
58
+ as exact PNG.
59
+
37
60
  ## What it is
38
61
 
39
- A small Node CLI around a deterministic renderer.
62
+ A small Node CLI around a deterministic renderer, for video, stills and frame sequences alike.
40
63
 
41
64
  - **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.
65
+ the bank, no row repeats the row above it, and each cell keeps the same character for the whole input.
43
66
  - **Fidelity first.** One fixed cover transform, one fixed grid, one rendered frame per decoded source frame. Frame
44
67
  count, duration, resolution and frame rate are probed from the source and reproduced exactly.
45
68
  - **Linear light.** sRGB is decoded before any averaging, compensation or comparison, and encoded once on the way out.
@@ -52,7 +75,7 @@ Paste this into an agent that can run shell commands. It installs the published
52
75
  reports what it measured before rendering anything for you.
53
76
 
54
77
  ```text
55
- Install asciianything from npm, verify it, then render a video.
78
+ Install asciianything from npm, verify it, then convert a clip or a still.
56
79
 
57
80
  1. Confirm node 18+ and ffmpeg/ffprobe are on PATH. If either is missing, give
58
81
  me the install command for my platform and stop.
@@ -64,8 +87,9 @@ Install asciianything from npm, verify it, then render a video.
64
87
  step fails, say so and stop. Never describe the tool from memory.
65
88
  4. Report in this order: version, grid and glyph size, encoder flags, then three
66
89
  rules from "How it works" with the section each came from.
67
- 5. Ask me for the video and the font size once, render it, and probe the output
68
- with ffprobe next to the source: frames, duration, resolution.
90
+ 5. Ask me for the input (video, photo, or a folder of frames) and the font size
91
+ once, render it, and probe the output next to the source: frames, duration,
92
+ resolution.
69
93
  ```
70
94
 
71
95
  ```bash
@@ -89,10 +113,13 @@ Update asciianything, then report what changed.
89
113
  ## Run it
90
114
 
91
115
  ```bash
92
- npx asciianything night-drive.mp4
116
+ npx asciianything night-drive.mp4 # video -> night-drive-ascii.mp4
117
+ npx asciianything poster.png # photo -> poster-ascii.png
118
+ npx asciianything frames/ --fps 60 # 3D scene frames -> frames-ascii.mp4
93
119
  ```
94
120
 
95
- That writes `night-drive-ascii.mp4` at the source's resolution, frame rate and duration.
121
+ A video is written at the source's resolution, frame rate and duration; a photo is written as a single PNG at the
122
+ photo's resolution.
96
123
 
97
124
  ```bash
98
125
  # a specific output, larger letters
@@ -124,8 +151,10 @@ npx asciianything clip.mp4 --prose my-words.txt
124
151
  | `--diffusion-adaptive <n>` | `0.25` | extra softening for bright cells |
125
152
  | `--detail <n>` / `--color-detail <n>` | `0.14` / `0.1` | subcell luminance and colour recovery |
126
153
  | `--prose <file>` | bundled bank | `.txt` sentences or a `.json` array |
127
- | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed |
128
- | `--still <seconds>` | — | render one PNG instead of a video |
154
+ | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed — `--crf 0` is lossless |
155
+ | `--pix-fmt <fmt>` | `yuv420p` (`yuv444p` when odd) | encoder pixel format; `yuv444p` keeps full chroma |
156
+ | `--fps <n>` | `30` | frame rate for an image-sequence input |
157
+ | `--still <seconds>` | — | render one PNG of a video instead of the whole file |
129
158
  | `--limit <n>` | — | stop after n frames |
130
159
  | `--info` | — | print grid, cell size and measured coverage, then exit |
131
160
 
@@ -133,7 +162,7 @@ npx asciianything clip.mp4 --prose my-words.txt
133
162
 
134
163
  ```text
135
164
  asciianything/
136
- src/cli.js argument parsing, ffprobe, the decode → render → encode pipe
165
+ src/cli.js argument parsing, ffprobe, video / photo / frame-sequence input
137
166
  src/render.js sampling, weight choice, coverage division, halo, composite
138
167
  src/atlas.js Skia glyph rasterisation and measured ink coverage
139
168
  src/prose.js sentence bank → the fixed character grid
@@ -181,7 +210,8 @@ reshuffled text.
181
210
 
182
211
  **One frame in, one frame out.** The decoder is asked for raw RGBA at the source's native size, the renderer writes RGB,
183
212
  and the encoder is told the source's frame rate and colour tags. Frame count, duration, resolution and pixel format are
184
- probed on both files afterwards.
213
+ probed on both files afterwards. A photo takes the same path with a single frame; a folder of frames is decoded at the
214
+ `--fps` you give it.
185
215
 
186
216
  ## Verification
187
217
 
@@ -195,6 +225,9 @@ Measured against the sources after encoding, in linear light, one-cell blur:
195
225
  Frame counts, durations, dimensions and colour tags are probed independently after encoding. The sunset run additionally
196
226
  holds every measured region — top sky, cirrus, cloud fan, sea band, wet sand, rocks — inside ±1.6 %.
197
227
 
228
+ Two more exactness checks: the photo path against frame 0 of a clip of the same image gives **0 differing pixels**, and a
229
+ `--crf 0 --pix-fmt yuv444p` encode of that frame decodes back within **±2 levels** of the rendered RGB.
230
+
198
231
  ## Demos
199
232
 
200
233
  Both clips above are rendered with this package:
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "asciianything",
3
- "version": "1.1.5",
4
- "description": "Turn any video into a mosaic of coloured lowercase prose, frame-accurate, with ffmpeg.",
3
+ "version": "1.2.1",
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)
@@ -30,8 +32,10 @@ options:
30
32
  --detail <n> subcell luminance detail recovery (default 0.14)
31
33
  --color-detail <n> subcell colour recovery (default 0.1)
32
34
  --prose <file> sentence bank (.txt or .json) instead of the bundled one
33
- --crf <n> x264 quality, lower is better (default 17)
35
+ --crf <n> x264 quality, lower is better, 0 = lossless (default 17)
36
+ --pix-fmt <fmt> encoder pixel format: yuv420p or yuv444p (default yuv420p)
34
37
  --preset <name> x264 preset (default slow)
38
+ --fps <n> frame rate for an image-sequence input (default 30)
35
39
  --still <seconds> render one frame to PNG instead of the whole video
36
40
  --limit <n> only render the first n frames (preview)
37
41
  --info print grid and coverage stats, then exit
@@ -77,6 +81,41 @@ function probe(file) {
77
81
  };
78
82
  }
79
83
 
84
+ const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.tif', '.tiff', '.bmp', '.avif']);
85
+
86
+ function probeImage(file) {
87
+ const res = spawnSync(
88
+ 'ffprobe',
89
+ ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'json', file],
90
+ { encoding: 'utf8' }
91
+ );
92
+ if (res.status !== 0) fail(`ffprobe failed on ${file}`);
93
+ const info = JSON.parse(res.stdout).streams[0];
94
+ if (!info || !info.width) fail(`no image data in ${file}`);
95
+ return { width: info.width, height: info.height, fps: 0, rate: '0/1', frames: 1, duration: 0 };
96
+ }
97
+
98
+ function probeSequence(dir, fps) {
99
+ const files = fs
100
+ .readdirSync(dir)
101
+ .filter((f) => IMAGE_EXT.has(path.extname(f).toLowerCase()))
102
+ .sort();
103
+ if (!files.length) fail(`no images in ${dir}`);
104
+ const first = path.join(dir, files[0]);
105
+ const img = probeImage(first);
106
+ const ext = path.extname(files[0]).toLowerCase();
107
+ const same = files.filter((f) => path.extname(f).toLowerCase() === ext).length;
108
+ return {
109
+ width: img.width,
110
+ height: img.height,
111
+ fps,
112
+ rate: `${fps}/1`,
113
+ frames: same,
114
+ duration: same / fps,
115
+ pattern: path.join(dir, `*${ext}`),
116
+ };
117
+ }
118
+
80
119
  async function* readFrames(stream, frameBytes) {
81
120
  const buf = Buffer.allocUnsafe(frameBytes);
82
121
  let fill = 0;
@@ -137,7 +176,9 @@ async function main() {
137
176
  'color-detail': { type: 'string' },
138
177
  prose: { type: 'string' },
139
178
  crf: { type: 'string' },
179
+ 'pix-fmt': { type: 'string' },
140
180
  preset: { type: 'string' },
181
+ fps: { type: 'string' },
141
182
  still: { type: 'string' },
142
183
  limit: { type: 'string' },
143
184
  info: { type: 'boolean' },
@@ -160,7 +201,10 @@ async function main() {
160
201
 
161
202
  const input = positionals[0];
162
203
  if (!fs.existsSync(input)) fail(`no such file: ${input}`);
163
- const meta = probe(input);
204
+ const isDir = fs.statSync(input).isDirectory();
205
+ const isImage = !isDir && IMAGE_EXT.has(path.extname(input).toLowerCase());
206
+ const seqFps = Number(values.fps || 30);
207
+ const meta = isDir ? probeSequence(input, seqFps) : isImage ? probeImage(input) : probe(input);
164
208
  const quiet = !!values.quiet;
165
209
 
166
210
  const num = (v, d) => (v === undefined ? d : Number(v));
@@ -200,8 +244,8 @@ async function main() {
200
244
  return;
201
245
  }
202
246
 
203
- if (values.still !== undefined) {
204
- const at = Number(values.still);
247
+ if (isImage || values.still !== undefined) {
248
+ const at = isImage ? 0 : Number(values.still);
205
249
  const png = await renderStill(input, at, renderer, meta);
206
250
  const out = values.out || `${path.basename(input, path.extname(input))}-ascii.png`;
207
251
  fs.writeFileSync(out, png);
@@ -212,9 +256,20 @@ async function main() {
212
256
  const out = values.out || `${path.basename(input, path.extname(input))}-ascii.mp4`;
213
257
  const limit = values.limit ? Number(values.limit) : 0;
214
258
 
259
+ // yuv420p needs even dimensions; pick 4:4:4 automatically when they are odd
260
+ // so an odd-sized frame sequence still encodes at its exact size.
261
+ const even = meta.width % 2 === 0 && meta.height % 2 === 0;
262
+ const pixFmt = values['pix-fmt'] || (even ? 'yuv420p' : 'yuv444p');
263
+ if (!even && !values['pix-fmt'] && !quiet) {
264
+ console.error(`${meta.width}x${meta.height} is odd: encoding yuv444p (yuv420p needs even sizes)`);
265
+ }
266
+
267
+ const decodeArgs = isDir
268
+ ? ['-v', 'error', '-framerate', String(seqFps), '-pattern_type', 'glob', '-i', meta.pattern]
269
+ : ['-v', 'error', '-i', input];
215
270
  const decoder = spawn(
216
271
  'ffmpeg',
217
- ['-v', 'error', '-i', input, '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
272
+ [...decodeArgs, '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
218
273
  { stdio: ['ignore', 'pipe', 'pipe'] }
219
274
  );
220
275
  let decodeErr = '';
@@ -231,7 +286,7 @@ async function main() {
231
286
  '-vf', 'scale=out_color_matrix=bt709',
232
287
  '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-color_range', 'tv',
233
288
  '-an', '-c:v', 'libx264', '-preset', values.preset || 'slow',
234
- '-crf', String(num(values.crf, 17)), '-pix_fmt', 'yuv420p',
289
+ '-crf', String(num(values.crf, 17)), '-pix_fmt', pixFmt,
235
290
  '-movflags', '+faststart', out,
236
291
  ],
237
292
  { stdio: ['pipe', 'inherit', 'inherit'] }
@@ -255,7 +310,12 @@ async function main() {
255
310
  }
256
311
  encoder.stdin.end();
257
312
  const code = await new Promise((resolve) => encoder.on('close', resolve));
258
- if (code !== 0) fail(`encoder exited with ${code}`);
313
+ if (code !== 0) {
314
+ fail(
315
+ `encoder exited with ${code}. For odd frame sizes or exact colour try ` +
316
+ `--pix-fmt yuv444p (and --crf 0 for a lossless encode).`
317
+ );
318
+ }
259
319
  if (decodeErr.trim() && !limit) fail(`decoder reported: ${decodeErr.split('\n')[0]}`);
260
320
  } finally {
261
321
  decoder.kill();
@@ -267,10 +327,14 @@ async function main() {
267
327
  }
268
328
  }
269
329
 
330
+ // One frame, decoded exactly as the video decoder decodes them: same flags,
331
+ // same pixel format, same renderer call. A photo is simply a source with one
332
+ // frame, so its output is byte-identical to frame 0 of a clip of that image.
270
333
  async function renderStill(input, at, renderer, meta) {
334
+ const seek = at > 0 ? ['-ss', String(at)] : [];
271
335
  const res = spawnSync(
272
336
  'ffmpeg',
273
- ['-v', 'error', '-ss', String(at), '-i', input, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
337
+ ['-v', 'error', ...seek, '-i', input, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgba', '-'],
274
338
  { maxBuffer: meta.width * meta.height * 4 * 2 }
275
339
  );
276
340
  if (res.status !== 0) fail('could not decode the frame for --still');