Bangen ✨

---

Bangen is an ASCII banner renderer built on pyfiglet, rich, and Pillow. It gives you a fast live TUI, a composable effect pipeline, JSON presets, and export support for TXT, PNG, and GIF.

Built for terminal art, title cards, intros, and animated text that still feels sharp when exported.

---

🌿 Screenshot

---

Star History ⭐

Why It Stands Out ⚡

• Live split-screen TUI with export modal
• Static and animated banner rendering
• Transparent PNG and animated transparent GIF export
• Plain TXT export with exact ASCII output
• CLI export progress with percentage, elapsed time, ETA, and status text
• Typer-powered CLI help with cleaner option formatting and examples
• Multi-stop gradients with horizontal or vertical interpolation
• Built-in presets plus user presets stored in ~/.bangen/presets/
• Effect library grouped into motion, visual, temporal, distortion, and signature tiers
• CLI workflows for rendering, exporting, listing assets, and loading presets

Quick Look 👀

bangen "SYSTEM READY" --font slant --gradient "#7c3aed:#06b6d4" --effect glow --effect wave

Setup 🛠️

git clone https://github.com/programmersd21/bangen.git
cd bangen
python -m venv .venv
source .venv/bin/activate
pip install -e .

🎯 Or download the prebuilts:

https://github.com/programmersd21/bangen/releases/latest

---

Requirements:

• Python 3.11+
• Pillow is included in the base install

Quick Start 🚀

Render a basic banner:

bangen "HELLO"

Render with custom styling:

bangen "HELLO" --font slant --gradient "#ff00ff:#00ffff"

Render with effects:

bangen "HELLO" --effect wave --effect glow --effect pulse --speed 1.5 --amplitude 2.0

Run screensaver mode:

bangen "HELLO" --screensaver

Export a GIF:

bangen "HELLO" --effect wave --effect glow --export-gif banner.gif --gif-duration 3 --gif-fps 20

Interface 🎛️

TUI 🖥️

Launch the editor:

bangen

Controls:

• ↑↓ navigate fields and effects
• ←→ adjust font or numeric settings
• Enter edit or toggle the selected field
• l load a saved preset or load from a custom preset file
• e open the export dialog
• s save the current preset
• q quit

The effect selector is windowed, so you can move through the full library without overflowing the controls panel.

Export Dialog 📦

Press e inside the TUI to open the exporter.

• Toggle GIF, PNG, and TXT
• Edit the output path directly
• Adjust GIF-only duration and fps
• Auto-update the file extension when the format changes
• Show live export progress in the modal with percentage, elapsed time, ETA, and stage text
• Confirm overwrite when the target file already exists

CLI ⌨️

The CLI is powered by Typer, so bangen --help now presents a cleaner option list and examples while keeping the same flag-based workflow.

Basic Rendering

bangen "HELLO"
bangen "HELLO" --font slant --gradient "#ff00ff:#00ffff"
bangen "HELLO" --gradient "#ff0000:#ffff00:#00ff00" --gradient-dir vertical

Discoverability

bangen --list-effects
bangen --list-fonts
bangen --list-presets

Presets and AI

bangen --preset cyberpunk "HELLO"
bangen --preset matrix "SYSTEM"
bangen --preset-file ./my_preset.json "HELLO"
bangen "HELLO" --ai "retro CRT hacker title"

Export

bangen "HELLO" --export-txt banner.txt
bangen "HELLO" --export-png banner.png
bangen "HELLO" --effect wave --effect glow --export-gif banner.gif --gif-duration 3 --gif-fps 20

CLI exports show a live progress bar with percentage, elapsed time, ETA, and the current export stage.

Releases 📦

GitHub Actions builds standalone binaries for Windows, macOS, and Linux and uploads them to the matching GitHub release.

• asset names follow the project version from pyproject.toml
• release files include the platform in the filename
• the release workflow expects a tag matching the project version, for example v2.2.1
• release builds explicitly bundle the TUI package, effect modules, pyfiglet font assets, Rich, and Pillow runtime pieces so the standalone app works outside a Python environment

Screensaver

Turns any banner text into a full-terminal animated screensaver. It auto-fits the text to the current terminal size, switches between effect scenes, and randomizes speed, amplitude, frequency, and scene duration.

bangen "SYSTEM READY" --screensaver
bangen "NIGHT MODE" --screensaver --screensaver-duration 60
bangen "SIGNAL" --screensaver --screensaver-seed 42

Notes:

• Ctrl+C exits screensaver mode
• --font, --gradient, presets, and AI prompts still influence the starting style
• effect selection is managed by the screensaver engine, so --effect is not the main control surface in this mode
• export flags are ignored while screensaver mode is running

Terminal Animation

Useful for temporal effects such as wipe and typewriter:

bangen "HELLO" --effect wipe --animate --animate-duration 5

Effects Library 🎨

Motion

• wave
• vertical_wave
• bounce
• scroll
• drift
• shake

Visual

• gradient_shift
• pulse
• rainbow_cycle
• glow
• flicker
• scanline

Temporal

• typewriter
• fade_in
• wipe
• stagger
• loop_pulse

Distortion

• glitch
• chromatic_aberration
• noise_injection
• melt
• warp
• fragment

Signature

• matrix_rain
• fire
• electric
• vhs_glitch
• neon_sign
• wave_interference
• particle_disintegration

Effect Stacks 🧪

Effects are order-sensitive and composable:

banner.apply(build_effect("wave", config=cfg))
banner.apply(build_effect("chromatic_aberration", config=cfg))
banner.apply(build_effect("pulse", config=cfg))

Common style stacks:

• cyberpunk: glitch + chromatic_aberration + pulse
• neon: glow + pulse or neon_sign
• matrix: matrix_rain + typewriter
• retro: scanline + flicker
• fire: fire + melt
• electric: electric + glow

Styling & Presets 🌈

Gradients

Use colon-separated hex stops:

#ff00ff:#00ffff
#ff0000:#ffff00:#00ff00

Use --gradient-dir vertical for top-to-bottom interpolation.

Presets 💾

Storage

Saved presets live under:

~/.bangen/presets/*.json

You can create these files manually, save them from the TUI with s, or save from the CLI with --save-preset NAME.

Loading

• TUI: press l, then choose SAVED or FILE
• CLI: --preset NAME loads from built-ins or ~/.bangen/presets/
• CLI: --preset-file PATH loads a preset JSON from any path without saving it

Preset Format

{
  "name": "my_preset",
  "font": "ansi_shadow",
  "gradient": "#ff00ff:#00ffff",
  "gradient_direction": "horizontal",
  "effects": ["wave", "glow", "pulse"],
  "effect_config": {
    "wave": { "speed": 1.8, "amplitude": 2.0, "frequency": 0.7 },
    "pulse": { "speed": 1.2, "min_brightness": 0.55 },
    "glow": {}
  }
}

Notes:

• name, font, and gradient should always be provided
• effects order matters
• speed, amplitude, and frequency map to shared EffectConfig
• any additional keys inside effect_config are passed to the effect constructor

Project Layout 🧱

bangen/
├── effects/
│   ├── base.py
│   ├── distortion.py
│   ├── motion.py
│   ├── signature.py
│   ├── temporal.py
│   ├── utils.py
│   └── visual.py
├── export/
│   ├── exporter.py
│   ├── gif.py
│   ├── png.py
│   └── txt.py
├── gradients/
├── presets/
├── rendering/
└── tui/
    ├── app.py
    ├── export_dialog.py
    └── preset_dialog.py

Notes 📝

• Animated exports look best when you keep effect stacks readable instead of maxing out distortion-heavy combinations.
• Temporal effects such as wipe and typewriter are best previewed with --animate in the terminal before exporting.
• --screensaver is designed for live terminal playback, not export generation.

License 📄

MIT. See LICENSE.