CHAFA(1)

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>.