asciianything 1.2.0 → 1.2.2

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 +15 -3
  2. package/package.json +1 -1
  3. package/src/cli.js +23 -4
package/README.md CHANGED
@@ -47,8 +47,16 @@ behind Puppeteer or Playwright, or any headless capture), then point the tool at
47
47
  with `--fps`; resolution comes from the frames. The same path handles Blender renders, stop-motion stills, screen
48
48
  recordings split to frames, and anything else that can write `0001.png`.
49
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.
50
+ **Exact by construction.** A photo is one frame of the same pipeline: same decoder flags, same renderer call, same atlas
51
+ and calibration. Rendering `shot.png` and rendering frame 0 of a clip made from that image produce identical pixels —
52
+ 0 differing pixels on a 3840×2160 frame.
53
+
54
+ What differs afterwards is only the container. A photo is written as exact PNG. A video carries the encoder's error:
55
+ `--crf 0 --pix-fmt yuv444p` decodes back within ±2 levels of the rendered RGB (the rounding of the RGB→YUV→RGB matrix),
56
+ while the default `--crf 17` is a normal lossy encode.
57
+
58
+ Output size always equals input size, odd dimensions included: a 1001×667 frame encodes as 1001×667, with the encoder
59
+ switching to `yuv444p` automatically because `yuv420p` needs even dimensions.
52
60
 
53
61
  ## What it is
54
62
 
@@ -144,7 +152,8 @@ npx asciianything clip.mp4 --prose my-words.txt
144
152
  | `--diffusion-adaptive <n>` | `0.25` | extra softening for bright cells |
145
153
  | `--detail <n>` / `--color-detail <n>` | `0.14` / `0.1` | subcell luminance and colour recovery |
146
154
  | `--prose <file>` | bundled bank | `.txt` sentences or a `.json` array |
147
- | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed |
155
+ | `--crf <n>` / `--preset <p>` | `17` / `slow` | x264 quality and speed — `--crf 0` is lossless |
156
+ | `--pix-fmt <fmt>` | `yuv420p` (`yuv444p` when odd) | encoder pixel format; `yuv444p` keeps full chroma |
148
157
  | `--fps <n>` | `30` | frame rate for an image-sequence input |
149
158
  | `--still <seconds>` | — | render one PNG of a video instead of the whole file |
150
159
  | `--limit <n>` | — | stop after n frames |
@@ -217,6 +226,9 @@ Measured against the sources after encoding, in linear light, one-cell blur:
217
226
  Frame counts, durations, dimensions and colour tags are probed independently after encoding. The sunset run additionally
218
227
  holds every measured region — top sky, cirrus, cloud fan, sea band, wet sand, rocks — inside ±1.6 %.
219
228
 
229
+ Two more exactness checks: rendering a photo and rendering frame 0 of a clip of the same image gives **0 differing
230
+ pixels**, and a `--crf 0 --pix-fmt yuv444p` encode of that frame decodes back within **±2 levels** of the rendered RGB.
231
+
220
232
  ## Demos
221
233
 
222
234
  Both clips above are rendered with this package:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "asciianything",
3
- "version": "1.2.0",
3
+ "version": "1.2.2",
4
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",
package/src/cli.js CHANGED
@@ -32,7 +32,8 @@ options:
32
32
  --detail <n> subcell luminance detail recovery (default 0.14)
33
33
  --color-detail <n> subcell colour recovery (default 0.1)
34
34
  --prose <file> sentence bank (.txt or .json) instead of the bundled one
35
- --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)
36
37
  --preset <name> x264 preset (default slow)
37
38
  --fps <n> frame rate for an image-sequence input (default 30)
38
39
  --still <seconds> render one frame to PNG instead of the whole video
@@ -175,6 +176,7 @@ async function main() {
175
176
  'color-detail': { type: 'string' },
176
177
  prose: { type: 'string' },
177
178
  crf: { type: 'string' },
179
+ 'pix-fmt': { type: 'string' },
178
180
  preset: { type: 'string' },
179
181
  fps: { type: 'string' },
180
182
  still: { type: 'string' },
@@ -254,6 +256,14 @@ async function main() {
254
256
  const out = values.out || `${path.basename(input, path.extname(input))}-ascii.mp4`;
255
257
  const limit = values.limit ? Number(values.limit) : 0;
256
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
+
257
267
  const decodeArgs = isDir
258
268
  ? ['-v', 'error', '-framerate', String(seqFps), '-pattern_type', 'glob', '-i', meta.pattern]
259
269
  : ['-v', 'error', '-i', input];
@@ -276,7 +286,7 @@ async function main() {
276
286
  '-vf', 'scale=out_color_matrix=bt709',
277
287
  '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-color_range', 'tv',
278
288
  '-an', '-c:v', 'libx264', '-preset', values.preset || 'slow',
279
- '-crf', String(num(values.crf, 17)), '-pix_fmt', 'yuv420p',
289
+ '-crf', String(num(values.crf, 17)), '-pix_fmt', pixFmt,
280
290
  '-movflags', '+faststart', out,
281
291
  ],
282
292
  { stdio: ['pipe', 'inherit', 'inherit'] }
@@ -300,7 +310,12 @@ async function main() {
300
310
  }
301
311
  encoder.stdin.end();
302
312
  const code = await new Promise((resolve) => encoder.on('close', resolve));
303
- 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
+ }
304
319
  if (decodeErr.trim() && !limit) fail(`decoder reported: ${decodeErr.split('\n')[0]}`);
305
320
  } finally {
306
321
  decoder.kill();
@@ -312,10 +327,14 @@ async function main() {
312
327
  }
313
328
  }
314
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.
315
333
  async function renderStill(input, at, renderer, meta) {
334
+ const seek = at > 0 ? ['-ss', String(at)] : [];
316
335
  const res = spawnSync(
317
336
  'ffmpeg',
318
- ['-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', '-'],
319
338
  { maxBuffer: meta.width * meta.height * 4 * 2 }
320
339
  );
321
340
  if (res.status !== 0) fail('could not decode the frame for --still');