matrixr 1.1.0

Animated Matrix-style terminal screensaver
Documentation
<p align="center">
  <img src="assets/icon.svg" height="128" alt="matrixr icon" />
</p>

<p align="center">
  <a href="https://github.com/WhoSowSee/matrixr/graphs/contributors"><img src="https://img.shields.io/github/contributors/WhoSowSee/matrixr?style=for-the-badge&color=CBA6F7&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTkgMTFhNCA0IDAgMSAwIDAtOCA0IDQgMCAwIDAgMCA4Wm0wIDJjLTMuOSAwLTcgMi03IDQuNVYyMGgxNHYtMi41QzE2IDE1IDEyLjkgMTMgOSAxM1ptOC41LTEuNWEzLjI1IDMuMjUgMCAxIDAgMC02LjUgMy4yNSAzLjI1IDAgMCAwIDAgNi41Wm0wIDEuOGMtLjkgMC0xLjc1LjE1LTIuNS40MiAxLjcgMS4wNSAyLjcgMi40NSAyLjcgMy45OFYyMEgyMnYtMi4zYzAtMi40LTItNC40LTQuNS00LjRaIi8+PC9zdmc+" alt="CONTRIBUTORS"></a>
  <a href="https://github.com/WhoSowSee/matrixr/forks"><img src="https://img.shields.io/github/forks/WhoSowSee/matrixr?style=for-the-badge&color=89B4FA&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTIgMTIpIHNjYWxlKDEuMDgpIHRyYW5zbGF0ZSgtMTIgLTEyKSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTYgM2EzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZabTEyIDBhMyAzIDAgMSAwIDAgNiAzIDMgMCAwIDAgMC02Wk0xMiAxNWEzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZaIi8%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTUgOGgydjIuNGMwIC4zMy4yNy42LjYuNmg4LjhjLjMzIDAgLjYtLjI3LjYtLjZWOGgydjIuNGEyLjYgMi42IDAgMCAxLTIuNiAyLjZIMTN2MmgtMnYtMkg3LjZBMi42IDIuNiAwIDAgMSA1IDEwLjRWOFoiLz48L2c%2BPC9zdmc%2B" alt="FORKS"></a>
  <a href="https://github.com/WhoSowSee/matrixr/stargazers"><img src="https://img.shields.io/github/stars/WhoSowSee/matrixr?style=for-the-badge&color=F9E2AF&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCAtMS42KSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTEyIDIuNSAxNC45IDguNGw2LjUgMWEuOC44IDAgMCAxIC40NSAxLjM2bC00LjcgNC41OCAxLjEgNi40NWEuOC44IDAgMCAxLTEuMTYuODRMMTIgMTkuOTUgNi4yIDIyLjYzYS44LjggMCAwIDEtMS4xNi0uODRsMS4xLTYuNDUtNC43LTQuNThBLjguOCAwIDAgMSAxLjkgOS40bDYuNS0xTDEyIDIuNVoiLz48L2c%2BPC9zdmc%2B" alt="STARS"></a>
</p>

<p align="center">
  <a href="https://crates.io/crates/matrixr"><img src="https://img.shields.io/crates/v/matrixr?style=for-the-badge&color=FAB387&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="CRATES.IO"></a>
  <a href="https://crates.io/crates/matrixr"><img src="https://img.shields.io/crates/d/matrixr?style=for-the-badge&color=A6E3A1&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="DOWNLOADS"></a>
</p>

<p align="center">
  <strong>English</strong> · <a href="README-RU.md">Русский</a>
</p>

<h2 align="center">Configurable matrix-style terminal rain written in Rust</h2>

<p align="center">
  <img src="assets/preview.png" width="750" alt="matrixr terminal preview" />
</p>

## Features

- Independent Matrix streams that adapt to terminal resizing
- ASCII, Japanese half-width kana, lambda, and legacy X-window character modes
- Normal and old-style scrolling, asynchronous streams, and live character mutation
- Named colors, rainbow mode, and random or all-character bold rendering
- Deep Mode with a distance-based RGB tail fade and smooth near/middle/far parallax
- Separate controls for simulation speed and render FPS
- Pause, lock, and screensaver behavior with transient status overlays
- Alternate-screen rendering, optional TTY output, and terminal state restoration
- Optional Linux console font support through <code>setfont matrix</code>

## Installation

### From crates.io

After the package is published:

```bash
cargo install matrixr
```

### With Nix (Flake)

```bash
nix run github:WhoSowSee/matrixr
nix profile install github:WhoSowSee/matrixr
```

Use `nix run` to try matrixr without installing it, or `nix profile install` to add it permanently to your Nix profile.

### From source

```bash
git clone https://github.com/WhoSowSee/matrixr.git
cd matrixr
cargo install --path .
```

Both methods install a single executable named <code>matrixr</code>.

## Quick start

```bash
matrixr
matrixr -D
matrixr -ba -u 2 -C red
matrixr -r -k
matrixr -L
```

General syntax:

```text
matrixr -[DabBcfhlsmVxk] [-u speed] [-C color] [-t tty]
```

## CLI options

| Option | Description |
| --- | --- |
| <code>-D</code> | Start in Deep Mode with an RGB depth fade and smooth parallax |
| <code>-a</code> | Use asynchronous stream updates |
| <code>-b</code> | Enable random bold characters |
| <code>-B</code> | Make all characters bold; overrides <code>-b</code> |
| <code>-n</code> | Disable bold characters; overrides <code>-b</code> and <code>-B</code> |
| <code>-c</code> | Use the Japanese half-width kana character set |
| <code>-m</code> | Enable lambda mode |
| <code>-k</code> | Mutate characters while streams move |
| <code>-o</code> | Use old-style scrolling |
| <code>-r</code> | Enable rainbow colors |
| <code>-C color</code> | Set <code>green</code>, <code>red</code>, <code>blue</code>, <code>white</code>, <code>yellow</code>, <code>cyan</code>, <code>magenta</code>, or <code>black</code> |
| <code>-u 0..10</code> | Set the initial simulation delay in 10 ms units; default <code>4</code>, <code>0</code> is unlimited |
| <code>-L</code> | Start locked; lock and unlock messages remain visible for 3 seconds |
| <code>-s</code> | Screensaver mode; exit on the first key press |
| <code>-x</code> | Enable legacy X-window character behavior |
| <code>-l</code> | Linux console mode; attempt to load the <code>matrix</code> console font |
| <code>-f</code> | Force <code>TERM=linux</code> before terminal initialization |
| <code>-t tty</code> | Render to a specific TTY device |
| <code>-h</code> | Print help |
| <code>-V</code> | Print version information |

## Runtime controls

| Key | Action |
| --- | --- |
| <code>~</code> | Toggle the centered keyboard shortcuts popup |
| <code>q</code> | Quit when not locked |
| <code>Ctrl+C</code> | Quit when not locked |
| <code>D</code> | Toggle Deep Mode without clearing existing streams |
| <code>a</code> | Toggle asynchronous updates |
| <code>b</code> / <code>B</code> / <code>n</code> | Random bold / all bold / bold off |
| <code>c</code> | Toggle the Japanese character set when not locked |
| <code>m</code> | Toggle lambda mode |
| <code>k</code> | Toggle live character mutation |
| <code>o</code> | Toggle old-style scrolling |
| <code>r</code> | Toggle rainbow mode |
| <code>x</code> | Toggle legacy X-window behavior |
| <code>p</code> or <code>P</code> | Pause or resume the simulation |
| <code>L</code> | Lock or unlock the application |
| <code>0..9</code> | Set simulation speed; <code>0</code> is unlimited |
| <code>d</code> / <code>f</code> | Decrease / increase render FPS from 1 to 120; hold to adjust continuously |

Setting changes are displayed in a top-right overlay for one second.

### Color hotkeys

| Key | Color |
| --- | --- |
| <code>!</code> | Red |
| <code>@</code> | Green |
| <code>#</code> | Yellow |
| <code>$</code> | Blue |
| <code>%</code> | Magenta |
| <code>^</code> | Cyan |
| <code>&</code> | White |
| <code>)</code> | Black |

Selecting a color disables rainbow mode.

## Development

```bash
cargo fmt -- --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release
```

<p align="center">
  <img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true" alt="Catppuccin footer" />
</p>

<p align="center">
  <i><code>&copy; 2026-present <a href="https://github.com/WhoSowSee">WhoSowSee</a></code></i>
</p>

<p align="center">
  <a href="https://github.com/WhoSowSee/matrixr/blob/main/LICENSE"><img src="https://img.shields.io/github/license/WhoSowSee/matrixr?style=for-the-badge&color=CBA6F7&logoColor=cdd6f4&labelColor=302D41" alt="LICENSE"></a>
</p>