1NEO(6)                          neo User Manual                         NEO(6)
2
3
4

NAME

6       neo - simulate the digital rain from "The Matrix"
7

SYNOPSIS

9       neo [OPTIONS]...
10

DESCRIPTION

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
20       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
26       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

OPTIONS

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
37              These will work:
38
39                     -S 16
40                     --speed 16
41                     --speed=16
42
43              These will not:
44
45                     -S=16
46                     --S 16
47
48       -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
53       -b, --bold=NUM
54              Controls if and how neo displays bold characters.  0=off, 1=ran‐
55              dom (default), 2=all.
56
57       -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
62       -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
69       -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
74       -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
80       -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
85       -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
92       -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
97       -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
107       -h, --help
108              Shows the help message.
109
110       -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
116       -M, --shadingmode=NUM
117              Controls  how  neo  assigns  color  values  to characters on the
118              screen.  0=random (default), 1=gradient.
119
120       -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
131                     neo   -m    "the    message"    --speed=12    --density=3
132                     --lingerms=1,1 --rippct=0
133
134       -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
140       -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
146       -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
153       -s, --screensaver
154              If this option is set, neo will exit on the first key press.
155
156       -V, --version
157              Displays the version, build date, copyright, and license.
158
159       --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
167       --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
174       --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
179       --maxdpc=NUM
180              Sets the maximum number of  droplets  per  column.  The  default
181              value is 3.
182
183       --noglitch
184              Disables character glitching.
185
186       --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

KEYS

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
199       Here are the available key controls:
200
201              ´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

COLOR FILE

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
233       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
238              neo_color_version N
239
240       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
247       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
254       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
262       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
267       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
271       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
276       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
280       Example 1: Blue text on a red background using only 256 color codes
281
282              196
283              21
284
285       Example 2: Different shades of purple text on a yellow background  with
286       some 32-bit color components
287
288              228,917,888,59
289              54
290              92
291              129,750,963,128
292
293       Example  3:  Default  background and various shades of green using only
294       256 color codes
295
296              -1
297              34
298              40
299              46
300              82
301              231
302

PERFORMANCE

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
312       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
320       If you experience performance issues, here are some things to try:
321
322              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
332       Here is a "potato mode" config that should perform well  on  most  sys‐
333       tems:
334
335              neo  --fps=20 -d 0.5 --speed=5 --noglitch --colormode=0 --bold=0
336              --charset=ascii
337

EXAMPLES

339       Example 0: Just run it
340
341              neo
342
343       Example 1: Sets a faster, asynchronous scrolling speed with 256 colors
344
345              neo -S 12 -a --color=green3 --colormode=256
346
347       Example 2: Red text with a custom message and Cyrillic characters
348
349              neo --color=red --charset=cyrillic -m "IN  SOVIET  RUSSIA,  COM‐
350              PUTER PROGRAMS YOU!"
351
352       Example 3: Displays golden Greek characters that are full-width
353
354              neo --color=gold --charset=greek -F
355
356       Example 4: Uses --chars to draw Unicode dominoes
357
358              neo --chars=0x1F030,0x1F093 --fullwidth
359

AUTHORS

361       Written by Stewart Reive
362

REPORTING BUGS

364       Create an issue on GitHub: https://github.com/st3w/neo
365
367       Copyright © 2021 Stewart Reive
368
369       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

DISCLAIMER

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

SEE ALSO

379       locale(1), localectl(1)
380

AFTERWORD

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? :)
384
385
386
387neo version 0.6.1                 Feb 21 2022                           NEO(6)
Impressum