1NEO(6) neo User Manual NEO(6)
2
6 neo - simulate the digital rain from "The Matrix"
7
9 neo [OPTIONS]...
10
12 neo recreates the digital rain effect from "The Matrix". Streams of
13 random characters will endlessly scroll down your terminal screen.
14 There are many differing depictions of this effect throughout the Ma‐
15 trix franchise. neo attempts to closely mimic the scene from "The Ma‐
16 trix" where Cypher explains the code to Neo. It imitates some of the
17 finer details such as the characters used (half-width katakana), uneven
18 colors, color palette, glitching, and flickering.
19 The digital rain is made of many "droplets". Each droplet scrolls ver‐
21 tically down a column. There can be multiple droplets in each column.
22 Some characters on the screen are "glitched" - their values will change
23 randomly until they are erased. The bottom of each droplet is a bit
24 brighter than the rest.
25 You can run neo without any arguments, but it has many options to cus‐
27 tomize it to your liking. It can also respond to key presses (try
28 pressing a number!), and it accepts a color file (see the "COLOR FILE"
29 section below), which allows neo to display user-defined colors. neo
30 will use Unicode characters by default if it detects a locale that sup‐
31 ports UTF.
32
34 neo takes options in two forms: short and long. Short options cannot
35 include an equal sign but long options can. Example for -S/--speed:
36 These will work:
38 -S 16
40 --speed 16
41 --speed=16
42 These will not:
44 -S=16
46 --S 16
47 -a, --async
49 Makes each column of characters scroll at an independent speed.
50 Each column's speed is still limited by the -S/--speed arg. All
51 droplets in a column will always scroll at the speed.
52 -b, --bold=NUM
54 Controls if and how neo displays bold characters. 0=off, 1=ran‐
55 dom (default), 2=all.
56 -C, --colorfile=FILE
58 Read the colors from a file. This option is mutually exclusive
59 with the -c/--color and --colormode=0 options. See the "COLOR
60 FILE" section below for more info.
61 -c, --color=COLOR
63 Sets the foreground text color. This option is mutually exclu‐
64 sive with the -C/--colorfile and --colormode=0 options. The
65 available colors are: green, green2, green3, yellow, orange,
66 red, blue, cyan, gold, rainbow, purple, pink, pink2, vaporwave,
67 and gray.
68 -D, --defaultbg
70 Use the default terminal background color. This option is mutu‐
71 ally exclusive with the -C/--colorfile and --colormode=0 op‐
72 tions.
73 -d, --density=NUM
75 Controls how many droplets will appear onscreen. NUM is a deci‐
76 mal number. Its default value is 1.0. Values greater than 0.0
77 but less than 100.0 are allowed. However, values in the range
78 [0.25, 4.0] will probably look best.
79 -F, --fullwidth
81 Use two columns per character. This option is useful when dis‐
82 playing characters that take two columns to display such as
83 Greek and full-width katakana.
84 -f, --fps=NUM
86 Sets a frame rate target. By default, neo will run at 60Hz. neo
87 does not attempt to query the OS for any display info. So it
88 can't match your monitor's refresh rate by default unless it
89 happens to be 60Hz. Lower frame rates will reduce CPU usage and
90 improve battery life on portable devices.
91 -G, --glitchpct=NUM
93 Sets the percentage of characters onscreen that glitch. NUM is a
94 decimal number between 0.0 and 100.0 inclusive. The default
95 value is 10.0 (i.e. 10%).
96 -g, --glitchms=NUM1,NUM2
98 Controls how often the characters on screen glitch. A "glitch"
99 refers to when a character changes into another. Each glitch is
100 accompanied by a flickering of the character's color if colors
101 are enabled. After each glitch, neo will wait for some time be‐
102 fore doing the next glitch. The time it waits is chosen randomly
103 to be between the two values provided (inclusive). NUM1 and NUM2
104 are positive integers that represent milliseconds. Their default
105 values are 300 and 400.
106 -h, --help
108 Shows the help message.
109 -l, --lingerms=NUM1,NUM2
111 Controls how long characters stay onscreen after they finish
112 scrolling. For each column, neo will pick a random value between
113 NUM1 and NUM2 inclusive. NUM1 and NUM2 are positive integers
114 that represent milliseconds. The default values are 1 and 3000.
115 -M, --shadingmode=NUM
117 Controls how neo assigns color values to characters on the
118 screen. 0=random (default), 1=gradient.
119 -m, --message=STR
121 Displays a message in the center of the screen. The message is
122 gradually uncovered as characters stream past it. This effect is
123 similar to the title reveal in the movies. The message should be
124 surrounded with double quotes. neo parses arguments using
125 getopt_long(), which does not have Unicode support. So, unfor‐
126 tunately, this argument only accepts simple ASCII text. The mes‐
127 sage will not display well if you also use the -F/--fullwidth
128 option. To unveil the message faster, the following options may
129 help:
130 neo -m "the message" --speed=12 --density=3
132 --lingerms=1,1 --rippct=0
133 -p, --profile
135 Turns on the profiling mode. This mode functions as normal ex‐
136 cept it times how long each frame takes and writes the values to
137 a file called "time_profile.txt" in the current working direc‐
138 tory.
139 -r, --rippct=NUM
141 Sets the percentage of droplets that stop scrolling before
142 reaching the bottom of the screen. NUM is a decimal number be‐
143 tween 0.0 and 100.0 inclusive. The default value is 33.0 (i.e.
144 about a third).
145 -S, --speed=NUM
147 Controls how fast characters scroll down the screen. NUM is a
148 decimal number that sets the number of characters drawn per sec‐
149 ond. The default value is 8.0. If -a/--async is used, this op‐
150 tion sets an upper bound on the value chosen for each droplet's
151 speed.
152 -s, --screensaver
154 If this option is set, neo will exit on the first key press.
155 -V, --version
157 Displays the version, build date, copyright, and license.
158 --chars=NUM1,NUM2
160 Tells neo to display Unicode characters between NUM1 and NUM2
161 inclusive. NUM1 and NUM2 are Unicode code points in hexadecimal
162 (e.g. 0x1F030). This argument can be used multiple times. If
163 --charset is not used, neo will only use the values provided by
164 this option. If a charset is also specified, neo will use both
165 the charset and the characters provided by this option.
166 --charset=LANG
168 Sets the charset that is used to draw characters onto the
169 screen. It can be combined with the --chars option. The sup‐
170 ported charsets are: ascii, extended, english, dec, decimal,
171 digits, punc, bin, binary, hex, hexadecimal, katakana, greek,
172 cyrillic, arabic, hebrew, devanagari, braille, and runic.
173 --colormode=NUM
175 Sets the color mode. The accepted values are 0, 16, 32, and 256.
176 0 disables color (i.e. mono). 16 selects 16 colors. 32 selects
177 32-bit color. 256 selects 256 colors.
178 --maxdpc=NUM
180 Sets the maximum number of droplets per column. The default
181 value is 3.
182 --noglitch
184 Disables character glitching.
185 --shortpct=NUM
187 Sets the percentage of shortened droplets. If a droplet is not
188 shortened, it will extend from the top of the screen to final
189 line, which is often the bottom of the screen but not always
190 (see also: -r/--rippct). NUM is a decimal number between 0.0
191 and 100.0 inclusive. The default value is 50.0 (i.e. 50%).
192
194 You can press keys while neo is running to control its behavior. The
195 key bindings cannot be changed without modifying the program code. Some
196 keys can be held to increase their effect (e.g. holding UP increases
197 speed further).
198 Here are the available key controls:
200 ´SPACE' - clears the screen
202 ´UP' - increases the scrolling speed
203 ´DOWN' - decreases the scrolling speed
204 ´RIGHT' - increases the number of characters that are glitchy
205 ´LEFT' - decreases the number of characters that are glitchy
206 ´TAB' - toggles the shading mode between random and gradient
207 ´ESC' - exits neo
208 ´+' - increases the number of droplets onscreen
209 ´-' - decreases the number of droplets onscreen
210 ´a' - toggles asynchronous droplet speed
211 ´p' - pauses neo
212 ´q' - exits neo
213 ´1' - sets the color to green
214 ´2' - sets the color to green2
215 ´3' - sets the color to green3
216 ´4' - sets the color to gold
217 ´5' - sets the color to pink2
218 ´6' - sets the color to red
219 ´7' - sets the color to blue
220 ´8' - sets the color to cyan
221 ´9' - sets the color to purple
222 ´0' - sets the color to gray
223 ´!' - sets the color to rainbow
224 ´@' - sets the color to yellow
225 ´#' - sets the color to orange
226 ´$' - sets the color to pink
227 ´%' - sets the color to vaporwave
228
230 neo can read a file that specifies the background color and all the
231 foreground colors. The file is given via the -C/--colorfile option.
232 You can write comments using "//", "#", ";", "*", or "@". Comments can
234 go on separate lines or after the data on any line. The first line that
235 is not blank or a comment should be the version string. The version
236 string line should look like:
237 neo_color_version N
239 where "N" is the color file version number, which is currently 1. The
241 version string is optional, and if it is omitted, then neo will assume
242 that the file adheres to the latest version's format. This could poten‐
243 tially break old color files. Ye have been warned! neo will try to
244 maintain backwards compatability with older color file versions so long
245 as their version is actually given.
246 Each data line in the file describes a color. The first line is the
248 background color. Each subsequent line describes a foreground color.
249 Each file must contain at least two lines: one for the background and
250 one for the foreground. Typically, you will want to put the foreground
251 colors in order of ascending brightness. neo will not sort the colors.
252 The last color should usually be very bright (e.g. white).
253 Each data line in the file specifies one value or four values. If only
255 one value is given, it is treated as a 16 or 256 terminal color code
256 (e.g. 16 is black). If four values are given, the first is treated as
257 a 16/256 color code and the other three are the RGB components of the
258 32-bit color. Each component is a value from 0 to 1000, which closely
259 mimics how ncurses handles color. Each value is separated by a comma,
260 and whitespace is allowed.
261 If more than one value is given on a line, then all four values must be
263 given. Lines do not all have to have the same number of components
264 i.e. some lines can just specify the 16/256 color code while others can
265 specify all four values.
266 On most systems, if a value of "-1" is provided for the 16/256 color
268 code, this will set the color to the system default. This can be useful
269 if you want to keep the default background.
270 All ncurses implementations should allow you to override at least the
272 first 256 colors, assuming your terminal supports it. Some will let you
273 override even more than that. ncurses should restore all colors back to
274 their previous state as long as neo exits cleanly.
275 If either of the 16 or 256 colormode options is used, all 32-bit RGB
277 components in the color file will be parsed if they are given, but they
278 will be unused.
279 Example 1: Blue text on a red background using only 256 color codes
281 196
283 21
284 Example 2: Different shades of purple text on a yellow background with
286 some 32-bit color components
287 228,917,888,59
289 54
290 92
291 129,750,963,128
292 Example 3: Default background and various shades of green using only
294 256 color codes
295 -1
297 34
298 40
299 46
300 82
301 231
302
304 neo can have two main performance issues: high CPU utilization and
305 stuttering. A terminal emulator with GPU acceleration (e.g. Alacritty)
306 may significantly improve these issues. The CPU utilization by neo it‐
307 self is fairly low, even at high frame rates on large screens. However,
308 your terminal emulator may use substantial CPU resources to draw every‐
309 thing. Without a fast terminal emulator, this application may use up a
310 whole CPU core or three.
311 Sometimes the text will not scroll smoothly. Again, a fast terminal em‐
313 ulator will probably help. You will also typically want the frame rate
314 (i.e. --fps) to be evenly divisible by the character speed (i.e.
315 -S/--speed). Sometimes, the glitching effect will lead to stuttering
316 because a substantial number of characters onscreen will have to be re‐
317 drawn. Reducing the glitchiness (i.e. --glitchpct) or disabling glitch‐
318 ing (i.e. --noglitch) may help.
319 If you experience performance issues, here are some things to try:
321 1. Use a GPU-accelerated terminal emulator
323 2. Run neo on a smaller screen/window
324 3. Reduce the frame rate (e.g. --fps=30)
325 4. Reduce the number of droplets onscreen (e.g. -d 0.5)
326 5. Reduce the character speed (e.g. --speed=6)
327 6. Disabling glitching (i.e. --noglitch)
328 7. Disable colors (i.e. --colormode=0)
329 8. Disable bold characters (i.e. --bold=0)
330 9. Disable Unicode characters (i.e. --charset=ascii)
331 Here is a "potato mode" config that should perform well on most sys‐
333 tems:
334 neo --fps=20 -d 0.5 --speed=5 --noglitch --colormode=0 --bold=0
336 --charset=ascii
337
339 Example 0: Just run it
340 neo
342 Example 1: Sets a faster, asynchronous scrolling speed with 256 colors
344 neo -S 12 -a --color=green3 --colormode=256
346 Example 2: Red text with a custom message and Cyrillic characters
348 neo --color=red --charset=cyrillic -m "IN SOVIET RUSSIA, COM‐
350 PUTER PROGRAMS YOU!"
351 Example 3: Displays golden Greek characters that are full-width
353 neo --color=gold --charset=greek -F
355 Example 4: Uses --chars to draw Unicode dominoes
357 neo --chars=0x1F030,0x1F093 --fullwidth
359
361 Written by Stewart Reive
362
364 Create an issue on GitHub: https://github.com/st3w/neo
365
367 Copyright © 2021 Stewart Reive
368 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/li‐
370 censes/gpl.html>. This is free software: you are free to change and
371 redistribute it. There is NO WARRANTY, to the extent permitted by law.
372
374 This program is not affiliated with "The Matrix", Warner Bros. Enter‐
375 tainment Inc., Village Roadshow Pictures, Silver Pictures, nor any of
376 their parent companies, subsidiaries, partners, or affiliates.
377
379 locale(1), localectl(1)
380
382 You get used to it. I... I don't even see the code. All I see is
383 blonde, brunette, redhead. Hey! You uh... want a drink? :)
384neo version 0.6.1 Feb 21 2022 NEO(6)