Skip to content

Matrix

Demo

Quick Start

matrix.py
from terminaltexteffects.effects.effect_matrix import Matrix

effect = Matrix("YourTextHere\n" * 10)
with effect.terminal_output() as terminal:
    for frame in effect:
        terminal.print(frame)

Matrix digital rain effect.

Classes:

Name Description
Matrix

Matrix digital rain effect.
MatrixConfig

Configuration for the Matrix effect.
MatrixIterator

Iterator for the Matrix effect. Does not normally need to be called directly.

Matrix

Bases: BaseEffect[MatrixConfig]

Matrix digital rain effect.

Attributes:

Name Type Description
effect_config MatrixConfig

Configuration for the Matrix effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_matrix.py 
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
class Matrix(BaseEffect[MatrixConfig]):
    """Matrix digital rain effect.

    Attributes:
        effect_config (MatrixConfig): Configuration for the Matrix effect.
        terminal_config (TerminalConfig): Configuration for the terminal."""

    _config_cls = MatrixConfig
    _iterator_cls = MatrixIterator

    def __init__(self, input_data: str) -> None:
        """Initialize the effect with the provided input data.

        Args:
            input_data (str): The input data to use for the effect."""
        super().__init__(input_data)

__init__(input_data)

Initialize the effect with the provided input data.

Parameters:

Name Type Description Default
input_data str

The input data to use for the effect.

 required
Source code in terminaltexteffects/effects/effect_matrix.py 
485
486
487
488
489
490
def __init__(self, input_data: str) -> None:
    """Initialize the effect with the provided input data.

    Args:
        input_data (str): The input data to use for the effect."""
    super().__init__(input_data)

MatrixConfig dataclass

Bases: ArgsDataClass

Configuration for the Matrix effect.

Attributes:

Name Type Description
highlight_color Color

Color for the bottom of the rain column.
rain_color_gradient tuple[Color, ...]

Tuple of colors for the rain gradient. If only one color is provided, the characters will be displayed in that color.
rain_symbols tuple[str, ...]

Tuple of symbols to use for the rain.
rain_fall_delay_range tuple[int, int]

Speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range.
rain_column_delay_range tuple[int, int]

Range of frames to wait between adding new rain columns.
rain_time int

Time, in seconds, to display the rain effect before transitioning to the input text.
symbol_swap_chance float

Chance of swapping a character's symbol on each tick.
color_swap_chance float

Chance of swapping a character's color on each tick.
resolve_delay int

Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase.
final_gradient_stops tuple[Color, ...]

Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.
final_gradient_steps tuple[int, ...] | int

Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation.
final_gradient_frames int

Number of frames to display each gradient step. Increase to slow down the gradient animation.
final_gradient_direction Direction

Direction of the final gradient.
Source code in terminaltexteffects/effects/effect_matrix.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
@argclass(
    name="matrix",
    help="Matrix digital rain effect.",
    description="matrix | Matrix digital rain effect.",
    epilog="""Example: tte matrix --rain-color-gradient 92be92 185318 --rain-symbols 2 5 9 8 Z : . = + - ¦ _ --rain-fall-delay-range 8-25 --rain-column-delay-range 5-15 --rain-time 15 --symbol-swap-chance 0.005 --color-swap-chance 0.001 --resolve-delay 5 --final-gradient-stops 389c38 --final-gradient-steps 12 --final-gradient-frames 5 --final-gradient-direction vertical --highlight-color dbffdb""",
)
@dataclass
class MatrixConfig(ArgsDataClass):
    """Configuration for the Matrix effect.

    Attributes:
        highlight_color (Color): Color for the bottom of the rain column.
        rain_color_gradient (tuple[Color, ...]): Tuple of colors for the rain gradient. If only one color is provided, the characters will be displayed in that color.
        rain_symbols (tuple[str, ...]): Tuple of symbols to use for the rain.
        rain_fall_delay_range (tuple[int, int]): Speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range.
        rain_column_delay_range (tuple[int, int]): Range of frames to wait between adding new rain columns.
        rain_time (int): Time, in seconds, to display the rain effect before transitioning to the input text.
        symbol_swap_chance (float): Chance of swapping a character's symbol on each tick.
        color_swap_chance (float): Chance of swapping a character's color on each tick.
        resolve_delay (int): Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase.
        final_gradient_stops (tuple[Color, ...]): Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.
        final_gradient_steps (tuple[int, ...] | int): Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation.
        final_gradient_frames (int): Number of frames to display each gradient step. Increase to slow down the gradient animation.
        final_gradient_direction (Gradient.Direction): Direction of the final gradient.
    """

    highlight_color: Color = ArgField(
        cmd_name=["--highlight-color"],
        type_parser=argvalidators.ColorArg.type_parser,
        default=Color("dbffdb"),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Color for the bottom of the rain column.",
    )  # type: ignore[assignment]
    "Color : Color for the bottom of the rain column."

    rain_color_gradient: tuple[Color, ...] = ArgField(
        cmd_name=["--rain-color-gradient"],
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("92be92"), Color("185318")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the rain gradient. Colors are selected from the gradient randomly. If only one color is provided, the characters will be displayed in that color.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors for the rain gradient. If only one color is provided, the characters will be displayed in that color."

    rain_symbols: tuple[str, ...] = ArgField(
        cmd_name=["--rain-symbols"],
        nargs="+",
        type_parser=argvalidators.Symbol.type_parser,
        default=MATRIX_SYMBOLS_COMMON + MATRIX_SYMBOLS_KATA,
        metavar=argvalidators.Symbol.METAVAR,
        help="Space separated, unquoted, list of symbols to use for the rain.",
    )  # type: ignore[assignment]
    "tuple[str, ...] : Tuple of symbols to use for the rain."

    rain_fall_delay_range: tuple[int, int] = ArgField(
        cmd_name=["--rain-fall-delay-range"],
        type_parser=argvalidators.IntRange.type_parser,
        default=(3, 25),
        metavar=argvalidators.IntRange.METAVAR,
        help="Range for the speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range.",
    )  # type: ignore[assignment]
    "tuple[int, int] : Speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range."

    rain_column_delay_range: tuple[int, int] = ArgField(
        cmd_name=["--rain-column-delay-range"],
        type_parser=argvalidators.IntRange.type_parser,
        default=(5, 15),
        metavar=argvalidators.IntRange.METAVAR,
        help="Range of frames to wait between adding new rain columns.",
    )  # type: ignore[assignment]
    "tuple[int, int] : Range of frames to wait between adding new rain columns."

    rain_time: int = ArgField(
        cmd_name="--rain-time",
        type_parser=argvalidators.PositiveInt.type_parser,
        default=15,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Time, in seconds, to display the rain effect before transitioning to the input text.",
    )  # type: ignore[assignment]
    "int : Time, in seconds, to display the rain effect before transitioning to the input text."

    symbol_swap_chance: float = ArgField(
        cmd_name="--symbol-swap-chance",
        type_parser=argvalidators.PositiveFloat.type_parser,
        default=0.005,
        metavar=argvalidators.PositiveFloat.METAVAR,
        help="Chance of swapping a character's symbol on each tick.",
    )  # type: ignore[assignment]
    "float : Chance of swapping a character's symbol on each tick."

    color_swap_chance: float = ArgField(
        cmd_name="--color-swap-chance",
        type_parser=argvalidators.PositiveFloat.type_parser,
        default=0.001,
        metavar=argvalidators.PositiveFloat.METAVAR,
        help="Chance of swapping a character's color on each tick.",
    )  # type: ignore[assignment]
    "float : Chance of swapping a character's color on each tick."

    resolve_delay: int = ArgField(
        cmd_name="--resolve-delay",
        type_parser=argvalidators.PositiveInt.type_parser,
        default=5,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase.",
    )  # type: ignore[assignment]
    "int : Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase."

    final_gradient_stops: tuple[Color, ...] = ArgField(
        cmd_name=["--final-gradient-stops"],
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("92be92"), Color("336b33")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the character gradient (applied from bottom to top). If only one color is provided, the characters will be displayed in that color.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color."

    final_gradient_steps: tuple[int, ...] | int = ArgField(
        cmd_name="--final-gradient-steps",
        type_parser=argvalidators.PositiveInt.type_parser,
        nargs="+",
        default=12,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation.",
    )  # type: ignore[assignment]
    "tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation."

    final_gradient_frames: int = ArgField(
        cmd_name="--final-gradient-frames",
        type_parser=argvalidators.PositiveInt.type_parser,
        default=5,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Number of frames to display each gradient step. Increase to slow down the gradient animation.",
    )  # type: ignore[assignment]
    "int : Number of frames to display each gradient step. Increase to slow down the gradient animation."

    final_gradient_direction: Gradient.Direction = ArgField(
        cmd_name="--final-gradient-direction",
        type_parser=argvalidators.GradientDirection.type_parser,
        default=Gradient.Direction.RADIAL,
        metavar=argvalidators.GradientDirection.METAVAR,
        help="Direction of the final gradient.",
    )  # type: ignore[assignment]
    "Gradient.Direction : Direction of the final gradient."

    @classmethod
    def get_effect_class(cls):
        return Matrix

color_swap_chance: float = ArgField(cmd_name='--color-swap-chance', type_parser=argvalidators.PositiveFloat.type_parser, default=0.001, metavar=argvalidators.PositiveFloat.METAVAR, help="Chance of swapping a character's color on each tick.") class-attribute instance-attribute

float : Chance of swapping a character's color on each tick.

final_gradient_direction: Gradient.Direction = ArgField(cmd_name='--final-gradient-direction', type_parser=argvalidators.GradientDirection.type_parser, default=Gradient.Direction.RADIAL, metavar=argvalidators.GradientDirection.METAVAR, help='Direction of the final gradient.') class-attribute instance-attribute

Gradient.Direction : Direction of the final gradient.

final_gradient_frames: int = ArgField(cmd_name='--final-gradient-frames', type_parser=argvalidators.PositiveInt.type_parser, default=5, metavar=argvalidators.PositiveInt.METAVAR, help='Number of frames to display each gradient step. Increase to slow down the gradient animation.') class-attribute instance-attribute

int : Number of frames to display each gradient step. Increase to slow down the gradient animation.

final_gradient_steps: tuple[int, ...] | int = ArgField(cmd_name='--final-gradient-steps', type_parser=argvalidators.PositiveInt.type_parser, nargs='+', default=12, metavar=argvalidators.PositiveInt.METAVAR, help='Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation.') class-attribute instance-attribute

tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation.

final_gradient_stops: tuple[Color, ...] = ArgField(cmd_name=['--final-gradient-stops'], type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('92be92'), Color('336b33')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the character gradient (applied from bottom to top). If only one color is provided, the characters will be displayed in that color.') class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.

highlight_color: Color = ArgField(cmd_name=['--highlight-color'], type_parser=argvalidators.ColorArg.type_parser, default=Color('dbffdb'), metavar=argvalidators.ColorArg.METAVAR, help='Color for the bottom of the rain column.') class-attribute instance-attribute

Color : Color for the bottom of the rain column.

rain_color_gradient: tuple[Color, ...] = ArgField(cmd_name=['--rain-color-gradient'], type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('92be92'), Color('185318')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the rain gradient. Colors are selected from the gradient randomly. If only one color is provided, the characters will be displayed in that color.') class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors for the rain gradient. If only one color is provided, the characters will be displayed in that color.

rain_column_delay_range: tuple[int, int] = ArgField(cmd_name=['--rain-column-delay-range'], type_parser=argvalidators.IntRange.type_parser, default=(5, 15), metavar=argvalidators.IntRange.METAVAR, help='Range of frames to wait between adding new rain columns.') class-attribute instance-attribute

tuple[int, int] : Range of frames to wait between adding new rain columns.

rain_fall_delay_range: tuple[int, int] = ArgField(cmd_name=['--rain-fall-delay-range'], type_parser=argvalidators.IntRange.type_parser, default=(3, 25), metavar=argvalidators.IntRange.METAVAR, help='Range for the speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range.') class-attribute instance-attribute

tuple[int, int] : Speed of the falling rain as determined by the delay between rows. Actual delay is randomly selected from the range.

rain_symbols: tuple[str, ...] = ArgField(cmd_name=['--rain-symbols'], nargs='+', type_parser=argvalidators.Symbol.type_parser, default=MATRIX_SYMBOLS_COMMON + MATRIX_SYMBOLS_KATA, metavar=argvalidators.Symbol.METAVAR, help='Space separated, unquoted, list of symbols to use for the rain.') class-attribute instance-attribute

tuple[str, ...] : Tuple of symbols to use for the rain.

rain_time: int = ArgField(cmd_name='--rain-time', type_parser=argvalidators.PositiveInt.type_parser, default=15, metavar=argvalidators.PositiveInt.METAVAR, help='Time, in seconds, to display the rain effect before transitioning to the input text.') class-attribute instance-attribute

int : Time, in seconds, to display the rain effect before transitioning to the input text.

resolve_delay: int = ArgField(cmd_name='--resolve-delay', type_parser=argvalidators.PositiveInt.type_parser, default=5, metavar=argvalidators.PositiveInt.METAVAR, help='Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase.') class-attribute instance-attribute

int : Number of frames to wait between resolving the next group of characters. This is used to adjust the speed of the final resolve phase.

symbol_swap_chance: float = ArgField(cmd_name='--symbol-swap-chance', type_parser=argvalidators.PositiveFloat.type_parser, default=0.005, metavar=argvalidators.PositiveFloat.METAVAR, help="Chance of swapping a character's symbol on each tick.") class-attribute instance-attribute

float : Chance of swapping a character's symbol on each tick.