NEO(6)

okay so bestie, sit down, hydrate, and let me tell you about neo(6) — the manual page for the digital rain simulator, and honestly? it ate 🌈✨

✨ NAME ✨

neo — simulate the digital rain from "The Matrix" 🌧️💚

🦋 SYNOPSIS 🦋

neo [OPTIONS]...

💅 DESCRIPTION 💅

okay so picture this: neo recreates the digital rain effect from "The Matrix", and it's iconic fr fr. Streams of random characters will endlessly scroll down your terminal screen. There are so many differing depictions of this effect throughout the Matrix franchise, but neo attempts to closely mimic the scene from "The Matrix" where Cypher explains the code to Neo. It imitates some of the finer details such as the characters used (half-width katakana), uneven colors, color palette, glitching, and flickering. the way it pays attention to detail?? obsessed 😭

The digital rain is made of many "droplets". Each droplet scrolls vertically down a column. There can be multiple droplets in each column. Some characters on the screen are "glitched" — their values will change randomly until they are erased. The bottom of each droplet is a bit brighter than the rest. little sparkle at the bottom, periodt. ✨

You can run neo without any arguments, but it has many options to customize it to your liking. It can also respond to key presses (try pressing a number! 🔢), and it accepts a color file (see the "COLOR FILE" section below), which allows neo to display user-defined colors. neo will use Unicode characters by default if it detects a locale that supports UTF. she's multilingual, she's flexible, she's everything. 💜

---

🎀 OPTIONS 🎀

neo takes options in two forms: short and long. Short options cannot include an equal sign but long options can. Example for -S/--speed:

These will work:

-S 16
--speed 16
--speed=16

These will not:

-S=16
--S 16

bestie. read that twice. -S=16 is a no. --S 16 is a no. the vibes are off and the parser will simply not be doing that 🙈

• -a, --async — Makes each column of characters scroll at an independent speed. Each column's speed is still limited by the -S/--speed arg. All droplets in a column will always scroll at the speed. they move together, like a squad 🫶
• -b, --bold=NUM — Controls if and how neo displays bold characters. 0=off, 1=random (default), 2=all.
• -C, --colorfile=FILE — Read the colors from a file. This option is mutually exclusive with the -c/--color and --colormode=0 options. See the "COLOR FILE" section below for more info. pick one, babe, you can't have both 💅
• -c, --color=COLOR — Sets the foreground text color. This option is mutually exclusive with the -C/--colorfile and --colormode=0 options. The available colors are: green, green2, green3, yellow, orange, red, blue, cyan, gold, rainbow, purple, pink, pink2, vaporwave, and gray. rainbow and vaporwave are RIGHT THERE, just saying 🌈
• -D, --defaultbg — Use the default terminal background color. This option is mutually exclusive with the -C/--colorfile and --colormode=0 options.
• -d, --density=NUM — Controls how many droplets will appear onscreen. NUM is a decimal number. Its default value is 1.0. Values greater than 0.0 but less than 100.0 are allowed. However, values in the range [0.25, 4.0] will probably look best. the sweet spot is real 🍓
• -F, --fullwidth — Use two columns per character. This option is useful when displaying characters that take two columns to display such as Greek and full-width katakana.
• -f, --fps=NUM — Sets a frame rate target. By default, neo will run at 60Hz. neo does not attempt to query the OS for any display info. So it can't match your monitor's refresh rate by default unless it happens to be 60Hz. Lower frame rates will reduce CPU usage and improve battery life on portable devices. eco queen behavior 🔋
• -G, --glitchpct=NUM — Sets the percentage of characters onscreen that glitch. NUM is a decimal number between 0.0 and 100.0 inclusive. The default value is 10.0 (i.e. 10%).
• -g, --glitchms=NUM1,NUM2 — Controls how often the characters on screen glitch. A "glitch" refers to when a character changes into another. Each glitch is accompanied by a flickering of the character's color if colors are enabled. After each glitch, neo will wait for some time before doing the next glitch. The time it waits is chosen randomly to be between the two values provided (inclusive). NUM1 and NUM2 are positive integers that represent milliseconds. Their default values are 300 and 400.
• -h, --help — Shows the help message. when in doubt 🫶
• -l, --lingerms=NUM1,NUM2 — Controls how long characters stay onscreen after they finish scrolling. For each column, neo will pick a random value between NUM1 and NUM2 inclusive. NUM1 and NUM2 are positive integers that represent milliseconds. The default values are 1 and 3000.
• -M, --shadingmode=NUM — Controls how neo assigns color values to characters on the screen. 0=random (default), 1=gradient.
• -m, --message=STR — Displays a message in the center of the screen. The message is gradually uncovered as characters stream past it. This effect is similar to the title reveal in the movies. The message should be surrounded with double quotes. neo parses arguments using getopt_long(), which does not have Unicode support. So, unfortunately, this argument only accepts simple ASCII text. The message will not display well if you also use the -F/--fullwidth option. To unveil the message faster, the following options may help:

neo -m "the message" --speed=12 --density=3 --lingerms=1,1 --rippct=0

• -p, --profile — Turns on the profiling mode. This mode functions as normal except it times how long each frame takes and writes the values to a file called time_profile.txt in the current working directory.
• -r, --rippct=NUM — Sets the percentage of droplets that stop scrolling before reaching the bottom of the screen. NUM is a decimal number between 0.0 and 100.0 inclusive. The default value is 33.0 (i.e. about a third).
• -S, --speed=NUM — Controls how fast characters scroll down the screen. NUM is a decimal number that sets the number of characters drawn per second. The default value is 8.0. If -a/--async is used, this option sets an upper bound on the value chosen for each droplet's speed.
• -s, --screensaver — If this option is set, neo will exit on the first key press. one tap and she's gone 💀
• -V, --version — Displays the version, build date, copyright, and license.
• --chars=NUM1,NUM2 — Tells neo to display Unicode characters between NUM1 and NUM2 inclusive. NUM1 and NUM2 are Unicode code points in hexadecimal (e.g. 0x1F030). This argument can be used multiple times. If --charset is not used, neo will only use the values provided by this option. If a charset is also specified, neo will use both the charset and the characters provided by this option.
• --charset=LANG — Sets the charset that is used to draw characters onto the screen. It can be combined with the --chars option. The supported charsets are: ascii, extended, english, dec, decimal, digits, punc, bin, binary, hex, hexadecimal, katakana, greek, cyrillic, arabic, hebrew, devanagari, braille, and runic. braille and runic?? the range. the versatility. 👑
• --colormode=NUM — Sets the color mode. The accepted values are 0, 16, 32, and 256. 0 disables color (i.e. mono). 16 selects 16 colors. 32 selects 32-bit color. 256 selects 256 colors.
• --maxdpc=NUM — Sets the maximum number of droplets per column. The default value is 3.
• --noglitch — Disables character glitching. if you want her calm and stable, no chaos, this is it.
• --shortpct=NUM — Sets the percentage of shortened droplets. If a droplet is not shortened, it will extend from the top of the screen to final line, which is often the bottom of the screen but not always (see also: -r/--rippct). NUM is a decimal number between 0.0 and 100.0 inclusive. The default value is 50.0 (i.e. 50%).

---

🕹️ KEYS 🕹️

You can press keys while neo is running to control its behavior. The key bindings cannot be changed without modifying the program code. Some keys can be held to increase their effect (e.g. holding UP increases speed further). hold it down, bestie, she'll keep going 👑

Here are the available key controls:

• SPACE — clears the screen
• UP — increases the scrolling speed
• DOWN — decreases the scrolling speed
• RIGHT — increases the number of characters that are glitchy
• LEFT — decreases the number of characters that are glitchy
• TAB — toggles the shading mode between random and gradient
• ESC — exits neo
• + — increases the number of droplets onscreen
• - — decreases the number of droplets onscreen
• a — toggles asynchronous droplet speed
• p — pauses neo
• q — exits neo
• 1 — sets the color to green
• 2 — sets the color to green2
• 3 — sets the color to green3
• 4 — sets the color to gold
• 5 — sets the color to pink2
• 6 — sets the color to red
• 7 — sets the color to blue
• 8 — sets the color to cyan
• 9 — sets the color to purple
• 0 — sets the color to gray
• ! — sets the color to rainbow
• @ — sets the color to yellow
• # — sets the color to orange
• $ — sets the color to pink
• % — sets the color to vaporwave

the number keys are a whole vibe check for your terminal 💅 press one and watch her transform.

🎨 COLOR FILE 🎨

okay so neo can read a whole file that tells it what the background color is and what <em>all</em> the foreground colors are. you hand it over with the -C/--colorfile option. it's giving custom palette era 💅

you can write comments using //, #, ;, *, or @. comments can chill on their own line or tag along after the data on any line, no judgment. the first line that isn't blank and isn't a comment should be the version string, and it should look like this:

neo_color_version N

where <em>N</em> is the color file version number, which rn is 1. the version string is optional — if you skip it, neo just assumes your file follows the latest version's format. and bestie, that could potentially break old color files. ye have been warned! 😭 but fr, neo will try to maintain backwards compatability with older color file versions as long as their version is actually given.

each data line in the file describes a color. the first line is the background color. every line after that describes a foreground color. each file must contain at least two lines: one for the background and one for the foreground. typically you'll wanna put the foreground colors in order of ascending brightness. neo will <strong>not</strong> sort the colors for you, so that's on you bestie. the last color should usually be very bright (e.g. white). ✨

each data line in the file specifies one value or four values. if only one value is given, it's treated as a 16 or 256 terminal color code (e.g. 16 is black). if four values are given, the first is treated as a 16/256 color code and the other three are the RGB components of the 32-bit color. each component is a value from 0 to 1000, which closely mimics how ncurses handles color. each value is separated by a comma, and whitespace is allowed. 🫶

if more than one value is given on a line, then <strong>all four values must be given</strong>. lines do not all have to have the same number of components, i.e. some lines can just specify the 16/256 color code while others can specify all four values. mix and match, it's fine.

on most systems, if a value of -1 is provided for the 16/256 color code, this will set the color to the system default. this can be useful if you want to keep the default background. 👑

all ncurses implementations should allow you to override at least the first 256 colors, assuming your terminal supports it. some will let you override even more than that. ncurses should restore all colors back to their previous state as long as neo exits cleanly. 💖

if either of the 16 or 256 colormode options is used, all 32-bit RGB components in the color file will be parsed if they are given, but they will be unused. (parsed and then just... ignored. the audacity.)

---

Example 1: blue text on a red background using only 256 color codes

196
21

Example 2: different shades of purple text on a yellow background with some 32-bit color components

228,917,888,59
54
92
129,750,963,128

Example 3: default background and various shades of green using only 256 color codes

-1
34
40
46
82
231

---

⚡ PERFORMANCE ⚡

neo can have two main performance issues: high CPU utilization and stuttering. a terminal emulator with GPU acceleration (e.g. Alacritty) may significantly improve these issues. the CPU utilization by neo itself is fairly low, even at high frame rates on large screens. <em>however</em>, your terminal emulator may use substantial CPU resources to draw everything. without a fast terminal emulator, this application may use up a whole CPU core or three. 💀 not a drill.

sometimes the text will not scroll smoothly. again, a fast terminal emulator will probably help. you will also typically want the frame rate (i.e. --fps) to be evenly divisible by the character speed (i.e. -S/--speed). sometimes, the glitching effect will lead to stuttering because a substantial number of characters onscreen will have to be redrawn. reducing the glitchiness (i.e. --glitchpct) or disabling glitching (i.e. --noglitch) may help. 🔥

if you experience performance issues, here are some things to try:

1. Use a GPU-accelerated terminal emulator
2. Run neo on a smaller screen/window
3. Reduce the frame rate (e.g. --fps=30)
4. Reduce the number of droplets onscreen (e.g. -d 0.5)
5. Reduce the character speed (e.g. --speed=6)
6. Disabling glitching (i.e. --noglitch)
7. Disable colors (i.e. --colormode=0)
8. Disable bold characters (i.e. --bold=0)
9. Disable Unicode characters (i.e. --charset=ascii)

here's a "potato mode" config that should perform well on most systems:

neo --fps=20 -d 0.5 --speed=5 --noglitch --colormode=0 --bold=0 --charset=ascii

---

✨ EXAMPLES ✨

Example 0: just run it

neo

Example 1: sets a faster, asynchronous scrolling speed with 256 colors

neo -S 12 -a --color=green3 --colormode=256

Example 2: red text with a custom message and Cyrillic characters

neo --color=red --charset=cyrillic -m "IN SOVIET RUSSIA, COMPUTER PROGRAMS YOU!"

Example 3: displays golden Greek characters that are full-width

neo --color=gold --charset=greek -F

Example 4: uses --chars to draw Unicode dominoes

neo --chars=0x1F030,0x1F093 --fullwidth

---

👑 AUTHORS 👑

Written by Stewart Reive 💜

🐛 REPORTING BUGS 🐛

create an issue on GitHub: https://github.com/st3w/neo

©️ COPYRIGHT

Copyright © 2021 Stewart Reive

License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 🫶

💀 DISCLAIMER

this program is not affiliated with "The Matrix", Warner Bros. Entertainment Inc., Village Roadshow Pictures, Silver Pictures, nor any of their parent companies, subsidiaries, partners, or affiliates. ngl just a lil guy falling down a screen, that's all. 🙈

🌈 SEE ALSO

locale(1), localectl(1)

🦋 AFTERWORD

You get used to it. I... I don't even see the code. All I see is blonde, brunette, redhead. Hey! You uh... want a drink? :)

---

and that's the whole page bestie!! 🎀 this one's neo <strong>version 0.6.1</strong> from <strong>Feb 21 2022</strong> (it's a section 6 page, iykyk). go forth and let the glyphs rain. periodt. 💅✨🌸