TerminalTextEffects (TTE) is a terminal visual effects engine designed for two primary use cases:

1. System Application: Run TTE directly in your terminal to produce visual effects.
2. Python Library: Integrate TTE effects into your own Python scripts and applications.

Key engine features include:

• Color Support: Xterm 256 and RGB hex colors.
• Motion Control: Complex character movement using Paths, Waypoints, motion easing, and quadratic/cubic bezier curves.
• Animation Engine: Support for Scenes with symbol/color changes, layers, easing, and Path-synced progression.
• Gradients: Variable stop/step color gradient generation.
• Event Handling: Custom callback support for Path/Scene state changes.
• Configuration: Typed effect configuration dataclasses that automatically map to CLI arguments.

To optimize effect output, distinguish between these three layers:

1. Terminal Dimensions: Based on your terminal emulator (discovered via shutil.get_terminal_size(), falling back to (80, 24)).
2. Canvas Dimensions: The 'world' for the effect. It can be sized to the terminal, the input text, or an arbitrary size. Effects should reference the Canvas for coordinates to ensure proper anchoring.
3. Input Text Dimensions: The dimensions of the data passed to TTE. These can be modified if --wrap-text is used, which wraps text based on Canvas dimensions (or Terminal dimensions if the Canvas matches the text).

Version 0.11.0 introduces the Matrix effect and significant engine improvements. Key updates include:

• Matrix Effect: A high-fidelity digital rain effect.
• Canvas Overhaul: The Canvas class has been redesigned to support arbitrary resizing and anchoring (both anchoring the Canvas within the terminal and anchoring text within the Canvas).
• Effect Improvements: Updates to Slice and Print effects to support the new Canvas system.
• CLI Updates: Added a --version switch.
• Interrupt Handling: Improved handling of ctrl-c during animations.
• BaseCharacter Attribute: Added is_fill_character to the BaseCharacter class.

Version 0.12.0 introduced three new visual effects:

• Highlight: Runs a specular highlight across the text. Parameters for brightness, width, and direction are customizable.
• LaserEtch: Simulates burning text into the terminal with flying sparks that cool and disappear. Parameters for etch speed, laser colors, spark colors, and all gradients are customizable.
• Sweep: Performs two passes over the canvas. The first pass reveals the text (dimmed and colorless), and the second pass applies color. Sweep directions and sweep noise symbols are customizable.

The Terminal Text Effects (TTE) engine is built around two primary components: the Terminal object and EffectCharacter objects.

• Terminal: Acts as the orchestrator. It is responsible for creating EffectCharacter instances, providing them to effects, and managing the rendering process. It handles terminal dimensions and converts the state of all characters into a single output string for printing.
• EffectCharacter: Represents an individual character on the screen. Each character is an isolated object responsible for its own animation logic, motion, and visual appearance.

On every call to Terminal.print(), the Terminal retrieves the latest location and string representation from each EffectCharacter to update the screen.

TTE can be used in two ways depending on your needs. Choose the guide that matches your workflow:

• As a System Application: Use the Application Usage guide to learn how to run effects directly in your terminal.
• As a Python Library: Use the Library Usage guide to integrate effects into your Python code.

Before starting, ensure you follow the Installation Guide.

TTE can generate shell completion scripts for bash and zsh. These scripts include discovered custom effects and their options.

To use completions for a single session, use eval with the --print-completion flag. To make completions permanent, add the command to your shell startup file (e.g., .bashrc or .zshrc).

The Unstable effect creates a jittery or unstable text animation. To use it, import Unstable from terminaltexteffects.effects.effect_unstable, instantiate it with your desired string, and iterate through the effect object to retrieve frames. Use the terminal_output() context manager to handle terminal rendering.

from terminaltexteffects.effects.effect_unstable import Unstable

effect = Unstable("YourTextHere")
with effect.terminal_output() as terminal:
    for frame in effect:
        terminal.print(frame)

TTE can automatically discover user-provided effects located in the following directory:

• ${XDG_CONFIG_HOME}/terminaltexteffects/effects
• If ${XDG_CONFIG_HOME} is unset: ~/.config/terminaltexteffects/effects

To register an effect, create a Python file in that directory and implement a get_effect_resources() function. This function must return a tuple containing the CLI command name, the effect class, and the config class. Once registered, the effect can be used via the CLI like any built-in effect.

# Example: ~/.config/terminaltexteffects/effects/effect_custom.py

def get_effect_resources():
    return "custom", CustomEffect, CustomConfig

Usage:

cat message.txt | tte custom

To evaluate the impact of code changes, run a baseline benchmark, then run a candidate benchmark using the same arguments, and finally use the --compare flag to compare the two resulting JSON files.

Note: Comparison results are advisory. They report mean deltas for build, render, and total time, but regressions are not treated as failures unless a specific threshold is set.

./.venv/bin/python tools/perf/benchmark_effects.py \
  --compare /tmp/tte-baseline.json /tmp/tte-candidate.json