pycmatrix

Python port of cmatrix — the classic "Matrix" digital-rain terminal animation.

Starting as a 1:1 restoration of the C code, and growing into a configurable pure-Python implementation.

---

Features

• Full replica of cmatrix's two scrolling modes (new-style / old-style -o)
• All original CLI options: color, bold, rainbow, λ, async, pause, lock, message overlay, ...
• New: press c to toggle between dark mode and light mode
  • dark: terminal-default (or black) background + bright characters
  • light: white background + dark characters, head highlight auto-inverted

---

Project layout

pycmatrix/
├── pycmatrix.py             # Main program, single-file Python implementation
├── requirements.txt         # Dependencies (windows-curses on Windows only)
└── README.md

Source file sections

pycmatrix.py is organized in the same order as the C source:

Section	Corresponding C code	Description
Cell dataclass	typedef struct cmatrix	Cell with val + is_head
class G	Global variables	matrix / length / spaces / updates / stdscr, etc.
c_die / finish / usage / version	Same-named functions	Error exit, clean exit, help, version
sighandler / install_signal_handlers	sighandler	Signal handling (POSIX-only SIGWINCH/SIGTSTP/SIGQUIT skipped automatically)
var_init	var_init()	Allocate the (LINES+1) × COLS matrix and initialize even columns
resize_screen	resize_screen()	Rebuild the matrix after a terminal resize
parse_args	getopt(...) block	Short options restored with argparse
run	main() loop	signals → keys → column updates → render → message → napms
pair_attr / apply_bkgd	(new) light/dark color switch	Two sets of color pairs pre-allocated, flicker-free toggle

Features skipped vs. the original

The following do not apply on Python / Windows; the options are kept but will either warn or be ignored:

• -t tty: Python curses does not expose newterm; passing it exits with an error
• consolechars / setfont: Linux console font switching
• TIOCSTI: keystroke injection in screensaver mode (Linux-only)

---

Install & run

Requires Python 3.13 (or a compatible version). uv is recommended for managing the virtual environment.

# 1. Create and activate the virtual environment
uv venv --python 3.13
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 2. Install dependencies
uv pip install -r requirements.txt

# 3. Run
python pycmatrix.py

Windows terminals need windows-curses; on POSIX platforms curses is in the standard library. requirements.txt isolates the Windows dependency with a sys_platform marker.

---

Command-line options

python pycmatrix.py -[abBcfhlsmVxk] [-u delay] [-C color] [-M message]

Option	Meaning
-a	Asynchronous scroll
-b / -B / -n	Bold: normal / all-bold / off
-c	Classic half-width kana character set
-f	Force TERM=linux
-l	Linux console mode (only affects the character range in this Python port)
-L	Lock mode (cannot exit from this terminal; default message "Computer locked.")
-o	Old-style scrolling
-s	Screensaver: exit on any keystroke
-x	X window character range
-r	Rainbow mode
-m	λ (lambda) mode
-k	Characters mutate while scrolling
-u N	Update delay (0–10, default 4, ~10 ms per step)
-C COLOR	Color: green/red/blue/white/yellow/cyan/magenta/black
-M TEXT	Display message centered on screen (overrides -L default)
-h / -V	Help / version

Runtime keys

Key	Action
q	Quit (disabled in lock mode)
p / P	Pause / resume
c	Toggle dark / light mode
a	Toggle async scroll
b / B / n	Bold: normal / all-bold / off
L	Enable lock mode
r	Enable rainbow mode
m	Toggle λ mode
0–9	Set update-delay level directly
! @ # $ % ^ &	Quick-switch to red / green / yellow / blue / magenta / cyan / white

---

License

The original cmatrix is licensed under GPL-3.0. This Python port, as a derivative work, follows the same license.