asciianything 1.1.5 → 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 +37 -15
  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.
@@ -52,7 +68,7 @@ Paste this into an agent that can run shell commands. It installs the published
52
68
  reports what it measured before rendering anything for you.
53
69
 
54
70
  ```text
55
- Install asciianything from npm, verify it, then render a video.
71
+ Install asciianything from npm, verify it, then convert a clip or a still.
56
72
 
57
73
  1. Confirm node 18+ and ffmpeg/ffprobe are on PATH. If either is missing, give
58
74
  me the install command for my platform and stop.
@@ -64,8 +80,9 @@ Install asciianything from npm, verify it, then render a video.
64
80
  step fails, say so and stop. Never describe the tool from memory.
65
81
  4. Report in this order: version, grid and glyph size, encoder flags, then three
66
82
  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.
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.
69
86
  ```
70
87
 
71
88
  ```bash
@@ -89,10 +106,13 @@ Update asciianything, then report what changed.
89
106
  ## Run it
90
107
 
91
108
  ```bash
92
- 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
93
112
  ```
94
113
 
95
- 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.
96
116
 
97
117
  ```bash
98
118
  # a specific output, larger letters
@@ -125,7 +145,8 @@ npx asciianything clip.mp4 --prose my-words.txt
125
145
  | `--detail <n>` / `--color-detail <n>` | `0.14` / `0.1` | subcell luminance and colour recovery |
126
146
  | `--prose <file>` | bundled bank | `.txt` sentences or a `.json` array |
127
147
  | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed |
128
- | `--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 |
129
150
  | `--limit <n>` | — | stop after n frames |
130
151
  | `--info` | — | print grid, cell size and measured coverage, then exit |
131
152
 
@@ -133,7 +154,7 @@ npx asciianything clip.mp4 --prose my-words.txt
133
154
 
134
155
  ```text
135
156
  asciianything/
136
- src/cli.js argument parsing, ffprobe, the decode → render → encode pipe
157
+ src/cli.js argument parsing, ffprobe, video / photo / frame-sequence input
137
158
  src/render.js sampling, weight choice, coverage division, halo, composite
138
159
  src/atlas.js Skia glyph rasterisation and measured ink coverage
139
160
  src/prose.js sentence bank → the fixed character grid
@@ -181,7 +202,8 @@ reshuffled text.
181
202
 
182
203
  **One frame in, one frame out.** The decoder is asked for raw RGBA at the source's native size, the renderer writes RGB,
183
204
  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.
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.
185
207
 
186
208
  ## Verification
187
209
 
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.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 = '';