NAME¶
chafa - Character art facsimile generator
SYNOPSIS¶
chafa [OPTION...] [IMAGE...]
DESCRIPTION¶
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
output.
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.
OPTIONS¶
--bg color
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
Clear screen before processing each file.
-c mode, --colors
mode
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 cs
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
once.
--fg color
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.
--fill symbols
Specify character symbols to use for fill/gradients.
Defaults to none. Usage is similar to that of --symbols; see below.
--font-ratio
width/height
Target font's width/height ratio. Can be specified as a
real number or a fraction. Defaults to 1/2.
-h, --help
Show a brief help text.
--invert
Invert video. For display with bright backgrounds in
color modes 2 and none. Swaps --fg and --bg.
-p bool, --preprocess
bool
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.
-s widthxheight,
--size widthxheight
Set maximum output dimensions in columns and rows. By
default this will be the size of your terminal, or 80x25 if size detection
fails.
--stretch
Stretch image to fit output dimensions; ignore aspect.
Implies --zoom.
--symbols symbols
Specify character symbols to employ in final output. See
below for full usage and a list of symbol classes.
-t threshold, --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
--bg).
--version
Show version, feature and copyright information.
--watch
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.
--zoom
Allow scaling up beyond one character per pixel.
SYMBOLS¶
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
also borders.
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.
EXAMPLES¶
chafa in.gif
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
environment.
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
image.
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.
AUTHOR¶
Written by Hans Petter Jansson <hpj@copyleft.no>.
