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

  {bouncyballs,bubbles,burn,columnslide,decrypt,errorcorrect,expand,fireworks,middleout,pour,rain,randomsequence,rowmerge,rowslide,scattered,spray,unstable,verticalslice}
                        Available Effects
    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.
    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.

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

In-Development Preview

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

Recent Changes

0.3.1

New Features

• Bouncyballs effect. Balls drop from the top of the output area and bounce before settling into position. A gradient is used to transition to the final color after the ball has landed. Random colors are used for balls unless specified.

• Unstable effect. Spawn characters jumbled, explode to the edge of the output area, then reassemble them in the correct layout.

• Bubble effect. Characters are formed into bubbles and fall down the screen before popping.

• Middleout effect. Characters start as a single character in the center of the output area. A row or column is expanded in the center of the screen, then the entire output is expanded from this row/column. Expansion from row/column is determined by the --expand-direction argument.

• Errorcorrect effect. Some characters spawn with their location swapped with another character. The characters then move, in pairs, to their correct location following an animation.

• --no-wrap argument prevents line wrapping.

• --tab-width argument can be used to specify the number of spaces used in place of tab characters. Defaults to 4.

• New Events for WaypointActivated and SceneActivated.

• New Event Actions for DeactivateWaypoint and DeactivateScene.

• Scenes can be synced to Waypoint progress. The scene will progress in-line with the character's steps towards the waypoint.

• Waypoints now have a layer attribute. Characters are drawin in ascending layer order. While a character has a waypoint active, that waypoint's layer is used. Otherwise, the character is drawn in layer 0.

Changes

• Added Easing Functions help output for fireworks effect.
• Updated spray effect help output.
• Removed shootingstar effect. It was not particularly interesting.
• Coord type is now hashable and frozen.
• Waypoints are hashable. Can be compared for equality based on row, col pair.
• Scenes can be compared for equality based on id.
• Terminal maintains an input_coord tuple[row, col] -> EffectCharacter map called character_by_input_coord.
• The terminal cursor is now hidden during the effect.
• The find_points_on_circle method in the motion module is now a static method.
• Terminal.OutputArea has center_row and center_column attributes.
• Added layers to effects.

Bug Fixes

• Fixed animating_chars filter in effect_template to properly remove completed characters.
• Initial symbol assignment when activating a scene no longer increases played_frames count.
• Waypoints and Animations completed are deactivated to prevent repeated event triggering.
• Fixed step_animation in graphics module handling of looping animations. It will no longer deactivate the animation.

License

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