chafa - Character art facsimile generator
chafa [OPTION...] [IMAGE...]
chafa is a utility that converts all kinds of images, including animated
GIFs, into (potentially animated) ANSI/Unicode character output that can be
displayed in a terminal. It supports alpha transparency and multiple color
modes and color spaces, and combines a range of Unicode characters for optimal
You can specify one or more input files, but the default behavior
is slightly different with multiple files -- for instance, animations will
not loop forever when there is more than one input file.
Background color of display (color name or hex).
Partially transparent input will be blended with this color. Color names are
based on those provided with X.Org. Defaults to black.
Clear screen before processing each file.
-c mode, --colors
Set output color mode; one of [none, 2, 16, 240, 256,
full]. Defaults to full (24-bit). The 240-color mode is recommended over the
256-color one, since the lower 16 colors are unreliable and tend to differ
between terminals. 16-color mode will use aixterm extensions to produce 16
foreground and background colors. 2-color mode will only emit the ANSI codes
for reverse color and attribute reset, while "none" will emit no
ANSI color codes whatsoever.
Color space used for quantization; one of [rgb, din99d].
Defaults to rgb, which is faster but less accurate.
-d, --duration seconds
Time to show each file. If showing a single file,
defaults to zero for a still image and infinite for an animation. For multiple
files, defaults to 3.0. Animations will always be played through at least
Foreground color of display (color name or hex). Together
with the background color specified by --bg, this specifies the terminal's
palette in color modes 2 and none. Color names are based on those provided
with X.Org. Defaults to white.
Specify character symbols to use for fill/gradients.
Defaults to none. Usage is similar to that of --symbols; see below.
Target font's width/height ratio. Can be specified as a
real number or a fraction. Defaults to 1/2.
Show a brief help text.
Invert video. For display with bright backgrounds in
color modes 2 and none. Swaps --fg and --bg.
-p bool, --preprocess
Image preprocessing [on, off]. Defaults to on with 16
colors or lower, off otherwise. This enhances colors and contrast prior to
conversion, which can be useful in low-color modes.
Set maximum output dimensions in columns and rows. By
default this will be the size of your terminal, or 80x25 if size detection
Stretch image to fit output dimensions; ignore aspect.
Specify character symbols to employ in final output. See
below for full usage and a list of symbol classes.
-t threshold, --threshold
Threshold above which full transparency will be used [0.0
- 1.0]. Setting this to 0.0 will render a blank image, while a value of 1.0
will replace any transparency with the background color (configurable with
Show version, feature and copyright information.
Watch a single input file, redisplaying it whenever its
contents change. Will run until manually interrupted or, if --duration is set,
until it expires.
-w num, --work num
How hard to work in terms of CPU and memory [1-9]. 1 is
the cheapest, 9 is the most accurate. Defaults to 5.
Allow scaling up beyond one character per pixel.
Accepted classes for --symbols are [all, none, space, solid, stipple, block,
border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical,
geometric, ascii]. Some symbols belong to multiple classes, e.g. diagonals are
You can specify a list of classes separated by commas, or prefix
them with + and - to add or remove symbols relative to the existing set. The
ordering is significant.
The default symbol set is
all-stipple-braille-ascii+space-extra-inverted for all modes except for
"none", which uses all-stipple-braille-ascii+space-extra.
Show a potentially animated GIF image in the terminal. If
this is an animation, it will run until the user generates an interrupt
(typically ctrl-c). All parameters will be autodetected based on the current
chafa -c full -s 200 in.gif
Like the above, but force truecolor output that is 200
characters wide and calculate the height preserving the aspect of the original
chafa -c 16 --color-space din99d --symbols -dot in.jpg
Generate 16-color output with perceptual color picking
and avoid using dot symbols.
chafa -c none --symbols block+border-solid in.png
Generate uncolored output using block and border symbols,
but avoid the solid block symbol.
Written by Hans Petter Jansson <email@example.com>.