| Name | terminaltexteffects JSON |
| Version |
0.9.2
JSON |
| download |
| home_page | None |
| Summary | A collection of visual effects that can be applied to terminal piped stdin text. |
| upload_time | 2024-05-11 12:15:06 |
| maintainer | None |
| docs_url | None |
| author | Chris |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<br/>
<p align="center">
<a href="https://github.com/ChrisBuilds/terminaltexteffects">
<img src="https://github.com/ChrisBuilds/terminaltexteffects/assets/57874186/66388e57-e95e-4619-b804-1d8d7ebd124f" alt="TTE" width="80" height="80">
</a>
<h3 align="center">Terminal Text Effects</h3>
<p align="center">
Inline Visual Effects in the Terminal
<br/>
<br/>
</p>
</p>
[](http://pypi.org/project/terminaltexteffects/ "")  [](https://youtu.be/eWnYlxOREu4?t=1549) 
## Table Of Contents
* [About](#tte)
* [Requirements](#requirements)
* [Installation](#installation)
* [Usage (Application)](#application-quickstart)
* [Usage (Library)](#library-quickstart)
* [Effect Showcase](#effect-showcase)
* [In-Development Preview](#in-development-preview)
* [Latest Release Notes](#latest-release-notes)
* [License](#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 quadratic/cubic bezier 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.
* Effect customization exposed through a typed effect configuration
dataclass that is automatically handled as CLI arguments.
* Runs inline, preserving terminal state and workflow.
## Requirements
TerminalTextEffects is written in Python and does not require any 3rd party modules. Terminal interactions use standard ANSI terminal sequences and should work in most modern terminals.
Note: Windows Terminal performance is slow for some effects.
## Installation
```pip install terminaltexteffects```
OR
```pipx install terminaltexteffects```
## Usage
View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for a full installation and usage guide.
### Application Quickstart
#### Options
<details>
<summary>TTE Command Line Options</summary>
```markdown
options:
-h, --help show this help message and exit
--tab-width (int > 0)
Number of spaces to use for a tab character. (default: 4)
--xterm-colors Convert any colors specified in RBG hex to the closest XTerm-256 color. (default: False)
--no-color Disable all colors in the effect. (default: False)
--wrap-text Wrap text wider than the output area width. (default: False)
--frame-rate FRAME_RATE
Target frame rate for the animation. (default: 100)
--terminal-width TERMINAL_WIDTH
Terminal width, if set to 0 the terminal width is detected automatically. (default: 0)
--terminal-height TERMINAL_HEIGHT
Terminal height, if set to 0 the terminal height is detected automatically. (default: 0)
--ignore-terminal-dimensions
Ignore the terminal dimensions and use the input data dimensions for the output area. (default: False)
Effect:
Name of the effect to apply. Use <effect> -h for effect specific help.
{beams,binarypath,blackhole,bouncyballs,bubbles,burn,crumble,decrypt,errorcorrect,expand,fireworks,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slide,spotlights,spray,swarm,synthgrid,unstable,verticalslice,vhstape,waves,wipe}
Available Effects
beams Create beams which travel over the output area illuminating the characters behind them.
binarypath Binary representations of each character move through the terminal towards the home coordinate of the character.
blackhole Characters are consumed by a black hole and explode outwards.
bouncyballs Characters are bouncy balls falling from the top of the output area.
bubbles Characters are formed into bubbles that float down and pop.
burn Burns vertically in the output area.
crumble Characters lose color and crumble into dust, vacuumed up, and reformed.
decrypt Display a movie style decryption effect.
errorcorrect Some characters start in the wrong position and are corrected in sequence.
expand Expands the text from a single point.
fireworks Characters launch and explode like fireworks and fall into place.
middleout Text expands in a single row or column in the middle of the output area then out.
orbittingvolley Four launchers orbit the output area firing volleys of characters inward to build the input text from the center out.
overflow Input text overflows ands scrolls the terminal in a random order until eventually appearing ordered.
pour Pours the characters into position from the given direction.
print Lines are printed one at a time following a print head. Print head performs line feed, carriage return.
rain Rain characters from the top of the output area.
randomsequence Prints the input data in a random sequence.
rings Characters are dispersed and form into spinning rings.
scattered Text is scattered across the output area and moves into position.
slide Slide characters into view from outside the terminal.
spotlights Spotlights search the text area, illuminating characters, before converging in the center and expanding.
spray Draws the characters spawning at varying rates from a single point.
swarm Characters are grouped into swarms and move around the terminal before settling into position.
synthgrid Create a grid which fills with characters dissolving into the final text.
unstable Spawn characters jumbled, explode them to the edge of the output area, then reassemble them in the correct layout.
verticalslice Slices the input in half vertically and slides it into place from opposite directions.
vhstape Lines of characters glitch left and right and lose detail like an old VHS tape.
waves Waves travel across the terminal leaving behind the characters.
wipe Wipes the text across the terminal to reveal characters.
Ex: ls -a | python -m terminaltexteffects decrypt --typing-speed 2 --ciphertext-colors 008000 00cb00 00ff00 --final-gradient-stops eda000 --final-gradient-steps 12 --final-gradient-direction vertical
```
</details>
```cat your_text | tte <effect> [options]```
OR
```cat your_text | python -m terminaltexteffects <effect> [options]```
* Use ```<effect> -h``` to view options for a specific effect, such as color or movement direction.
* Ex: ```tte decrypt -h```
For more information, view the [Application Usage Guide](https://chrisbuilds.github.io/terminaltexteffects/appguide/).
### 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.
```python
from terminaltexteffects.effects import effect_rain
effect = effect_rain.Rain("your text here")
for frame in effect:
# do something with the string
...
```
In the event you want to allow TTE to handle the terminal setup/teardown, cursor positioning, and animation frame rate, a terminal_output() context manager is available.
```python
from terminaltexteffects.effects import effect_rain
effect = effect_rain.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](https://chrisbuilds.github.io/terminaltexteffects/libguide/).
### Effect Showcase
Note: Below you'll find a subset of the built-in effects.
View all of the effects and related information in the [Effects Showroom](https://chrisbuilds.github.io/terminaltexteffects/showroom/).
#### Beams
#### Binarypath
#### Blackhole
#### Bubbles
#### Burn
#### Decrypt
#### Fireworks
#### Orbittingvolley
#### Pour
#### Print
#### Rain
#### Rings
#### Slide
#### Spotlights
#### Swarm
#### VHSTape
#### Waves
## In-Development Preview
Any effects shown below are in development and will be available in the next release.
## Latest Release Notes
## 0.9.1
---
### New Features (0.9.1)
---
#### New Engine Features (0.9.1)
* Terminal dimension auto-detection supports automatically detecting a single dimensions.
### Changes (0.9.1)
---
#### Effects Changes (0.9.1)
* All effects have been updated to use the new `update()` method and `frame` property of
`base_effect.BaseEffectIterator`. See Engine Changes for more info.
#### Engine Changes (0.9.1)
* `base_effect.BaseEffectIterator` now has an `update()` method which calls the `tick()` method of all active characters
and manages the `active_characters` list.
* `base_effect.BaseEffectIterator` has a `frame` property which calls `Terminal.get_formatted_output_string()` and
returns the string.
* `TerminalConfig.terminal_dimensions` has been split into `TerminalConfig.terminal_width` and
`TerminalConfig.terminal_height` to simply the command line argument for dimensions and make it more obvious which
dimensions is being specified when interacting with `effect.terminal_config`.
#### Other Changes (0.9.1)
* Updated help output for `--terminal-dimensions` argument.
### Bug Fixes (0.9.1)
---
#### Engine Fixes (0.9.1)
* Fixed division by zero error when the terminal height was set to 1.
## License
Distributed under the MIT License. See [LICENSE](https://github.com/ChrisBuilds/terminaltexteffects/blob/main/LICENSE.md) for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "terminaltexteffects",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Chris",
"author_email": "741258@pm.me",
"download_url": "https://files.pythonhosted.org/packages/db/eb/7185b1690fc2e1cfe3412bd29c45e35877e8ff29ba9aa3973ce7629e64c2/terminaltexteffects-0.9.2.tar.gz",
"platform": null,
"description": "<br/>\n<p align=\"center\">\n <a href=\"https://github.com/ChrisBuilds/terminaltexteffects\">\n <img src=\"https://github.com/ChrisBuilds/terminaltexteffects/assets/57874186/66388e57-e95e-4619-b804-1d8d7ebd124f\" alt=\"TTE\" width=\"80\" height=\"80\">\n </a>\n\n <h3 align=\"center\">Terminal Text Effects</h3>\n\n <p align=\"center\">\n Inline Visual Effects in the Terminal\n <br/>\n <br/>\n </p>\n</p>\n\n[](http://pypi.org/project/terminaltexteffects/ \"\")  [](https://youtu.be/eWnYlxOREu4?t=1549) \n\n## Table Of Contents\n\n* [About](#tte)\n* [Requirements](#requirements)\n* [Installation](#installation)\n* [Usage (Application)](#application-quickstart)\n* [Usage (Library)](#library-quickstart)\n* [Effect Showcase](#effect-showcase)\n* [In-Development Preview](#in-development-preview)\n* [Latest Release Notes](#latest-release-notes)\n* [License](#license)\n\n## TTE\n\n\n\nTerminalTextEffects (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:\n\n* Xterm 256 / RGB hex color support\n* Complex character movement via Paths, Waypoints, and\n motion easing, with support for quadratic/cubic bezier curves.\n* Complex animations via Scenes with symbol/color changes,\n layers, easing, and Path synced progression.\n* Variable stop/step color gradient generation.\n* Event handling for Path/Scene state changes with\n custom callback support and many pre-defined actions.\n* Effect customization exposed through a typed effect configuration\n dataclass that is automatically handled as CLI arguments.\n* Runs inline, preserving terminal state and workflow.\n\n## Requirements\n\nTerminalTextEffects is written in Python and does not require any 3rd party modules. Terminal interactions use standard ANSI terminal sequences and should work in most modern terminals.\n\nNote: Windows Terminal performance is slow for some effects.\n\n## Installation\n\n```pip install terminaltexteffects```\nOR\n```pipx install terminaltexteffects```\n\n## Usage\n\nView the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for a full installation and usage guide.\n\n### Application Quickstart\n\n#### Options\n\n<details>\n\n<summary>TTE Command Line Options</summary>\n\n```markdown\noptions:\n -h, --help show this help message and exit\n --tab-width (int > 0)\n Number of spaces to use for a tab character. (default: 4)\n --xterm-colors Convert any colors specified in RBG hex to the closest XTerm-256 color. (default: False)\n --no-color Disable all colors in the effect. (default: False)\n --wrap-text Wrap text wider than the output area width. (default: False)\n --frame-rate FRAME_RATE\n Target frame rate for the animation. (default: 100)\n --terminal-width TERMINAL_WIDTH\n Terminal width, if set to 0 the terminal width is detected automatically. (default: 0)\n --terminal-height TERMINAL_HEIGHT\n Terminal height, if set to 0 the terminal height is detected automatically. (default: 0)\n --ignore-terminal-dimensions\n Ignore the terminal dimensions and use the input data dimensions for the output area. (default: False)\n\nEffect:\n Name of the effect to apply. Use <effect> -h for effect specific help.\n\n {beams,binarypath,blackhole,bouncyballs,bubbles,burn,crumble,decrypt,errorcorrect,expand,fireworks,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slide,spotlights,spray,swarm,synthgrid,unstable,verticalslice,vhstape,waves,wipe}\n Available Effects\n beams Create beams which travel over the output area illuminating the characters behind them.\n binarypath Binary representations of each character move through the terminal towards the home coordinate of the character.\n blackhole Characters are consumed by a black hole and explode outwards.\n bouncyballs Characters are bouncy balls falling from the top of the output area.\n bubbles Characters are formed into bubbles that float down and pop.\n burn Burns vertically in the output area.\n crumble Characters lose color and crumble into dust, vacuumed up, and reformed.\n decrypt Display a movie style decryption effect.\n errorcorrect Some characters start in the wrong position and are corrected in sequence.\n expand Expands the text from a single point.\n fireworks Characters launch and explode like fireworks and fall into place.\n middleout Text expands in a single row or column in the middle of the output area then out.\n orbittingvolley Four launchers orbit the output area firing volleys of characters inward to build the input text from the center out.\n overflow Input text overflows ands scrolls the terminal in a random order until eventually appearing ordered.\n pour Pours the characters into position from the given direction.\n print Lines are printed one at a time following a print head. Print head performs line feed, carriage return.\n rain Rain characters from the top of the output area.\n randomsequence Prints the input data in a random sequence.\n rings Characters are dispersed and form into spinning rings.\n scattered Text is scattered across the output area and moves into position.\n slide Slide characters into view from outside the terminal.\n spotlights Spotlights search the text area, illuminating characters, before converging in the center and expanding.\n spray Draws the characters spawning at varying rates from a single point.\n swarm Characters are grouped into swarms and move around the terminal before settling into position.\n synthgrid Create a grid which fills with characters dissolving into the final text.\n unstable Spawn characters jumbled, explode them to the edge of the output area, then reassemble them in the correct layout.\n verticalslice Slices the input in half vertically and slides it into place from opposite directions.\n vhstape Lines of characters glitch left and right and lose detail like an old VHS tape.\n waves Waves travel across the terminal leaving behind the characters.\n wipe Wipes the text across the terminal to reveal characters.\n\nEx: ls -a | python -m terminaltexteffects decrypt --typing-speed 2 --ciphertext-colors 008000 00cb00 00ff00 --final-gradient-stops eda000 --final-gradient-steps 12 --final-gradient-direction vertical\n```\n\n</details>\n\n```cat your_text | tte <effect> [options]```\n\nOR\n\n```cat your_text | python -m terminaltexteffects <effect> [options]```\n\n* Use ```<effect> -h``` to view options for a specific effect, such as color or movement direction.\n * Ex: ```tte decrypt -h```\n\nFor more information, view the [Application Usage Guide](https://chrisbuilds.github.io/terminaltexteffects/appguide/).\n\n### Library Quickstart\n\nAll 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.\n\n```python\nfrom terminaltexteffects.effects import effect_rain\n\neffect = effect_rain.Rain(\"your text here\")\n\nfor frame in effect:\n # do something with the string\n ...\n```\n\nIn the event you want to allow TTE to handle the terminal setup/teardown, cursor positioning, and animation frame rate, a terminal_output() context manager is available.\n\n```python\nfrom terminaltexteffects.effects import effect_rain\n\neffect = effect_rain.Rain(\"your text here\")\nwith effect.terminal_output() as terminal:\n for frame in effect:\n terminal.print(frame)\n```\n\nFor more information, view the [Library Usage Guide](https://chrisbuilds.github.io/terminaltexteffects/libguide/).\n\n### Effect Showcase\n\nNote: Below you'll find a subset of the built-in effects.\n\nView all of the effects and related information in the [Effects Showroom](https://chrisbuilds.github.io/terminaltexteffects/showroom/).\n\n#### Beams\n\n\n\n#### Binarypath\n\n\n\n#### Blackhole\n\n\n\n#### Bubbles\n\n\n\n#### Burn\n\n\n\n#### Decrypt\n\n\n\n#### Fireworks\n\n\n\n#### Orbittingvolley\n\n\n\n#### Pour\n\n\n\n#### Print\n\n\n\n#### Rain\n\n\n\n#### Rings\n\n\n\n#### Slide\n\n\n\n#### Spotlights\n\n\n\n#### Swarm\n\n\n\n#### VHSTape\n\n\n\n#### Waves\n\n\n\n## In-Development Preview\n\nAny effects shown below are in development and will be available in the next release.\n\n## Latest Release Notes\n\n## 0.9.1\n\n---\n\n### New Features (0.9.1)\n\n---\n\n#### New Engine Features (0.9.1)\n\n* Terminal dimension auto-detection supports automatically detecting a single dimensions.\n\n### Changes (0.9.1)\n\n---\n\n#### Effects Changes (0.9.1)\n\n* All effects have been updated to use the new `update()` method and `frame` property of\n `base_effect.BaseEffectIterator`. See Engine Changes for more info.\n\n#### Engine Changes (0.9.1)\n\n* `base_effect.BaseEffectIterator` now has an `update()` method which calls the `tick()` method of all active characters\n and manages the `active_characters` list.\n* `base_effect.BaseEffectIterator` has a `frame` property which calls `Terminal.get_formatted_output_string()` and\n returns the string.\n* `TerminalConfig.terminal_dimensions` has been split into `TerminalConfig.terminal_width` and\n `TerminalConfig.terminal_height` to simply the command line argument for dimensions and make it more obvious which\n dimensions is being specified when interacting with `effect.terminal_config`.\n\n#### Other Changes (0.9.1)\n\n* Updated help output for `--terminal-dimensions` argument.\n\n### Bug Fixes (0.9.1)\n\n---\n\n#### Engine Fixes (0.9.1)\n\n* Fixed division by zero error when the terminal height was set to 1.\n\n## License\n\nDistributed under the MIT License. See [LICENSE](https://github.com/ChrisBuilds/terminaltexteffects/blob/main/LICENSE.md) for more information.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A collection of visual effects that can be applied to terminal piped stdin text.",
"version": "0.9.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "235f9b3c665e202d04710f48a78e8d1d41208c4d90142437b036182076a8cdac",
"md5": "66cb68fba4a639dda159a34e5ebe7b10",
"sha256": "12a2f0c0fc67d44d2d090b8e91e6693ca4ff176eea7fb4d01da3bac9362a22ad"
},
"downloads": -1,
"filename": "terminaltexteffects-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66cb68fba4a639dda159a34e5ebe7b10",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 140886,
"upload_time": "2024-05-11T12:15:04",
"upload_time_iso_8601": "2024-05-11T12:15:04.799486Z",
"url": "https://files.pythonhosted.org/packages/23/5f/9b3c665e202d04710f48a78e8d1d41208c4d90142437b036182076a8cdac/terminaltexteffects-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbeb7185b1690fc2e1cfe3412bd29c45e35877e8ff29ba9aa3973ce7629e64c2",
"md5": "ff8127012e47bf664cf6012d8aedb496",
"sha256": "a0aaacf69275575c9648e67c3bcb5dee9213c3e10d1bda83bb276af01cac9dcb"
},
"downloads": -1,
"filename": "terminaltexteffects-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "ff8127012e47bf664cf6012d8aedb496",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 92730,
"upload_time": "2024-05-11T12:15:06",
"upload_time_iso_8601": "2024-05-11T12:15:06.408179Z",
"url": "https://files.pythonhosted.org/packages/db/eb/7185b1690fc2e1cfe3412bd29c45e35877e8ff29ba9aa3973ce7629e64c2/terminaltexteffects-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-11 12:15:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "terminaltexteffects"
}
