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.
- package/README.md +49 -16
- package/package.json +7 -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,
|
|
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
|
[](https://github.com/sloemo01/asciianything/stargazers)
|
|
8
8
|
[](https://github.com/sloemo01/asciianything/forks)
|
|
@@ -18,28 +18,51 @@
|
|
|
18
18
|
|
|
19
19
|
<sub><b>Night highway</b>, 19.4 s, 1920×1080 · <b>Sunset</b>, 11.6 s, 3840×2160·60</sub>
|
|
20
20
|
|
|
21
|
-
<sub>Two clips rendered by this package
|
|
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) · [**Run it**](#run-it) · [What is in here](#what-is-in-here) · [How it works](#how-it-works) · [Verification](#verification) · [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
|
|
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
|
|
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
|

|
|
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
|
|
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
|
|
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
|
|
68
|
-
|
|
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
|
-
|
|
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
|
-
| `--
|
|
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,
|
|
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
|
|
4
|
-
"description": "Turn
|
|
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
|
|
12
|
+
asciianything — turn anything with pixels into coloured lowercase prose.
|
|
13
13
|
|
|
14
14
|
usage:
|
|
15
|
-
asciianything <
|
|
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
|
|
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
|
-
[
|
|
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',
|
|
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)
|
|
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',
|
|
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');
|