1CHAFA(1) User Commands CHAFA(1)
2
6 chafa - Character art facsimile generator
7
9 chafa [OPTION...] [IMAGE...]
10
12 chafa is a utility that converts all kinds of images, including
13 animated GIFs, into (potentially animated) ANSI/Unicode character
14 output that can be displayed in a terminal. It supports alpha
15 transparency and multiple color modes and color spaces, and combines a
16 range of Unicode characters for optimal output.
17 You can specify one or more input files, but the default behavior is
19 slightly different with multiple files -- for instance, animations will
20 not loop forever when there is more than one input file.
21
23 --bg color
24 Background color of display (color name or hex). Partially
25 transparent input will be blended with this color. Color names are
26 based on those provided with X.Org. Defaults to black.
27 --clear
29 Clear screen before processing each file.
30 -c mode, --colors mode
32 Set output color mode; one of [none, 2, 8, 16, 240, 256, full].
33 Defaults to full (24-bit). The 240-color mode is recommended over
34 the 256-color one, since the lower 16 colors are unreliable and
35 tend to differ between terminals. 16-color mode will use aixterm
36 extensions to produce 16 foreground and background colors. 2-color
37 mode will only emit the ANSI codes for reverse color and attribute
38 reset, while "none" will emit no ANSI color codes whatsoever.
39 In sixel mode, "full" will dynamically generate a 256-color palette
41 for each image or animation frame. The other modes refer to
42 built-in palettes. "none" and "2" are interchangeable and will use
43 the specified foreground/background colors (see --fg and --bg).
44 --color-extractor extractor
46 Method for extracting color from an area; one of [average, median].
47 Median normally produces crisper output, while average may perform
48 better on noisy images. Defaults to average.
49 --color-space cs
51 Color space used for quantization; one of [rgb, din99d]. Defaults
52 to rgb, which is faster but less accurate.
53 --dither type
55 Type of dithering to apply during quantization. One of [none,
56 ordered, diffusion]. "Bayer" is a synonym for "ordered", and "fs"
57 (Floyd-Steinberg) is a synonym for "diffusion".
58 --dither-grain widthxheight
60 Dimensions of grain used when dithering. Specified as width x
61 height, where each can be one of [1, 2, 4, 8] pixels. One character
62 cell is by definition 8 pixels across in both dimensions. Defaults
63 to 4x4 in symbol mode and 1x1 in sixel mode.
64 --dither-intensity intensity
66 Intensity of dithering pattern. Ranges from 0.0 to infinity, with
67 1.0 considered neutral. Lower values tend to reduce the amount of
68 dithering done, while higher values increase it. In practice,
69 values higher than 10.0 are unlikely to produce useful results.
70 -d, --duration seconds
72 Time to show each file, in seconds. Defaults to zero for still
73 images and for animations when multiple files are specified. If a
74 single animation is specified, defaults to infinite. Animations
75 will always be played through at least once, even if duration is
76 e.g. zero.
77 --fg color
79 Foreground color of display (color name or hex). Together with the
80 background color specified by --bg, this specifies the terminal's
81 palette in color modes 2 and none. Color names are based on those
82 provided with X.Org. Defaults to white.
83 --fg-only
85 Leave the background color untouched. This produces character-cell
86 output using foreground colors only, and will avoid resetting or
87 inverting the colors.
88 --fill symbols
90 Specify character symbols to use for fill/gradients. Defaults to
91 none. Usage is similar to that of --symbols; see below.
92 --font-ratio width/height
94 Target font's width/height ratio. Can be specified as a real number
95 or a fraction. Defaults to 1/2.
96 -f, --format format
98 Set output format; one of [iterm, kitty, sixels, symbols]. The
99 default is iterm, kitty or sixels if the connected terminal
100 supports one of these, falling back to symbols ("ANSI art")
101 otherwise.
102 --glyph-file file
104 Load glyph information from file, which can be any font file
105 supported by FreeType (TTF, PCF, etc). The glyph outlines will
106 replace any existing outlines, including builtins. Useful in symbol
107 mode for custom font support or for improving quality with a
108 specific font. Note that this only makes sense if the output
109 terminal is using a matching font. Can be specified multiple times.
110 -h, --help
112 Show a brief help text.
113 --invert
115 Invert video. For display with bright backgrounds in color modes 2
116 and none. Swaps --fg and --bg.
117 -O num, --optimize num
119 Compress the output by using control sequences intelligently [0-9].
120 0 disables, 9 enables every available optimization. Defaults to 5,
121 except for when used with "-c none", where it defaults to 0.
122 -p bool, --preprocess bool
124 Image preprocessing [on, off]. Defaults to on with 16 colors or
125 lower, off otherwise. This enhances colors and contrast prior to
126 conversion, which can be useful in low-color modes.
127 -s widthxheight, --size widthxheight
129 Set maximum output dimensions in columns and rows. By default this
130 will be the size of your terminal, or 80x25 if size detection
131 fails.
132 --speed speed
134 Set the speed animations will play at. This can be either a
135 unitless multiplier (fractions are allowed), or a real number
136 followed by "fps" to apply a specific framerate.
137 --stretch
139 Stretch image to fit output dimensions; ignore aspect. Implies
140 --zoom.
141 --symbols symbols
143 Specify character symbols to employ in final output. See below for
144 full usage and a list of symbol classes.
145 -t threshold, --threshold threshold
147 Threshold above which full transparency will be used [0.0 - 1.0].
148 Setting this to 0.0 will render a blank image, while a value of 1.0
149 will replace any transparency with the background color
150 (configurable with --bg).
151 --version
153 Show version, feature and copyright information.
154 --watch
156 Watch a single input file, redisplaying it whenever its contents
157 change. Will run until manually interrupted or, if --duration is
158 set, until it expires.
159 -w num, --work num
161 How hard to work in terms of CPU and memory [1-9]. 1 is the
162 cheapest, 9 is the most accurate. Defaults to 5.
163 --zoom
165 Allow scaling up beyond one character per pixel.
166
168 Accepted classes for --symbols are [all, none, space, solid, stipple,
169 block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted,
170 braille, technical, geometric, ascii, legacy, sextant, wedge, wide,
171 narrow]. Some symbols belong to multiple classes, e.g. diagonals are
172 also borders.
173 You can specify a list of classes separated by commas, or prefix them
175 with + and - to add or remove symbols relative to the existing set. The
176 ordering is significant.
177 The default symbol set is block+border+space-wide-inverted for all
179 modes except "none", which uses block+border+space-wide (including
180 inverse symbols).
181
183 chafa in.gif
184 Show a potentially animated GIF image in the terminal. If this is
185 an animation, it will run until the user generates an interrupt
186 (typically ctrl-c). All parameters will be autodetected based on
187 the current environment.
188 chafa -c full -s 200 in.gif
190 Like the above, but force truecolor output that is 200 characters
191 wide and calculate the height preserving the aspect of the original
192 image.
193 chafa -c 16 --color-space din99d --symbols -dot in.jpg
195 Generate 16-color output with perceptual color picking and avoid
196 using dot symbols.
197 chafa -c none --symbols block+border-solid in.png
199 Generate uncolored output using block and border symbols, but avoid
200 the solid block symbol.
201
203 See the Chafa homepage[1] for more information.
204
206 Written by Hans Petter Jansson[2] <hpj@hpjansson.org>.
207
209 1. Chafa homepage
210 https://hpjansson.org/chafa/
211 2. Hans Petter Jansson
213 https://hpjansson.org/
214chafa CHAFA(1)