StaticFX

Animated ASCII effects for your terminal. Think cmatrix, but with a thousand more effects, live theme switching, and a studio for making your own.

Pure Python, no dependencies, runs in any modern terminal on Linux, macOS, WSL, and even Android through Termux.

Install

You need Python 3.10 or newer (python3 --version tells you).

pipx install staticfx
staticfx

pipx installs command-line tools in their own environment so they can't clash with anything else. If you don't have it:

Then run pipx ensurepath once (or python3 -m pipx ensurepath if the pipx command isn't found yet) and open a new terminal so the staticfx command is on your PATH.

Plain pip install staticfx works too, inside a virtual environment. On Termux, if the katakana in Matrix rain show up as boxes, run staticfx --ascii, and turn the phone sideways if it says the terminal is too small. Newer Ubuntu and Debian refuse to pip-install outside one, which is another reason to use pipx. To try it without installing anything:

git clone https://github.com/ethanlabs101/StaticFX
cd StaticFX
python3 -m staticfx

The 30-second tour

Everything is remappable in Settings (o). The full guide is in docs/USAGE.md.

What's inside

There are 50 hand-written effects in seven groups. Rain: the classic, plus binary, hex and glitch versions. Particles: snow, embers, fireworks, orbits. Space: a starfield, a galaxy, a black hole, a wormhole. Waves and fields: plasma, aurora, a lava lamp, a synthwave grid. Geometry: a tumbling cube, a 4D tesseract, spirographs. Simulations: Game of Life, Langton's ant, fire, a maze that carves itself. Retro tech: boot screens, decryption, circuits, TV static.

On top of those are 992 generated effects. Each one is a recipe of layered patterns (spirals, Julia and Mandelbrot fractals, Voronoi cells, metaballs, noise), warps (kaleidoscope, swirl, tile, fold) and filters. They're seeded, so proc_042 is the same effect for everyone, forever. An automated quality check weeds out the duds, and 47 hand-picked ones live in the Gallery.

Then there are your own. The Studio remixes any generated effect or starts from scratch, with a live preview and undo, and saves small JSON files you can share.

You also get:

• 26 colour themes: originals like Matrix, Inferno and Vaporwave, takes on popular editor schemes (Dracula, Nord, Gruvbox, Catppuccin, Tokyo Night), an animated rainbow, and Strobe if you opt in (it's off by default for photosensitivity reasons)
• filters that work on anything: CRT scanlines, glitch, rainbow recolour
• looks, which save an effect with its theme, speed and filters so you can recall it with one key (a dozen come built in)

Make your own

Press n for a new effect, or highlight a generated one in the browser and press e to remix it. Arrow keys change things; s saves it to My Effects.

See docs/STUDIO.md for what every control does, and docs/EFFECT_FORMAT.md for the file format if you'd rather write recipes by hand.

Command line

staticfx -e plasma -t ocean           # start on an effect and theme
staticfx --look "Synthwave"           # start from a look
staticfx --auto 30 --duration 600     # screensaver: new effect every 30s, quit after 10 min
staticfx list fire                    # search effects
staticfx render galaxy --size 80x24   # print one frame (add --ansi for colour)
staticfx fetch                        # your fastfetch/neofetch info over a live effect
staticfx fetch --once                 # one still frame, for your .bashrc
staticfx new "Night Drive"            # create a random effect in My Effects
staticfx export my_night_drive nd.sfx # share it
staticfx doctor                       # check your setup

staticfx --help and staticfx COMMAND --help list everything.

Docs

• Usage: every key, the browser, themes, looks, settings, command line, troubleshooting
• The Studio
• Effect file format
• Writing a built-in effect in Python
• Architecture: how it fits together, and why
• Releasing: publishing a new version to PyPI

Development

git clone https://github.com/ethanlabs101/StaticFX && cd StaticFX
python3 -m pip install -e '.[dev]'
python3 -m pytest          # ~650 tests, about a minute
ruff check . && ruff format --check . && mypy

See CONTRIBUTING.md for how changes are made and checked.

License

MIT