terminaltexteffects

Terminal Text Effects

Inline Visual Effects in the Terminal

PyPI - Python Version License

About
Requirements
Installation
Usage
Options
Examples
In-Development Preview
Latest Release Notes
License

TTE

synthgrid_demo

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

Requirements

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.

Installation

pip install terminaltexteffects OR pipx install terminaltexteffects

Usage

cat your_text | tte <effect> [options]

cat your_text | python -m terminaltexteffects <effect> [options]

Use <effect> -h to view options for a specific effect, such as color or movement direction.
- Ex: tte decrypt -h

Options

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.

  {binarypath,blackhole,bouncyballs,bubbles,burn,crumble,decrypt,errorcorrect,expand,fireworks,middleout,pour,print,rain,randomsequence,rings,scattered,slide,spray,swarm,synthgrid,test,unstable,verticalslice,vhstape,waves,wipe}
                        Available Effects
    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 output area.
    bubbles             Characters are formed into bubbles that float down and pop.
    burn                Burns vertically in the output area.
    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.
    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.
    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 output area.
    randomsequence      Prints the input data in a random sequence.
    rings               Characters are dispersed and form into spinning rings.
    scattered           Move the characters into place from random starting locations.
    slide               Slide characters into view from outside the terminal.
    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 output area, then reassemble them in the correct layout.
    verticalslice       Slices the input in half vertically and slides it into place from opposite directions.
    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 --xterm-colors decrypt -a 0.002 --ciphertext-color 00ff00 --plaintext-color ff0000 --final-color 0000ff

Examples

Note: All effects support extensive customization via effect specific arguments. The examples shown below only represent the default settings for a given effect.

Fireworks

fireworks_demo

tte fireworks -h

fireworks | Characters explode like fireworks and fall into place.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Minimum time, in seconds, between animation steps. This value does not normally need to be modified. Use this to increase the playback speed of all aspects of the effect. This will have
                        no impact beyond a certain lower threshold due to the processing speed of your device. (default: 0.01)
  --explode-anywhere    If set, fireworks explode anywhere in the output area. Otherwise, fireworks explode above highest settled row of text. (default: False)
  --firework-colors [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
                        Space separated list of colors from which firework colors will be randomly selected. (default: ['88F7E2', '44D492', 'F5EB67', 'FFA15C', 'FA233E'])
  --firework-symbol (single character)
                        Symbol to use for the firework shell. (default: o)
  --firework-volume (float 0 < n <= 1)
                        Percent of total characters in each firework shell. (default: 0.02)
  --final-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the final character. (default: ffffff)
  --launch-delay (int >= 0)
                        Number of animation steps to wait between launching each firework shell. (default: 60)
  --explode-distance (float 0 < n <= 1)
                        Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total output area width. (default: 0.1)

        
Example: terminaltexteffects fireworks -a 0.01 --firework-colors 88F7E2 44D492 F5EB67 FFA15C FA233E --firework-symbol o --firework-volume 2 --final-color ffffff --launch-delay 60 --explode-distance 10

Rain

rain_demo

tte rain -h

rain | Rain characters from the top of the output area.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Minimum time, in seconds, between animation steps. This value does not normally need to be modified. Use this to increase the playback speed of all aspects of the effect. This will have
                        no impact beyond a certain lower threshold due to the processing speed of your device. (default: 0.01)
  --rain-colors [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
                        List of colors for the rain drops. Colors are randomly chosen from the list. (default: 0)
  --final-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the final character. (default: ffffff)
  --movement-speed (float > 0)
                        Falling speed of the rain drops. (default: 0.15)
  --easing EASING       Easing function to use for character movement. (default: IN_QUART)

    Easing
    ------
    Note: A prefix must be added to the function name.
    
    All easing functions support the following prefixes:
        IN_  - Ease in
        OUT_ - Ease out
        IN_OUT_ - Ease in and out
        
    Easing Functions
    ----------------
    SINE   - Sine easing
    QUAD   - Quadratic easing
    CUBIC  - Cubic easing
    QUART  - Quartic easing
    QUINT  - Quintic easing
    EXPO   - Exponential easing
    CIRC   - Circular easing
    BACK   - Back easing
    ELASTIC - Elastic easing
    BOUNCE - Bounce easing
    
    Visit: https://easings.net/ for visualizations of the easing functions.

        
Example: terminaltexteffects rain -a 0.01 --rain-colors 39 45 51 21

Decrypt

decrypt_demo

tte decrypt -h

decrypt | Movie style decryption effect.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Time to sleep between animation steps. Defaults to 0.003 seconds.
  --ciphertext-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the ciphertext. Defaults to 40
  --plaintext-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the plaintext. Defaults to 208.

Example: terminaltexteffects decrypt -a 0.003 --cipher-text-color 40 --plain-text-color 208

Spray

spray_demo

tte spray -h

spray | Draws the characters spawning at varying rates from a single point.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Minimum time, in seconds, between animation steps. This value does not normally need to be modified. Use this to increase the playback speed of all aspects of the effect. This will have
                        no impact beyond a certain lower threshold due to the processing speed of your device. (default: 0.01)
  --spray-colors [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
                        List of colors for the character spray. Colors are randomly chosen from the list. (default: 0)
  --final-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the final character. (default: ffffff)
  --spray-position {n,ne,e,se,s,sw,w,nw,center}
                        Position for the spray origin. (default: e)
  --spray-volume (int > 0)
                        Maximum number of characters to spray at a time. (default: 5)
  --movement-speed (float > 0)
                        Movement speed of the characters. Note: Speed effects the number of steps in the easing function. Adjust speed and animation rate separately to fine tune the effect. (default: 0.7)
  --easing EASING       Easing function to use for character movement. (default: OUT_EXPO)

    Easing
    ------
    Note: A prefix must be added to the function name.
    
    All easing functions support the following prefixes:
        IN_  - Ease in
        OUT_ - Ease out
        IN_OUT_ - Ease in and out
        
    Easing Functions
    ----------------
    SINE   - Sine easing
    QUAD   - Quadratic easing
    CUBIC  - Cubic easing
    QUART  - Quartic easing
    QUINT  - Quintic easing
    EXPO   - Exponential easing
    CIRC   - Circular easing
    BACK   - Back easing
    ELASTIC - Elastic easing
    BOUNCE - Bounce easing
    
    Visit: https://easings.net/ for visualizations of the easing functions.

        
Example: terminaltexteffects spray -a 0.01 --spray-position center --spray-volume 5 --movement-speed 0.7 --easing OUT_EXPO --spray-colors 10 11 12 --final-color 0

Scattered

scattered_demo

tte scattered -h

scattered | Move the characters into place from random starting locations.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Time between animation steps. (default: 0.01)
  --movement-speed (float > 0)
                        Movement speed of the characters. Note: Speed effects the number of steps in the easing function. Adjust speed and animation rate separately to fine tune the effect. (default: 0.5)
  --easing EASING       Easing function to use for character movement. (default: IN_OUT_BACK)

    Easing
    ------
    Note: A prefix must be added to the function name.
    
    All easing functions support the following prefixes:
        IN_  - Ease in
        OUT_ - Ease out
        IN_OUT_ - Ease in and out
        
    Easing Functions
    ----------------
    SINE   - Sine easing
    QUAD   - Quadratic easing
    CUBIC  - Cubic easing
    QUART  - Quartic easing
    QUINT  - Quintic easing
    EXPO   - Exponential easing
    CIRC   - Circular easing
    BACK   - Back easing
    ELASTIC - Elastic easing
    BOUNCE - Bounce easing
    
    Visit: https://easings.net/ for visualizations of the easing functions.

        
Example: terminaltexteffects scattered --movement-speed 0.5 --easing IN_OUT_BACK

Expand

expand_demo

tte expand -h

expand | Expands the text from a single point.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Minimum time, in seconds, between animation steps. This value does not normally need to be modified. Use this to increase the playback speed of all aspects of the effect. This will have
                        no impact beyond a certain lower threshold due to the processing speed of your device. (default: 0.01)
  --movement-speed (float > 0)
                        Movement speed of the characters. Note: Speed effects the number of steps in the easing function. Adjust speed and animation rate separately to fine tune the effect. (default: 0.5)
  --easing EASING       Easing function to use for character movement. (default: IN_OUT_QUART)

    Easing
    ------
    Note: A prefix must be added to the function name.
    
    All easing functions support the following prefixes:
        IN_  - Ease in
        OUT_ - Ease out
        IN_OUT_ - Ease in and out
        
    Easing Functions
    ----------------
    SINE   - Sine easing
    QUAD   - Quadratic easing
    CUBIC  - Cubic easing
    QUART  - Quartic easing
    QUINT  - Quintic easing
    EXPO   - Exponential easing
    CIRC   - Circular easing
    BACK   - Back easing
    ELASTIC - Elastic easing
    BOUNCE - Bounce easing
    
    Visit: https://easings.net/ for visualizations of the easing functions.

        
Example: terminaltexteffects expand -a 0.01 --movement-speed 0.5 --easing IN_OUT_QUART

Burn

burn_demo

tte burn -h

burn | Burn the output area.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Time between animation steps. Defaults to 0.03 seconds.
  --burned-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color faded toward as blocks burn. Defaults to 252525
  --flame-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the flame. Defaults to 0
  --final-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
                        Color for the final character. Will leave as system default if not provided.

Example: terminaltexteffects burn -a 0.003 --flame-color ff9600 --burned-color 252525

Pour

pour_demo

tte pour -h

pour | Pours the characters into position from the given direction.

options:
  -h, --help            show this help message and exit
  -a ANIMATION_RATE, --animation-rate ANIMATION_RATE
                        Minimum time, in seconds, between animation steps. This value does not normally need to be modified. Use this to increase the playback speed of all aspects of the effect. This will have
                        no impact beyond a certain lower threshold due to the processing speed of your device. (default: 0.004)
  --pour-direction {up,down,left,right}
                        Direction the text will pour. (default: down)
  --movement-speed (float > 0)
                        Movement speed of the characters. Note: Speed effects the number of steps in the easing function. Adjust speed and animation rate separately to fine tune the effect. (default: 0.2)
  --easing EASING       Easing function to use for character movement. (default: IN_QUAD)

    Easing
    ------
    Note: A prefix must be added to the function name.
    
    All easing functions support the following prefixes:
        IN_  - Ease in
        OUT_ - Ease out
        IN_OUT_ - Ease in and out
        
    Easing Functions
    ----------------
    SINE   - Sine easing
    QUAD   - Quadratic easing
    CUBIC  - Cubic easing
    QUART  - Quartic easing
    QUINT  - Quintic easing
    EXPO   - Exponential easing
    CIRC   - Circular easing
    BACK   - Back easing
    ELASTIC - Elastic easing
    BOUNCE - Bounce easing
    
    Visit: https://easings.net/ for visualizations of the easing functions.

        
Example: terminaltexteffects pour -a 0.004 --pour-direction down

Randomsequence

randomsequence_demo

Verticalslice

verticalslice_demo

Unstable

unstable_demo

Bubbles

bubbles_demo

Bouncyballs

bouncyballs_demo

Middleout

middleout_demo

Errorcorrect

errorcorrect_demo

Waves

waves_demo

Blackhole

blackhole_demo

Swarm

swarm_demo

Crumble

crumble_demo

Rings

rings_demo

VHStape

vhstape_demo

Print

print_demo

BinaryPath

binarypath_demo

Slide

slide_demo

Wipe

wipe_demo

SynthGrid

synthgrid_demo

In-Development Preview

Any effects shown below are in development and will be available in the next release.

Latest Release Notes

0.6.0

New Features

Effects

Print. Lines are printed one at a time following a print head. Print head performs line feed, carriage return.
BinaryPath. Characters are converted into their binary representation. These binary groups travel to their input coordinate and collapse into the original character symbol.
Wipe. Performs directional wipes with an optional trailing gradient.
Slide. Slides characters into position from outside the terminal view. Characters can be grouped by column, row, or diagonal. Groups can be merged from opposite directions or slide from the same direction.
SynthGrid. Creates a gradient colored grid in which blocks of characters dissolve into the input text.

Engine

Terminal.get_character() method accepts a Terminal.CharacterSort argument to easily retrieve the input characters in groups sorted by various directions, ex: Terminal.CharacterSort.COLUMN_LEFT_TO_RIGHT
Terminal.add_character() method allows adding characters to the effect that are not part of the input text. These characters are added to a separate list (Terminal.non_input_characters) in terminal to allow for iteration over Terminal.characters and adding new characters based on the input characters without modifying the Terminal.characters list during iteration. The added characters are handled the same as input characters by the Terminal.
New EventHandler Action, Callback. The Action target can be any callable and will pass the character as the first argument, followed by any additional arguments provided. Uses new EventHandler.Callback type with signature EventHandler.Callback(typing.Callable, *args)
graphics.Gradient() objects specified with a single color will create a list of the single color with length steps. This enables gradients to be specified via command line arguments while supporting an arbitrary number of colors > 0, without needing to perform any checking in the effect logic.

Changes

Effects

Rowslide, Columnslide, and Rowmerge have been replaced with a single effect, Slide.
Many classic effects now support gradient specification which includes stops, steps, and frames to enable greater customization.
Randomsequence effect supports gradient specification.
Scattered effect supports gradient specification.
Expand effect supports gradient specification.
Pour effect now has a back and forth pouring animation and supports gradient specification.

Engine

Terminal._update_terminal_state() refactored for improved performance.
EffectCharacter.tick() will progress motion and animation by one step. This solves the problem of running Animation.step_animation() before Motion.move() and desyncing Path synced animations.
EffectCharacter.is_active has been renamed to EffectCharacter.is_visible.
EffectCharacter.is_active() can be used to check if motion/animation is in progress.
graphics.Animation.new_scene(), motion.Motion.new_path(), and Path.new_waypoint() all support automatic IDs. If no ID is provided a unique ID is automatically generated.

Bug Fixes

Fixed rare division by zero error in Path.step() when the final segment has a distance of zero and the distance to travel exceeds the total distance of the Path.
Fixed effects not respecting --no-color argument.

License

Distributed under the MIT License. See LICENSE for more information.

Metadata

Release files for terminaltexteffects 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for terminaltexteffects 0.6.0
File	Size	Uploaded
terminaltexteffects-0.6.0.tar.gz	67.7 kB	Feb 10, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for terminaltexteffects 0.6.0
File	Interpreter	ABI	Platform	Reset
terminaltexteffects-0.6.0-py3-none-any.whl 98.2 kB Feb 10, 2024	Python 3	none	any	Details

Total release size: 165.9 kB

Release files / terminaltexteffects-0.6.0.tar.gz

Download URL	terminaltexteffects-0.6.0.tar.gz
Size	67.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`fb87a2b06e7676cd50d05e22181b7bdbaa6d3e7cccdb5f3a978e381a46c8c5be`
BLAKE2b-256 checksum How to use checksums	`79eaf370d7b23a265eac710b671677a6d4ea30a80c0c0c79f7b0e1db67e7c289`
Upload date	Feb 10, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.6.1 CPython/3.10.12 Linux/6.6.10-76060610-generic`

Release files / terminaltexteffects-0.6.0-py3-none-any.whl

Download URL	terminaltexteffects-0.6.0-py3-none-any.whl
Size	98.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`36e32406b387617216069e4511a8358c5fc09739a0ef81c6b089493822941038`
BLAKE2b-256 checksum How to use checksums	`b1c03e26217126b44f47e9b237ea6913a6ecf69c62888466e2f595e666e86e03`
Upload date	Feb 10, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.6.1 CPython/3.10.12 Linux/6.6.10-76060610-generic`