terminaltexteffects 0.4.1

Terminal Text Effects

Inline Visual Effects in the Terminal

Table Of Contents

• About
• Requirements
• Installation
• Usage
• Options
• Examples
• In-Development Preview
• Recent Changes
• License

TTE

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

Usage

cat your_text | tte <effect> [options]

OR

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

• All effects support adjustable animation speed using the -a option.
• 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.

  {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

Examples

Fireworks

Rain

Decrypt

Spray

Scattered

Expand

Burn

Pour

Rowslide

Rowmerge

Columnslide

Randomsequence

Verticalslice

Unstable

Bubbles

Bouncyballs

Middleout

Errorcorrect

Waves

Blackhole

Swarm

In-Development Preview

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

Recent Changes

0.4.0

New Features

• 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.

Changes

• 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.

Bug Fixes

• Fixed Gradient creating two more steps than specified.
• Fixed waypoint synced animation index out of range error.

License

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