Discover effects, presets, and settings

The same typed catalog exposes capture and record methods with matching preset/settings hints. See Seeded capture and recording for seeded randomness, immutable frame snapshots, and headless .cast export. bruhanimate info EFFECT includes the inherited seed setting; play and record also accept --seed.

A preset is a named settings object. For example, snow’s light preset uses SnowSettings(intensity=0.005, wind=0.0, show_info=False, collision=False). It lowers the per-column, per-tick chance of creating a flake from the default 0.01 to 0.005. It does not change playback FPS or simulation tick frequency.

Explore in Python

from bruhanimate import effects

print(effects.names())                 # All registered effects, including extensions
print(effects.snow.description)
print(effects.snow.defaults())         # A fresh SnowSettings object
print(effects.snow.presets())          # light, moderate, blizzard, windy + values
print(effects.snow.preset("light"))     # One independent SnowSettings copy

Type effects. in an editor to browse the built-in catalog. Its members are statically declared, so editors can discover them without running animations. effects.snow.play(preset=...) and effects.snow.preset(...) use snow-specific Literal types; compatible editors suggest its preset names. Settings parameters and return values retain the concrete settings class. Exact completion UI depends on your editor and Python language server.

from bruhanimate import effects

effects.snow.play(preset="light", fps=60, updates_per_second=30, duration=10)

The string-based API remains available and accepts custom registered names:

from bruhanimate import play

play("snow", preset="light", fps=60, updates_per_second=30, duration=10)

The general play function accepts arbitrary registry names and validates their settings/presets at runtime. Use the typed catalog for effect-specific static checks. EffectName describes built-in names only; it does not limit runtime registration. effect_registry.names(), get(name), and presets(name) also support custom effects. Static catalog members are not generated dynamically for extensions or registry replacements.

Customize a preset

from bruhanimate import effects

settings = effects.snow.preset("light")
settings.wind = 0.4
effects.snow.play(settings=settings, duration=10)

Preset inspection returns independent copies, including nested lists. Editing one cannot alter future animations. Explicit settings replace a preset’s whole configuration; they are not a partial merge. When both settings and a preset are supplied, the preset name must still exist. Settings objects remain mutable, but editing one does not reconfigure a running effect.

Built-in dataclasses validate at construction, and built-in effects validate again before using supplied settings. Wrong types raise TypeError; invalid ranges, choices, non-finite numbers, and unsupported glyphs raise ValueError with the field name. Booleans are not numbers. Glyph fields accept one printable single-cell character; wide/combining characters and escape sequences are not supported. Valid zero values and ANSI color index 0 are preserved.

Custom registry settings are checked against their declared class. They can inherit EffectSettings to opt into built-in field validation, or enforce their own rules. Existing individual effect setter methods retain their documented behavior; these validation rules apply to settings objects.

Explore from the command line

Both entry points use the same registry and player:

bruhanimate list
bruhanimate presets snow
bruhanimate info snow
bruhanimate play snow --preset light --duration 10 --fps 60 --updates-per-second 30
python -m bruhanimate info snow

list shows descriptions; presets shows names and complete configurations; info additionally shows field types, defaults, and numeric ranges. Discovery does not construct effects, open a terminal, or start audio capture. Use bruhanimate --help and bruhanimate play --help for command options. In a source checkout, prefix commands with uv run --locked.

Override individual fields with repeatable --set FIELD=VALUE arguments. Overrides are applied to the chosen preset, or to defaults when no preset is selected. Values are JSON (numbers, true/false, arrays, null), or text for choices such as east. Quote values as required by your shell:

bruhanimate play snow --preset light --set wind=0.4 --duration 10
bruhanimate play matrix --set 'character_halt_range=[2,4]' --duration 10
bruhanimate play rain --set wind_direction=east --set lightning_color_type=0

Invalid names, settings, and timing options fail before opening a terminal. --duration is wall-clock seconds after startup, including paused or held time. --frames limits presentations. The first limit or quit request wins; zero starts no effect. Synchronous work cannot be interrupted mid-callback, so a slow callback may overrun a duration. play still opens/restores its Screen for zero-duration playback. See Player and composition for lifecycle details.

Catalog API

class bruhanimate.effects.EffectInfo(name: Literal['static', 'offset', 'noise', 'stars', 'plasma', 'gol', 'rain', 'matrix', 'drawlines', 'snow', 'twinkle', 'audio', 'firework', 'fire', 'julia', 'boids', 'sand', 'diffusion', 'water', 'smoke', 'metaballs', 'cloth', 'terrain', 'automaton', 'voronoi', 'perlin'])

Typed view of a registry entry, without constructing a running effect.

name: Literal['static', 'offset', 'noise', 'stars', 'plasma', 'gol', 'rain', 'matrix', 'drawlines', 'snow', 'twinkle', 'audio', 'firework', 'fire', 'julia', 'boids', 'sand', 'diffusion', 'water', 'smoke', 'metaballs', 'cloth', 'terrain', 'automaton', 'voronoi', 'perlin']

property description: str

Human-readable description from the live registry.

defaults() → SettingsT

Return a fresh default configuration, or None for unconfigured effects.

presets() → dict[PresetT, SettingsT]

Return preset names and independent, editable configuration copies.

preset(name: PresetT) → SettingsT

Return one preset’s settings; editors suggest this effect’s names.

play(*, preset: PresetT | None = None, settings: SettingsT | None = None, seed: int | None = None, fps: float | None = 30, updates_per_second: float | None = None, frames: int | None = None, duration: float | None = None, on_complete: Literal['hold', 'exit'] = 'hold', on_resize: Literal['raise', 'resize'] = 'raise', background: str = ' ', event_handler: Callable[[int], bool] | None = None) → int

Play this effect with typed presets/settings through the shared player.

duration is wall-clock seconds after startup; None is unlimited and zero starts no effect. See bruhanimate.play for timing and ownership details.

capture(*, on_frame: Callable[[Frame], None], preset: PresetT | None = None, settings: SettingsT | None = None, seed: int | None = None, width: int = 80, height: int = 24, fps: float = 30, updates_per_second: float | None = None, frames: int | None = None, duration: float | None = None, on_complete: Literal['hold', 'exit'] = 'exit', background: str = ' ') → int

Stream immutable frames with typed presets/settings and virtual timing.

Requires frames or duration; see bruhanimate.capture for lifecycle, reproducibility and timing details. seed overrides the selected settings.

record(output: str | PathLike[str] | TextIO, *, preset: PresetT | None = None, settings: SettingsT | None = None, seed: int | None = None, width: int = 80, height: int = 24, fps: float = 30, updates_per_second: float | None = None, frames: int | None = None, duration: float | None = None, on_complete: Literal['hold', 'exit'] = 'exit', background: str = ' ', overwrite: bool = False) → int

Record an asciicast v2 file or borrowed text stream, without a terminal.

Requires frames or duration; see bruhanimate.record. Existing files are protected unless overwrite=True. Preset/settings hints match this effect.

__init__(name: Literal['static', 'offset', 'noise', 'stars', 'plasma', 'gol', 'rain', 'matrix', 'drawlines', 'snow', 'twinkle', 'audio', 'firework', 'fire', 'julia', 'boids', 'sand', 'diffusion', 'water', 'smoke', 'metaballs', 'cloth', 'terrain', 'automaton', 'voronoi', 'perlin']) → None

bruhanimate.effects.names() → list[str]

List all currently registered names, including custom effects.

bruhanimate.effects.get(name: str) → EffectEntry

Inspect a live registry entry, including custom effects.