asciianything 1.1.1 → 1.1.3

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/CREDITS.md +2 -2
  2. package/README.md +104 -12
  3. package/package.json +1 -1
package/CREDITS.md CHANGED
@@ -5,8 +5,8 @@
5
5
  **Night highway** — [Night Traffic Flow in Urban Highway View](https://www.pexels.com/video/night-traffic-flow-in-urban-highway-view-35835506/)
6
6
  by [Sururi Ballıdağ](https://www.pexels.com/@drector/) (İstanbul).
7
7
  Source file `15195617_1440_2560_30fps.mp4`, 1440 × 2560, 29.97 fps, 19.42 s.
8
- Used under the [Pexels license](https://www.pexels.com/license/). The clips in `assets/demo.mp4` and
9
- `assets/night-highway-1080p.mp4` are ASCII derivatives of it; the 1080p version is a 16:9 crop of the vertical original.
8
+ Used under the [Pexels license](https://www.pexels.com/license/). `assets/night-highway-1080p.mp4` is the
9
+ ASCII derivative of it: a 16:9 crop of the vertical original, rendered at 1920 × 1080.
10
10
 
11
11
  **Sunset** — [Stunning Beach Sunset with Vibrant Colors](https://www.pexels.com/video/stunning-beach-sunset-with-vibrant-colors-29045884/)
12
12
  by [Manoo Media](https://www.pexels.com/@manoo-media-65214113/).
package/README.md CHANGED
@@ -4,23 +4,24 @@
4
4
 
5
5
  **A video rebuilt from coloured lowercase prose. One command, every frame, at the source's own resolution and frame rate.**
6
6
 
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
+ [![Forks](https://img.shields.io/github/forks/sloemo01/asciianything?style=flat-square&color=1d1d1f&label=forks)](https://github.com/sloemo01/asciianything/forks)
9
+ [![Watchers](https://img.shields.io/github/watchers/sloemo01/asciianything?style=flat-square&color=1d1d1f&label=watchers)](https://github.com/sloemo01/asciianything/watchers)
10
+ [![License](https://img.shields.io/github/license/sloemo01/asciianything?style=flat-square&color=1d1d1f)](LICENSE)
7
11
  [![npm](https://img.shields.io/npm/v/asciianything?style=flat-square&color=1d1d1f&logo=npm&logoColor=white)](https://www.npmjs.com/package/asciianything)
8
12
  [![downloads](https://img.shields.io/npm/dm/asciianything?style=flat-square&color=1d1d1f&label=downloads)](https://www.npmjs.com/package/asciianything)
9
- [![stars](https://img.shields.io/github/stars/sloemo01/asciianything?style=flat-square&color=1d1d1f&logo=github&label=stars)](https://github.com/sloemo01/asciianything/stargazers)
10
- [![license](https://img.shields.io/github/license/sloemo01/asciianything?style=flat-square&color=1d1d1f)](LICENSE)
11
13
  [![node](https://img.shields.io/badge/node-%E2%89%A518-1d1d1f?style=flat-square)](package.json)
12
14
 
13
15
  <p>
14
- <a href="assets/night-highway-1080p.mp4"><img src="https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/night-highway-1080p.jpg" width="32%" alt="Night highway in ASCII prose, 1920x1080"></a>
15
- <a href="assets/sunset-ascii.mp4"><img src="https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/sunset.jpg" width="32%" alt="Sunset in ASCII prose, 3840x2160 at 60 fps"></a>
16
- <a href="assets/demo.mp4"><img src="https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/portrait.jpg" width="32%" alt="Night highway in ASCII prose, vertical 1440x2560"></a>
16
+ <a href="assets/night-highway-1080p.mp4"><img src="https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/night-highway-1080p.jpg" width="48%" alt="Night highway in ASCII prose, 1920x1080"></a>
17
+ <a href="assets/sunset-ascii.mp4"><img src="https://raw.githubusercontent.com/sloemo01/asciianything/main/assets/sunset.jpg" width="48%" alt="Sunset in ASCII prose, 3840x2160 at 60 fps"></a>
17
18
  </p>
18
19
 
19
- <sub><b>Night highway</b>, 19.4 s, 1920×1080 &nbsp;·&nbsp; <b>Sunset</b>, 11.6 s, 3840×2160·60 &nbsp;·&nbsp; <b>Night highway</b>, 19.4 s, 1440×2560</sub>
20
+ <sub><b>Night highway</b>, 19.4 s, 1920×1080 &nbsp;·&nbsp; <b>Sunset</b>, 11.6 s, 3840×2160·60</sub>
20
21
 
21
- <sub>Three clips rendered by this package. Click a tile for the MP4.</sub>
22
+ <sub>Two clips rendered by this package. Click a tile for the MP4.</sub>
22
23
 
23
- [**Run it**](#run-it) &nbsp;·&nbsp; [What it is](#what-it-is) &nbsp;·&nbsp; [Options](#options) &nbsp;·&nbsp; [How it works](#how-it-works) &nbsp;·&nbsp; [Verification](#verification)
24
+ [**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
25
 
25
26
  </div>
26
27
 
@@ -46,14 +47,80 @@ A small Node CLI around a deterministic renderer.
46
47
  - **Zero disk churn.** Raw frames are piped from `ffmpeg` into the renderer and straight into `libx264`; no PNG sequence
47
48
  is ever written.
48
49
 
50
+ ## Install it
51
+
52
+ Paste this into an agent that can run shell commands. It asks where the copy should live, clones the repository, installs
53
+ the dependency, renders a test frame and reports what it measured before it renders anything for you. The published
54
+ package is the same code, so the agent can work from either.
55
+
56
+ ```text
57
+ Install asciianything here, then use it to render a video.
58
+
59
+ Repo: https://github.com/sloemo01/asciianything
60
+
61
+ 1. Ask me where the folder should go before downloading anything,
62
+ and wait for my answer. Propose ~/tools/asciianything as the default.
63
+ Do not pick a path silently.
64
+ 2. Download the whole repository, not just the README:
65
+ git clone https://github.com/sloemo01/asciianything.git "<target>"
66
+ Without git:
67
+ curl -L -o asciianything.tar.gz \
68
+ https://github.com/sloemo01/asciianything/archive/main.tar.gz
69
+ tar xzf asciianything.tar.gz && mv asciianything-main "<target>"
70
+ 3. Install and prove it:
71
+ cd "<target>" && npm ci
72
+ node src/cli.js --help
73
+ node src/cli.js assets/night-highway-1080p.mp4 --still 8 \
74
+ --font-size 10 --calibration 0.76 --halo 1.2 --halo-radius 8 \
75
+ -o /tmp/proof.png
76
+ Print the commit hash (git -C "<target>" rev-parse --short HEAD), the
77
+ grid size the CLI reports, and the size of /tmp/proof.png. If npm ci,
78
+ ffmpeg, or the still fails, say so and stop. Never describe this tool
79
+ from memory.
80
+ 4. Check the machine has ffmpeg and ffprobe on PATH; if not, tell me the
81
+ install command for my platform and stop.
82
+ 5. Report back in this order: install path and commit, the grid and glyph
83
+ settings, the encoder flags, and three rules from "How it works" with
84
+ the section each came from.
85
+ 6. Then ask me for the video to convert, and for the font size. Ask once;
86
+ do not interview me. Render it, probe the output with ffprobe, and show
87
+ me the frame count, duration and resolution next to the source's.
88
+ ```
89
+
90
+ Or skip the repository entirely:
91
+
92
+ ```bash
93
+ npx asciianything night-drive.mp4 # one clip, no install
94
+ npm i -g asciianything # or keep it on PATH
95
+ ```
96
+
97
+ Node 18+ and `ffmpeg` / `ffprobe` are the only requirements.
98
+
99
+ ### Update it
100
+
101
+ ```text
102
+ Update my asciianything install, then report what changed.
103
+
104
+ 1. Ask me for the folder before touching anything, and wait.
105
+ 2. Print the current commit, then make the update reversible:
106
+ git -C "<target>" rev-parse --short HEAD
107
+ git -C "<target>" diff > my-changes.patch
108
+ cp -R "<target>" "<target>.bak"
109
+ 3. Pull the latest main:
110
+ git -C "<target>" pull --ff-only
111
+ cd "<target>" && npm ci
112
+ 4. Diff the CLI help and the README changelog before and after, and tell
113
+ me what new flags or defaults appeared. Do not re-render anything yet.
114
+ 5. If the build or a test still fails, restore "<target>.bak" and say so.
115
+ ```
116
+
49
117
  ## Run it
50
118
 
51
119
  ```bash
52
120
  npx asciianything night-drive.mp4
53
121
  ```
54
122
 
55
- That writes `night-drive-ascii.mp4` at the source's resolution, frame rate and duration. Node 18+ and `ffmpeg` /
56
- `ffprobe` on `PATH` are the only requirements.
123
+ That writes `night-drive-ascii.mp4` at the source's resolution, frame rate and duration.
57
124
 
58
125
  ```bash
59
126
  # a specific output, larger letters
@@ -90,6 +157,28 @@ npx asciianything clip.mp4 --prose my-words.txt
90
157
  | `--limit <n>` | — | stop after n frames |
91
158
  | `--info` | — | print grid, cell size and measured coverage, then exit |
92
159
 
160
+ ## What is in here
161
+
162
+ ```text
163
+ asciianything/
164
+ src/cli.js argument parsing, ffprobe, the decode → render → encode pipe
165
+ src/render.js sampling, weight choice, coverage division, halo, composite
166
+ src/atlas.js Skia glyph rasterisation and measured ink coverage
167
+ src/prose.js sentence bank → the fixed character grid
168
+ assets/
169
+ JetBrainsMono-Variable.ttf the bundled mono, weight axis 100–800
170
+ prose.json 1,844 sentences for the night-highway clips
171
+ OFL.txt the font licence
172
+ night-highway-1080p.mp4 demo, 19.4 s, 1920×1080
173
+ sunset-ascii.mp4 demo, 11.6 s, 3840×2160·60
174
+ .github/workflows/publish.yml npm publish on release, with provenance
175
+ CREDITS.md footage and typeface sourcing
176
+ LICENSE MIT
177
+ ```
178
+
179
+ `src/` is the whole tool; everything else is either a demo or a licence. There is no build step — the CLI runs from
180
+ source.
181
+
93
182
  ## How it works
94
183
 
95
184
  **A glyph inks only part of its cell, so the colour is divided by that part.** Drawing the sampled source colour into a
@@ -118,6 +207,10 @@ sand and rock are untouched. It is off by default.
118
207
  offset, and the character grid is frozen for the whole clip. Motion in the output is the source's motion, sampled — never
119
208
  reshuffled text.
120
209
 
210
+ **One frame in, one frame out.** The decoder is asked for raw RGBA at the source's native size, the renderer writes RGB,
211
+ and the encoder is told the source's frame rate and colour tags. Frame count, duration, resolution and pixel format are
212
+ probed on both files afterwards.
213
+
121
214
  ## Verification
122
215
 
123
216
  Measured against the sources after encoding, in linear light, one-cell blur:
@@ -125,7 +218,6 @@ Measured against the sources after encoding, in linear light, one-cell blur:
125
218
  | clip | grid | whole-frame luminance | settings |
126
219
  | --- | --- | --- | --- |
127
220
  | night highway · 1920×1080 | 320 × 99 (31,680) | +2.5 % | `--font-size 10 --calibration 0.76 --halo 1.2 --halo-radius 8` |
128
- | night highway · 1440×2560 | 120 × 117 (14,040) | +0.5 … +7 % | `--font-size 20`, six sampled times |
129
221
  | sunset · 3840×2160·60 | 384 × 114 (43,776) | +0.9 % | `--font-size 17 --calibration 0.8025 --halo 1.7 --halo-radius 14` |
130
222
 
131
223
  Frame counts, durations, dimensions and colour tags are probed independently after encoding. The sunset run additionally
@@ -133,7 +225,7 @@ holds every measured region — top sky, cirrus, cloud fan, sea band, wet sand,
133
225
 
134
226
  ## Demos
135
227
 
136
- The three clips above are rendered with this package:
228
+ Both clips above are rendered with this package:
137
229
 
138
230
  ```bash
139
231
  # 1920x1080, cropped from a 1440x2560 source, 582 frames at 29.97 fps
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "asciianything",
3
- "version": "1.1.1",
3
+ "version": "1.1.3",
4
4
  "description": "Turn any video into a mosaic of coloured lowercase prose, frame-accurate, with ffmpeg.",
5
5
  "keywords": [
6
6
  "ascii",