terminaltexteffects

Terminal Text Effects

Inline Visual Effects in the Terminal

[!NOTE] This README and the documentation follow development main, toward 0.16.0. The latest published release is 0.15.0, so some features described here are not yet in the package on PyPI. See SUPPORT.md for the differences between releases.

Table Of Contents

• About
• Quick Start
• Requirements
• Support and Security
• Installation
• Usage
  • Application Quickstart
  • Library Quickstart
• Effect Showcase
• Changelog
• License

TTE

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 Bézier 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.
• Typed effect configuration that is automatically exposed as CLI arguments.
• Input color preservation and parsing of common ANSI sequences from fetch-style tools.
• Recording rendered effects to files and replaying them without re-rendering.
• Custom effect plugins that run alongside the built-in effects.
• Runs inline, preserving terminal state and workflow.

Quick Start

pipx install terminaltexteffects

echo "Hello, terminal!" | tte beams

Requirements

Development main requires Python 3.9.2 or newer. The core package does not require any third-party modules. Terminal interactions use standard ANSI terminal sequences and should work in most modern terminals.

Support and Security

See SUPPORT.md for Python/platform coverage, terminal requirements, shell completion, and reporting ordinary problems. Report vulnerabilities privately through the route in SECURITY.md; security fixes target the latest stable release.

Installation

pipx install terminaltexteffects

pip install terminaltexteffects

uv tool run terminaltexteffects -h

uv tool install terminaltexteffects

uv add terminaltexteffects

nix shell github:ChrisBuilds/terminaltexteffects

echo 'terminaltexteffects is awesome' | nix run github:ChrisBuilds/terminaltexteffects -- beams

inputs = {
  terminaltexteffects.url = "github:ChrisBuilds/terminaltexteffects";
};

let
  pkgs = import <nixpkgs> {};

  tte = pkgs.callPackage (pkgs.fetchFromGitHub {
    owner = "ChrisBuilds";
    repo = "terminaltexteffects";
    rev = "COMMIT_SHA";
    hash = ""; # Build first, put proper hash in place
  }) {};
in
  pkgs.mkShell {
    packages = [tte];
  }

Usage

View the Documentation for a full installation and usage guide.

Application Quickstart

tte [global_options] <effect> [effect_options] < your_file

Input can be piped or redirected through stdin, or passed with --input-file/-i. python -m terminaltexteffects works in place of tte.

• Use tte -h to list global options and effects, and tte <effect> -h to view options for a specific effect, such as color or movement direction.
• Randomly select an effect with --random-effect/-R. Use --seed to make the choice repeatable, and --include-effects or --exclude-effects to limit the pool.
• Enable shell completion for built-in effects in the current shell. Add the line to ~/.bashrc or ~/.zshrc to keep it. See Shell Completion for PowerShell and other details.
  • Bash: eval "$(tte --print-completion bash)"
  • Zsh: eval "$(tte --print-completion zsh)"
• Add custom effect modules to ${XDG_CONFIG_HOME}/terminaltexteffects/effects, or ~/.config/terminaltexteffects/effects when XDG_CONFIG_HOME is unset, empty, or a relative path. See Community effects for installation steps, and browse or share projects in TTE Effect Show and Tell.
• Compose text and preview effects interactively by running tte with no effect, after installing the optional extra with pipx install 'terminaltexteffects[tui]'. See Interactive Interface.
• Record effects and replay them later with --export and --play. See Recording and playback.
• TTE is not a full terminal emulator, but it parses common fetch-style input including SGR colors, cursor movement, and carriage returns. Unsupported control sequences fail with an error rather than leaking into the animation.

For all options and more examples, 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 Rain

effect = Rain("your text here")

for frame in effect:
    # do something with the string
    ...

To let TTE handle terminal setup/teardown, cursor positioning, and animation frame rate, use the terminal_output() context manager.

from terminaltexteffects.effects import Rain

effect = 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

Below you’ll find a subset of the built-in effects. View all of the effects and related information in the Effects Showroom.

Changelog

See the CHANGELOG for release history. Unreleased changes on development main appear in the documentation changelog. The ChangeBlog provides optional release write-ups and demos.

License

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