Inline Visual Effects in the Terminal
- About
- Requirements
- Installation
- Usage (Application)
- Usage (Library)
- Effect Showcase
- In-Development Preview
- Latest Release Notes
- License
TerminalTextEffects (TTE) is a terminal visual effects engine. TTE can be installed as a system application to produce effects in your terminal, or as a Python library to enable effects within your Python scripts/applications. TTE includes a growing library of built-in effects which showcase the engine's features. These features include:
- Xterm 256 / RGB hex color support
- Complex character movement via Paths, Waypoints, and motion easing, with support for bezier curves.
- Complex animations via Scenes with symbol/color changes, layers, easing, and Path synced progression.
- Variable stop/step color gradient generation.
- Event handling for Path/Scene state changes with custom callback support and many pre-defined actions.
- Effect customization exposed through a typed effect configuration dataclass that is automatically handled as CLI arguments.
- Runs inline, preserving terminal state and workflow.
TerminalTextEffects is written in Python and does not require any 3rd party modules. Terminal interactions use standard ANSI terminal sequences and should work in most modern terminals.
UV Install
Tool Run
uv tool run terminaltexteffects -h
Application Install
uv tool install terminaltexteffects
Library Install
uv install terminaltexteffects
Pip Install
Application Install
pipx install terminaltexteffects
Library Install
pip install terminaltexteffects
Nix (flakes)
Add it as an input to a flake:
inputs = {
terminaltexteffects.url = "github:ChrisBuilds/terminaltexteffects/<optional-ref>"
}Create a shell with it:
nix shell github:ChrisBuilds/terminaltexteffects/<optional-ref>Or run it directly:
echo 'terminaltexteffects is awesome' | nix run github:ChrisBuilds/terminaltexteffects/<optional-ref> -- beamsNix (classic)
Fetch the source and add it to, e.g. your shell:
let
pkgs = import <nixpkgs> {};
tte = pkgs.callPackage (pkgs.fetchFromGitHub {
owner = "ChrisBuilds";
repo = "terminaltexteffects";
rev = "<revision, e.g. main/v0.13.0/etc.>";
hash = ""; # Build first, put proper hash in place
}) {};
in
pkgs.mkShell {
packages = [tte];
}View the Documentation for a full installation and usage guide.
TTE Command Line Options
options:
-h, --help show this help message and exit
--input-file, -i INPUT_FILE
File to read input from
--version, -v show program's version number and exit
--random-effect, -R Randomly select an effect to apply
--include-effects INCLUDE_EFFECTS [INCLUDE_EFFECTS ...]
Space-separated list of Effects to include when randomly selecting an effect
--exclude-effects EXCLUDE_EFFECTS [EXCLUDE_EFFECTS ...]
Space-separated list of Effects to exclude when randomly selecting an effect
--tab-width (int > 0)
Number of spaces to use for a tab character.
--xterm-colors Convert any colors specified in 24-bit RBG hex to the closest 8-bit XTerm-256 color.
--no-color Disable all colors in the effect.
--terminal-background-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
The background color of you terminal. Used to determine the appropriate color for fade-in/out within effects.
--existing-color-handling {always,dynamic,ignore}
Specify handling of existing 8-bit and 24-bit ANSI color sequences in the input data. 3-bit and 4-bit sequences are not supported. 'always' will always use the
input colors, ignoring any effect specific colors. 'dynamic' will leave it to the effect implementation to apply input colors. 'ignore' will ignore the colors in
the input data. Default is 'ignore'.
--wrap-text Wrap text wider than the canvas width.
--frame-rate FRAME_RATE
Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting. Defaults to 60.
--canvas-width int >= -1
Canvas width, set to an integer > 0 to use a specific dimension, use 0 to match the terminal width, or use -1 to match the input text width. Defaults to -1.
--canvas-height int >= -1
Canvas height, set to an integer > 0 to use a specific dimension, use 0 to match the terminal height, or use -1 to match the input text height. Defaults to -1.
--anchor-canvas {sw,s,se,e,ne,n,nw,w,c}
Anchor point for the canvas. The canvas will be anchored in the terminal to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.
--anchor-text {n,ne,e,se,s,sw,w,nw,c}
Anchor point for the text within the Canvas. Input text will anchored in the Canvas to the location corresponding to the cardinal/diagonal direction. Defaults to
'sw'.
--ignore-terminal-dimensions
Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. Useful for sending frames to another output handler.
--reuse-canvas Do not create new rows at the start of the effect. The cursor will be moved up the number of rows present in the input text in an attempt to re-use the canvas.
This option works best when used in a shell script. If used interactively with prompts between runs, the result is unpredictable.
--no-eol Suppress the trailing newline emitted when an effect animation completes.
--no-restore-cursor Do not restore cursor visibility after the effect.
Effect:
Name of the effect to apply. Use <effect> -h for effect specific help.
{beams,binarypath,blackhole,bouncyballs,bubbles,burn,colorshift,crumble,decrypt,errorcorrect,expand,fireworks,highlight,laseretch,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,smoke,spotlights,spray,swarm,sweep,synthgrid,thunderstorm,unstable,vhstape,waves,wipe}
Available Effects
beams Create beams which travel over the canvas illuminating the characters behind them.
binarypath Binary representations of each character move towards the home coordinate of the character.
blackhole Characters are consumed by a black hole and explode outwards.
bouncyballs Characters are bouncy balls falling from the top of the canvas.
bubbles Characters are formed into bubbles that float down and pop.
burn Burns vertically in the canvas.
colorshift Display a gradient that shifts colors across the terminal.
crumble Characters lose color and crumble into dust, vacuumed up, and reformed.
decrypt Display a movie style decryption effect.
errorcorrect Some characters start in the wrong position and are corrected in sequence.
expand Expands the text from a single point.
fireworks Characters launch and explode like fireworks and fall into place.
highlight Run a specular highlight across the text.
laseretch A laser etches characters onto the terminal.
matrix Matrix digital rain effect.
middleout Text expands in a single row or column in the middle of the canvas then out.
orbittingvolley Four launchers orbit the canvas firing volleys of characters inward to build the input text from the center out.
overflow Input text overflows and scrolls the terminal in a random order until eventually appearing ordered.
pour Pours the characters into position from the given direction.
print Lines are printed one at a time following a print head. Print head performs line feed, carriage return.
rain Rain characters from the top of the canvas.
randomsequence Prints the input data in a random sequence.
rings Characters are dispersed and form into spinning rings.
scattered Text is scattered across the canvas and moves into position.
slice Slices the input in half and slides it into place from opposite directions.
slide Slide characters into view from outside the terminal.
smoke Smoke floods the canvas colorizing any characters it crosses.
spotlights Spotlights search the text area, illuminating characters, before converging in the center and expanding.
spray Draws the characters spawning at varying rates from a single point.
swarm Characters are grouped into swarms and move around the terminal before settling into position.
sweep Sweep across the canvas to reveal uncolored text, reverse sweep to color the text.
synthgrid Create a grid which fills with characters dissolving into the final text.
thunderstorm Create a thunderstorm in the terminal.
unstable Spawn characters jumbled, explode them to the edge of the canvas, then reassemble them in the correct layout.
vhstape Lines of characters glitch left and right and lose detail like an old VHS tape.
waves Waves travel across the terminal leaving behind the characters.
wipe Wipes the text across the terminal to reveal characters.
Ex: ls -a | tte decrypt --typing-speed 2 --ciphertext-colors 008000 00cb00 00ff00 --final-gradient-stops eda000 --final-gradient-steps 12 --final-gradient-direction verticalcat your_text | tte <effect> [options]
OR
cat your_text | python -m terminaltexteffects <effect> [options]
- Use
<effect> -hto view options for a specific effect, such as color or movement direction.- Ex:
tte decrypt -h
- Ex:
For more information, view the Application Usage Guide.
All effects are iterators which return a string representing the current frame. Basic usage is as simple as importing the effect, instantiating it with the input text, and iterating over the effect.
from terminaltexteffects.effects import Rain
effect = Rain("your text here")
for frame in effect:
# do something with the string
...In the event you want to allow TTE to handle the terminal setup/teardown, cursor positioning, and animation frame rate, a terminal_output() context manager is available.
from terminaltexteffects.effects import Rain
effect = Rain("your text here")
with effect.terminal_output() as terminal:
for frame in effect:
terminal.print(frame)For more information, view the Library Usage Guide.
Note: Below you'll find a subset of the built-in effects.
View all of the effects and related information in the Effects Showroom.
Visit the ChangeBlog for release write-ups.
random_effectis now specified as--random-effectand supports--include-effectsor--exclude-effectsfor limiting which effects are available.
- Added
EasingTracker, a reusable helper that tracks eased progress, deltas, and completion state for any easing function. - Replaced
eased_step_functionclosure with the newSequenceEaser, enabling eased iteration over arbitrary sequences while reporting added, removed, and total elements for each step. - Renamed
CharacterGroupcenter related groupings toCENTER_TO_OUTSIDE/OUTSIDE_TO_CENTER. CharacterGroup,CharacterSort, andColorSortthemselves were relocated from theTerminalmodule intoterminaltexteffects.utils.argutils, and the terminal now imports them from there so both the CLI and the engine share a single definition of the enums.terminaltexteffects.utils.argutilsintroduces dedicated argument-type helpers forCharacterGroup,CharacterSort, andColorSort.Canvasnow exposes atext_centerCoordcomputed fromtext_center_row/text_center_column, eliminating redundant per-call calculations when effects or sort helpers need the true center of the anchored text.- Center-to-outside/Outside-to-center
CharacterGroupcalculations withinTerminalnow measure distance from the text center instead of the canvas center, so middle-out and outside-in sorts stay aligned with the rendered text even when it is offset on the canvas.
- Highlight - Simplified effect logic by offloading to
SequenceEaser. - Sweep - Simplified effect logic by offloading to
SequenceEaser. - Wipe - Simplified effect logic by offloading to
SequenceEaser. - Wipe - Changed default
--wipe-easetoIN_OUT_CIRC. - Wipe - Removed
--wipe-ease-stepsizeCLI arg. - Colorshift -
--travelrenamed--no-travel. The default behavior is to travel radially. - Colorshift - Default
--travel-directionchanged from horizontal to radial.
- Sweep - Fixed bug when second sweep direction is a grouping of a different length from the first direction.
- Removed mistakenly added effect dev_worm.
- CLI now exits with a non-zero status when input files are missing, no input is provided, or no effect is specified.
- CLI detects duplicate effect command registrations.
Distributed under the MIT License. See LICENSE for more information.







