Inline Visual Effects in the Terminal
- About
- Requirements
- Installation
- Usage
- Options
- Examples
- In-Development Preview
- Recent Changes
- License
TerminalTextEffects is a collection of visual effects that run inline in the terminal. The underlying visual effect framework supports the following:
- Xterm 256 color and RBG hex color support
- Color gradients
- Runs inline, preserving terminal state and workflow
- Dynamic character movement with motion easing
- Dynamic animations with symbol and color changes and animation easing
- Effect customization through command line arguments
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
cat your_text | tte <effect> [options]
OR
cat your_text | python -m terminaltexteffects <effect> [options]
- All effects support adjustable animation speed using the
-aoption. - Use
<effect> -hto view options for a specific effect, such as color or movement direction.- Ex:
tte decrypt -h
- Ex:
options:
-h, --help show this help message and exit
--xterm-colors Convert any colors specified in RBG hex to the closest XTerm-256 color.
--no-color Disable all colors in the effect.
--tab-width TAB_WIDTH
Number of spaces to use for a tab character.
--no-wrap Disable wrapping of text.
Effect:
Name of the effect to apply. Use <effect> -h for effect specific help.
{blackhole,bouncyballs,bubbles,burn,columnslide,decrypt,errorcorrect,expand,fireworks,middleout,pour,rain,randomsequence,rowmerge,rowslide,scattered,spray,swarm,test,unstable,verticalslice,waves}
Available Effects
blackhole Characters are consumed by a black hole and explode outwards.
bouncyballs Characters are bouncy balls falling from the top of the output area.
bubbles Characters are formed into bubbles that float down and pop.
burn Burns vertically in the output area.
columnslide Slides each column into place from the outside to the middle.
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.
middleout Text expands in a single row or column in the middle of the output area then
out.
pour Pours the characters into position from the given direction.
rain Rain characters from the top of the output area.
randomsequence Prints the input data in a random sequence.
rowmerge Merges rows of characters.
rowslide Slides each row into place.
scattered Move the characters into place from random starting locations.
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.
test effect_description
unstable Spawn characters jumbled, explode them to the edge of the output area, then
reassemble them in the correct layout.
verticalslice Slices the input in half vertically and slides it into place from opposite
directions.
waves Waves travel across the terminal leaving behind the characters.
Ex: ls -a | python -m terminaltexteffects --xterm-colors decrypt -a 0.002 --ciphertext-color 00ff00
--plaintext-color ff0000 --final-color 0000ff
Any effects shown below are in development and will be available in the next release.
- Waves effect. A wave animation is played over the characters. Wave colors and final colors are configurable.
- Blackhole effect. Characters spawn scattered as a field of stars. A blackhole forms and consumes the stars then explodes the characters across the screen. Characters then 'cool' and ease into position.
- Swarm effect. Characters a separated into swarms and fly around the output area before landing in position.
- Animations support easing functions. Easing functions are applied to Scenes using Scene.ease = easing_function.
- OutputArea has a center attribute that is the center Coord of the output area.
- Terminal has a random_coord() method which returns a random coordinate. Can specify outside the output area.
- Animation and Motion have been refactored to use direct Scene and Waypoint object references instead of string IDs.
- base_character.EventHandler uses Scene and Waypoint objects instead of string IDs.
- graphics.GraphicalEffect renamed to CharacterVisual
- graphics.Sequence renamed to Frame
- Animation methods for created Scenes and adding frames to scenes have been refactored to return Scene objects and expose terminal modes, respectively.
- Easing function api has been simplified. Easing function callables are used directly rather than Enums and function maps.
- Layer is set on the EffectCharacter object instead of the motion object. The layer is modified through the EventHandler to allow finer control over the layer.
- Animations not longer sync to specific waypoints, rather, they sync to the progress of the character towards the active waypoint.
- Animations synced to waypoint progress can now sync to either the distance progression or the step progression.
- Motion methods which utilize coordinates now use Coord objects rather than tuples.
- Motion has methods for finding coordinates on a circle and in a circle.
- Fixed Gradient creating two more steps than specified.
- Fixed waypoint synced animation index out of range error.
Distributed under the MIT License. See LICENSE for more information.