Inline Visual Effects in the Terminal
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:
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.
Note: Windows Terminal performance is slow for some effects.
pip install terminaltexteffects
OR
pipx install terminaltexteffects
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> -- beams
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.10.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.
options:
-h, --help show this help message and exit
--input-file INPUT_FILE, -i INPUT_FILE
File to read input from (default: None)
--version, -v show program's version number and exit
--tab-width (int > 0)
Number of spaces to use for a tab character. (default: 4)
--xterm-colors Convert any colors specified in RBG hex to the closest
XTerm-256 color. (default: False)
--no-color Disable all colors in the effect. (default: False)
--wrap-text Wrap text wider than the canvas width. (default: False)
--frame-rate FRAME_RATE
Target frame rate for the animation. (default: 100)
--canvas-width WIDTH Canvas width, set to an integer > 0 to use a specific
dimension, or use 0, or -1 to set the dimension based off the
input data or the terminal device, respectively. (default:
-1)
--canvas-height WIDTH
Canvas height, set to an integer > 0 to use a specific
dimension, or use 0, or -1 to set the dimension based off the
input data or the terminal device, respectively. (default:
-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. (default: 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. (default: 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. (default: False)
Effect:
Name of the effect to apply. Use <effect> -h for effect specific help.
{beams,binarypath,blackhole,bouncyballs,bubbles,burn,canvas_test,colorshift,crumble,decrypt,dev,errorcorrect,expand,fireworks,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,spotlights,spray,swarm,synthgrid,test,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 through the
terminal 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.
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.
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.
synthgrid Create a grid which fills with characters dissolving into the
final text.
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 | python -m terminaltexteffects decrypt --typing-speed 2 --ciphertext-colors 008000 00cb00 00ff00 --final-gradient-stops eda000 --final-gradient-steps 12 --final-gradient-direction vertical
cat your_text | tte <effect> [options]
OR
cat your_text | python -m terminaltexteffects <effect> [options]
<effect> -h to view options for a specific effect, such as color or movement direction.
tte decrypt -hFor 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 effect_rain
effect = effect_rain.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 effect_rain
effect = effect_rain.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.
Any effects shown below are in development and will be available in the next release.
Visit the ChangeBlog for release write-ups.
-1 matches the input text dimension, 0 matches the terminal dimension)text_[left/right/top/bottom] and text_width/height and text_center_row/center_column.symbol attribute. Instead, the Animation class has a new attribute
current_character_visual which provides access to a symbol and color attribute reflecting the character's current
symbol and color. The prior EffectCharacter.symbol attribute was unreliable and represented both a formatted and
unformatted symbol depending on when it was accessed. In addition, the color attribute is now a Color object and the
color code has been moved into the _color_code attribute.is_fill_character: bool.Distributed under the MIT License. See LICENSE for more information.
FAQs
TerminalTextEffects (TTE) is a terminal visual effects engine.
We found that terminaltexteffects demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.