Skip to main content

TTE

Terminal Text Effects

Inline Visual Effects in the Terminal

PyPI - Version PyPI - Python Version Python Bytes License

Table Of Contents

TTE

synthgrid_demo

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 quadratic/cubic 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.

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

View the Documentation for a full installation and usage guide.

Application Quickstart

Options

TTE Command Line Options
options:
-h, --help            show this help message 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 output area width. (default: False)
  --frame-rate FRAME_RATE
                        Target frame rate for the animation. (default: 100)
  --terminal-dimensions TERMINAL_DIMENSIONS TERMINAL_DIMENSIONS
                        Use the terminal dimensions to limit the size of the output area and support wrapping. If False, the output area is determined by the input data dimensions and may overflow the terminal
                        width. (default: (0, 0))
  --ignore-terminal-dimensions
                        Ignore the terminal dimensions and use the input data dimensions for the output area. (default: False)
Effect:
  Name of the effect to apply. Use <effect> -h for effect specific help.

  {beams,binarypath,blackhole,bouncyballs,bubbles,burn,crumble,decrypt,dev,errorcorrect,expand,fireworks,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slide,spotlights,spray,swarm,synthgrid,test,unstable,verticalslice,vhstape,waves,wipe}
                        Available Effects
    beams               Create beams which travel over the output area 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 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.
    orbittingvolley     Four launchers orbit the output area firing volleys of characters inward to build the input text from the center out.
    overflow            Input text overflows ands 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 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.
    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 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 | tte crumble --final-gradient-stops 5CE1FF FF8C00 --final-gradient-steps 12 --final-gradient-direction diagonal

cat your_text | tte <effect> [options]

OR

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

For more information, view the Application Usage Guide.

Library Quickstart

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.

Effect Showcase

Note: Below you'll find a subset of the built-in effects.

View all of the effects and related information in the Effects Showroom.

Beams

beams_demo

Binarypath

binarypath_demo

Blackhole

blackhole_demo

Bubbles

bubbles_demo

Burn

burn_demo

Decrypt

decrypt_demo

Fireworks

fireworks_demo

Orbittingvolley

orbittingvolley_demo

Pour

pour_demo

Print

print_demo

Rain

rain_demo

Rings

rings_demo

Slide

slide_demo

Spotlights

spotlights_demo

Swarm

swarm_demo

VHSTape

vhstape_demo

Waves

waves_demo

In-Development Preview

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

Latest Release Notes

0.9.0


New Features (0.9.0)


New Engine Features (0.9.0)

  • Linear easing function added.

Changes (0.9.0)


Other Changes (0.9.0)

  • Major re-organization of the codebase and significant documentation changes and additions.

License

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

Metadata

Release files for terminaltexteffects 0.9.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.9.0
File Size Uploaded
terminaltexteffects-0.9.0.tar.gz 92.2 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for terminaltexteffects 0.9.0
File Interpreter ABI Platform
terminaltexteffects-0.9.0-py3-none-any.whl Python 3 none any Details

Total release size: 233.9 kB

Release files / terminaltexteffects-0.9.0.tar.gz

Download URL terminaltexteffects-0.9.0.tar.gz
Size 92.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ae105e458b3e1f639bacfc3bbe49179430adef185345181dbd60c94796ed1453
BLAKE2b-256 checksum
How to use checksums
bb199caec9e1496f432552ace9ca2e1c5c8e80c30cd3978681561fad19ea4f00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.2 CPython/3.10.12 Linux/6.8.0-76060800daily20240311-generic

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

Download URL terminaltexteffects-0.9.0-py3-none-any.whl
Size 141.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7aadc7b852da0687e00aab8cc1cb28520bd4196d07bb5bc7304ae13596b08a88
BLAKE2b-256 checksum
How to use checksums
5992180ddd9e68b09c88bdec25b9c38fbb47e5fe568843b9e66a2c863c0bbabc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.2 CPython/3.10.12 Linux/6.8.0-76060800daily20240311-generic

Release history Release notifications | RSS feed

0.15.0

2 release files

0.14.2

2 release files

0.14.1

2 release files

0.14.0

2 release files

0.13.0

2 release files

0.12.2

2 release files

0.12.0

2 release files

0.11.0

2 release files

0.10.1

2 release files

0.10.0

2 release files

0.9.3

2 release files

0.9.2

2 release files

0.9.1

2 release files

This release

0.9.0 This release

2 release files

0.8.0

2 release files

0.7.0

2 release files

0.6.0

2 release files

0.5.0

2 release files

0.4.3

2 release files

0.4.2

2 release files

0.4.1

2 release files

0.4.0

2 release files

0.3.1

2 release files

0.3.0

2 release files

0.2.1

2 release files

0.2.0

2 release files

0.1.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page