Unicode Animatio

Lightweight Unicode and ASCII terminal animation data for Python.

GitHub · PyPI · Website · Docs · X

Unicode Animatio packages deterministic animation frames and timing for terminals and other text renderers. It has no runtime dependencies and does not take ownership of colors, labels, layout, progress, or task state.

The distribution and CLI name is unicode-animatio. The Python import root is unicode_animations.

Read This First

1. Read At a Glance for the package naming and renderer boundary.
2. Follow Install and Quick Start to read animation frames and render a first spinner.
3. Use Python Examples for braille grids, provider integration, and category lookup.
4. Use Preview Every Animation before choosing a preset.
5. Read Development before changing the package.

Trust and Brand Safety

• Official GitHub: https://github.com/openminion/unicode-animatio
• Official website: https://www.openminion.com
• Official X account: https://x.com/OpenMinion

Unicode Animatio has no official token, coin, NFT, airdrop, staking program, treasury product, or investment offering. Any claim otherwise is unauthorized and should be treated as a scam.

At a Glance

Common Commands

python3 -m pip install unicode-animatio
unicode-animatio --list
unicode-animatio --categories
unicode-animatio --search graph --json
unicode-animatio --show edgepulse
unicode-animatio --version
unicode-animatio helix
unicode-animatio --web --port 8765

Install

Install from PyPI:

python3 -m pip install unicode-animatio

For a source checkout:

python3 -m pip install -e ".[dev]"

Quick Start

Animation records contain immutable frames plus an interval in milliseconds:

from unicode_animations import spinners

spinner = spinners["braille"]
print(spinner.frames)
print(spinner.interval)

The host application owns rendering. A minimal terminal loop looks like this:

from itertools import cycle, islice
import sys
import time

from unicode_animations import spinners

spinner = spinners["braille"]

for frame in islice(cycle(spinner.frames), 30):
    sys.stdout.write(f"\r{frame} Working...")
    sys.stdout.flush()
    time.sleep(spinner.interval / 1000)

sys.stdout.write("\n")

This example stops after 30 frames. A real renderer should also handle cancellation, cursor cleanup, reduced-motion preferences, and non-interactive output.

Python Examples

Build a braille frame

Use make_grid to create a dot grid and grid_to_braille to convert it to Unicode braille cells:

from unicode_animations import grid_to_braille, make_grid

grid = make_grid(rows=4, cols=4)
grid[0][0] = True
grid[1][1] = True

print(grid_to_braille(grid))

The compatibility aliases makeGrid and gridToBraille remain available, but new code should use the snake-case names.

Use the provider boundary

Use the provider boundary when the consumer should not depend on the catalog implementation:

from unicode_animations import get_provider

provider = get_provider()
animation = provider.get("helix")
wide_animation = provider.get("helix", length=3)
metadata = provider.describe("helix")

print(provider.provider_id)
print(animation.frames)
print(animation.interval_ms)
print(metadata.tags)

length repeats each frame in sync, so a host can request a wider animation without combining independently phased indicators. It defaults to 1 and does not change the frame count or interval.

The provider exposes structural animation records with frames, interval_ms, category, tags, frame count, width hints, motion hints, and usage descriptions. This is the preferred boundary for plugin hosts and applications that may swap animation providers.

get_provider() is the framework-neutral Python integration surface. The installed openminion.cli.animation_providers entry point adds automatic discovery specifically for OpenMinion. Other hosts do not share that entry-point protocol; they should map their own lifecycle events to a selected preset and render its raw frames.

Browse by category

Use the category API when an application wants to offer a constrained preset picker:

from unicode_animations import (
    SPINNER_CATEGORIES,
    metadata_for_spinner,
    search_spinner_names,
    spinner_names_for_category,
)

print(spinner_names_for_category("graph"))
print(SPINNER_CATEGORIES["edgepulse"])
print(search_spinner_names("knowledge", category="graph"))
print(metadata_for_spinner("edgepulse").description)

spinner_names_for_category() returns canonical preset names. SPINNER_CATEGORIES maps each preset name to its category. search_spinner_names() searches preset names, categories, and tags in catalog order.

Preview Every Animation

The preview tools are the fastest way to understand the catalog. They render the raw records but are not application UI frameworks.

Terminal preview

Discover presets:

unicode-animatio --list
unicode-animatio --categories
unicode-animatio --list --category graph
unicode-animatio --search knowledge --category graph
unicode-animatio --show edgepulse
unicode-animatio --show edgepulse --json

Cycle through all animations or run one by name:

unicode-animatio
unicode-animatio helix
unicode-animatio edgepulse

The preview respects terminal color capability by default. Override it when testing a renderer:

unicode-animatio helix --color auto --foreground gray

Press Ctrl+C to stop a running terminal preview.

Browser preview

Open the local gallery through either command:

unicode-animatio --web
unicode-animatio-web --port 8765

The browser gallery includes category chips, search, theme toggle, reduced-motion toggle, a selected-preset details panel, and a copyable provider snippet for host integration. It starts from the operating system's color and reduced-motion preferences, remembers explicit choices, supports arrow-key preset selection, shows live filter-result counts, and announces copy and search status to assistive technology.

For a remote development machine:

unicode-animatio --web --host 0.0.0.0 --port 8765 --no-open

Binding to 0.0.0.0 exposes the preview server to the machine's network. Use that option only on a trusted development network.

Source-checkout terminal demo

The repository includes a longer Python API demo that can cycle through the catalog or focus on one preset:

python examples/terminal_demo.py
python examples/terminal_demo.py --seconds-per-spinner 2 --loops 2
python examples/terminal_demo.py helix
python examples/terminal_demo.py --list

This script is part of the source checkout; it is not installed as a console command.

What Unicode Animatio Provides

• immutable animation frame data and millisecond timing
• canonical animation names, categories, metadata, and searchable tags
• braille-grid helpers: make_grid and grid_to_braille
• compatibility aliases: makeGrid and gridToBraille
• a structural provider entry point for host applications
• a terminal preview CLI: unicode-animatio
• a local browser preview CLI: unicode-animatio-web
• a PEP 561 type marker and typed public API

What Unicode Animatio Does Not Provide

• terminal UI or async rendering frameworks
• progress bars, task orchestration, or job-state tracking
• renderer colors, backgrounds, labels, or layout
• provider-level reduced-motion or accessibility policy beyond metadata hints; the bundled browser preview manages only its own presentation preferences
• hosted demos or remote APIs
• framework-specific Rich, Textual, or Typer adapters

The host renderer owns presentation and accessibility. The package returns raw frames and timing only.

Available animations

The catalog currently contains 58 deterministic animations:

Prefer a visual overview? Expand the complete catalog poster below.

Representative first frames show the range of the catalog. The browser and terminal previews show the complete frame sequences.

Choosing a Preset

Inspect exact names and timing rather than selecting from memory:

unicode-animatio --categories
unicode-animatio --list --category data
unicode-animatio --search stream
unicode-animatio packetflow

For public-facing previews, start with edgepulse, packetflow, helix, synapse, focusbeam, and shimmergrid. They show graph traversal, data movement, thinking, inspection, and high-energy showcase states without needing an application renderer.

Development

make dev-install
make hooks-install
make check

Use make release-check before publishing or changing the documented public surface.

Docs and Release

• docs/README.md: package documentation map
• docs/getting-started.md: package usage and contributor bootstrap
• docs/source-tree-owner-map.md: code owners and package layout
• API_COMPATIBILITY.md: public names and provider contract
• RELEASING.md: release and publish flow

Questions and bug reports belong in GitHub Issues.

Community

• Contributing guide
• Code of Conduct
• GitHub Issues
• OpenMinion organization

License and Brand-use Boundary

• Source code license: MIT
• Brand/trademark grant: none

The license grants rights to use, modify, and redistribute the code. It does not grant rights to present a fork, clone, token, website, or social account as the official Unicode Animatio or OpenMinion project or imply affiliation or endorsement.