chafa (1) - Linux Manuals

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.

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

--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. 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 [at] copyleft.no>.