CHAFA(1)

NAME
chafa - Character art facsimile generator

SYNOPSIS

chafa [OPTION...] [IMAGE...]

DESCRIPTION

chafa is a command-line utility that converts image data, including animated GIFs, into graphics formats or ANSI/Unicode character art suitable for display in a terminal. It has broad feature support, allowing it to be used on devices ranging from historical teleprinters to modern terminal emulators and everything in between.

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

--animate bool
    Whether to allow animation [on, off]. Defaults to on. When off, will show a still frame from each animation.

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

-C bool, --center bool
    Center images [on, off]. Defaults to off.

--clear
    Clear screen before processing each file.

-c mode, --colors mode
    Set output color mode; one of [none, 2, 8, 16/8 16, 240, 256, full]. 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. The 16/8 mode allows for 8 colors plus another "bright" 8 colors in the foreground implemented with the "bold" escape sequence. 2-color mode will only emit the ANSI codes for reverse color and attribute reset, while "none" will emit no escape sequences at all.

    In sixel mode, "full" will dynamically generate a 256-color palette for each image or animation frame. The other modes refer to built-in palettes. "none" and "2" are interchangeable and will use the specified foreground/background colors (see --fg and --bg).

    If left unspecified, an optimal default will be chosen based on the current environment.

--color-extractor extractor
    Method for extracting color from an area; one of [average, median]. Median normally produces crisper output, while average may perform better on noisy images. Defaults to average.

--color-space cs
    Color space used for quantization; one of [rgb, din99d]. Defaults to rgb, which is faster but less accurate.

--dither type
    Type of dithering to apply during quantization. One of [none, ordered, diffusion]. "Bayer" is a synonym for "ordered", and "fs" (Floyd-Steinberg) is a synonym for "diffusion".

--dither-grain widthxheight
    Dimensions of grain used when dithering. Specified as width x height, where each can be one of [1, 2, 4, 8] pixels. One character cell is by definition 8 pixels across in both dimensions. Defaults to 4x4 in symbol mode and 1x1 in sixel mode.

--dither-intensity intensity
    Intensity of dithering pattern. Ranges from 0.0 to infinity, with 1.0 considered neutral. Lower values tend to reduce the amount of dithering done, while higher values increase it. In practice, values higher than 10.0 are unlikely to produce useful results.

-d, --duration seconds
    Time to show each file, in seconds. Defaults to zero for still images and for animations when multiple files are specified. If a single animation is specified, defaults to infinite. Animations will always be played through at least once, even if duration is e.g. zero.

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

--fg-only
    Leave the background color untouched. This produces character-cell output using foreground colors only, and will avoid resetting or inverting the colors.

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

-f, --format format
    Set output format; one of [iterm, kitty, sixels, symbols]. The default is iterm, kitty or sixels if the connected terminal supports one of these, falling back to symbols ("ANSI art") otherwise.

--glyph-file file
    Load glyph information from file, which can be any font file supported by FreeType (TTF, PCF, etc). The glyph outlines will replace any existing outlines, including builtins. Useful in symbol mode for custom font support or for improving quality with a specific font. Note that this only makes sense if the output terminal is using a matching font. Can be specified multiple times.

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

--margin-bottom num
    When terminal size is detected, reserve at least this many rows at the bottom as a safety margin. Can be used to prevent images from scrolling out. Defaults to 1.

--margin-right num
    When terminal size is detected, reserve at least this many columns on the right-hand side as a safety margin. Defaults to 0.

-O num, --optimize num
    Compress the output by using control sequences intelligently [0-9]. 0 disables, 9 enables every available optimization. Defaults to 5, except for when used with "-c none", where it defaults to 0.

--polite bool
    Polite mode [on, off]. Defaults to on. Turning this off may enhance presentation and prevent interference from other programs, but risks leaving the terminal in an altered state (rude).

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

--scale NUM
    Scale image, respecting terminal's maximum dimensions. 1.0 approximates original pixel dimensions. Specify "max" to use all available space. Defaults to 1.0 for pixel graphics and 4.0 for symbols.

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

--speed speed
    Set the speed animations will play at. This can be either a unitless multiplier (fractions are allowed), or a real number followed by "fps" to apply a specific framerate.

--stretch
    Stretch image to fit output dimensions; ignore aspect. Implies --scale max.

--symbols symbols
    Specify character symbols to employ in final output. See below for full usage and a list of symbol classes.

--threads num
    Maximum number of CPU threads to use. If left unspecified or negative, this will equal available CPU cores.

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

EXIT STATUS

chafa will return 0 on success, 1 on partial failure or 2 on complete failure (including when invoked with no arguments).
Status | Meaning
0 | Success
1 | Some files failed to display
2 | All files failed to display

SYMBOLS

Accepted classes for --symbols are [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical, geometric, ascii, legacy, sextant, wedge, wide, narrow]. 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 block+border+space-wide-inverted for all modes except "none", which uses block+border+space-wide (including inverse symbols).

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.

FURTHER READING

See the Chafa homepage[1] for more information.

AUTHOR

Written by Hans Petter Jansson[2] <hpj@hpjansson.org>.

NOTES

1.  Chafa homepage
    https://hpjansson.org/chafa/

2.  Hans Petter Jansson
    https://hpjansson.org/