Aisling

Embeddable terminal text effects for Rust TUI applications.

Aisling renders animated text effects as plain Rust data. It does not own your terminal, start an event loop, sleep, or print unless you run the included examples. Your app drives the iterator and maps each styled Frame into Ratatui, Crossterm, ANSI output, tests, logs, or any custom renderer.

The effect catalog is ported from the Python terminaltexteffects project shape and includes every built-in reference effect exposed by the current snapshot.

Install

After publishing:

cargo add aisling

Or in Cargo.toml:

[dependencies]
aisling = "0.1"

For local development from this repository:

[dependencies]
aisling = { path = "../aisling" }

Quick Start

use aisling::{Effect, EffectConfig, EffectKind};

let config = EffectConfig::default()
    .with_duration(80)
    .with_seed(42);

let effect = Effect::with_config(EffectKind::Matrix, "Aisling", config);

for frame in effect.iter() {
    // Map frame.cells() into your TUI buffer.
    let plain = frame.to_plain_string();
    let ansi = frame.to_ansi_string();
}

TUI Integration

Effect::iter() yields Frame values. A Frame is a fixed-size grid with row-major Cell data.

Important types:

Type	Purpose
`Effect`	Owns the effect kind, input text, and config.
`EffectKind`	Selects one of the built-in effects.
`EffectConfig`	Controls duration, seed, gradient, canvas size, color handling, and more.
`Frame`	Rendered 2D grid for a single animation tick.
`Cell`	Character plus foreground/background colors and simple styles.
`Color`, `Gradient`, `Easing`	Color and timing helpers.

Minimal renderer loop shape:

use aisling::{Effect, EffectKind};

let effect = Effect::new(EffectKind::Wipe, "ship it");

for frame in effect.iter() {
    for y in 0..frame.height() {
        for x in 0..frame.width() {
            let cell = frame.cell(x, y).unwrap();
            // Write cell.ch and cell.colors into your TUI buffer here.
        }
    }
}

Effects

All built-in effects are available through EffectKind and EffectKind::all().

Command	Enum
`beams`	`EffectKind::Beams`
`binarypath`	`EffectKind::BinaryPath`
`blackhole`	`EffectKind::Blackhole`
`bouncyballs`	`EffectKind::BouncyBalls`
`bubbles`	`EffectKind::Bubbles`
`burn`	`EffectKind::Burn`
`colorshift`	`EffectKind::ColorShift`
`crumble`	`EffectKind::Crumble`
`decrypt`	`EffectKind::Decrypt`
`errorcorrect`	`EffectKind::ErrorCorrect`
`expand`	`EffectKind::Expand`
`fireworks`	`EffectKind::Fireworks`
`highlight`	`EffectKind::Highlight`
`laseretch`	`EffectKind::LaserEtch`
`matrix`	`EffectKind::Matrix`
`middleout`	`EffectKind::MiddleOut`
`orbittingvolley`	`EffectKind::OrbittingVolley`
`overflow`	`EffectKind::Overflow`
`pour`	`EffectKind::Pour`
`print`	`EffectKind::Print`
`rain`	`EffectKind::Rain`
`randomsequence`	`EffectKind::RandomSequence`
`rings`	`EffectKind::Rings`
`scattered`	`EffectKind::Scattered`
`slice`	`EffectKind::Slice`
`slide`	`EffectKind::Slide`
`smoke`	`EffectKind::Smoke`
`spotlights`	`EffectKind::Spotlights`
`spray`	`EffectKind::Spray`
`swarm`	`EffectKind::Swarm`
`sweep`	`EffectKind::Sweep`
`synthgrid`	`EffectKind::SynthGrid`
`thunderstorm`	`EffectKind::Thunderstorm`
`unstable`	`EffectKind::Unstable`
`vhstape`	`EffectKind::VhsTape`
`waves`	`EffectKind::Waves`
`wipe`	`EffectKind::Wipe`

String parsing is supported:

use std::str::FromStr;
use aisling::EffectKind;

let kind = EffectKind::from_str("laseretch").unwrap();
assert_eq!(kind, EffectKind::LaserEtch);

Configuration

use aisling::{Color, EffectConfig, Easing, Gradient, GradientDirection};

let config = EffectConfig::default()
    .with_duration(120)
    .with_seed(9001)
    .with_canvas_size(48, 8)
    .with_gradient(
        Gradient::new(
            vec![Color::rgb(255, 170, 60), Color::rgb(80, 110, 95)],
            24,
        ),
        GradientDirection::Horizontal,
    );

Notable EffectConfig fields:

Field	Meaning
`duration`	Number of animation frames.
`hold_final_frames`	Extra frames that hold the final text.
`seed`	Deterministic random seed for repeatable playback.
`gradient`	Final/effect color gradient.
`gradient_direction`	Horizontal, vertical, diagonal, or radial mapping.
`easing`	Global easing used by many effect renderers.
`existing_color_handling`	Preserve or ignore parsed ANSI input colors.
`no_color`	Disable color output.
`canvas_width`, `canvas_height`	Optional fixed frame dimensions.
`tab_width`	Spaces per tab when parsing input text.

ANSI Input

Aisling parses common ANSI SGR sequences in input text, including foreground/background 3-bit, bright 3-bit, 8-bit xterm, and 24-bit RGB colors. Parsed styling is kept in each final Cell when the color-handling mode allows it.

use aisling::{Effect, EffectKind};

let effect = Effect::new(EffectKind::Print, "\x1b[38;2;255;80;80mred text\x1b[0m");
let final_frame = effect.final_frame();
assert_eq!(final_frame.to_plain_string(), "red text");

Examples

Run a single effect in the terminal:

cargo run --example demo -- wipe "Hello from Aisling"
cargo run --example demo -- matrix "opencode style"

Use the helper script while developing locally:

./run.sh wipe "Hello from Aisling"
./run.sh matrix "opencode style"
./run.sh list
./run.sh all "Aisling"

Run the multi-pane all-effects showcase:

./run.sh showcase
./run.sh showcase --theme industrial
./run.sh showcase --seconds 60
./run.sh showcase --forever

test.sh launches the showcase with a longer embedded text sample:

./test.sh
./test.sh 90
./test.sh --industrial
./test.sh --industrial 90

Package Verification

Before publishing:

cargo fmt
cargo test
cargo package --allow-dirty

Publish when ready:

cargo publish

License

MIT

aisling 0.1.0