1CHAFA(1) User Commands CHAFA(1)
2
6 chafa - Character art facsimile generator
7
9 chafa [OPTION...] [IMAGE...]
10
12 chafa is a command-line utility that converts image data, including
13 animated GIFs, into graphics formats or ANSI/Unicode character art
14 suitable for display in a terminal. It has broad feature support,
15 allowing it to be used on devices ranging from historical teleprinters
16 to modern terminal emulators and everything in between.
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 --animate bool
24 Whether to allow animation [on, off]. Defaults to on. When off,
25 will show a still frame from each animation.
26 --bg color
28 Background color of display (color name or hex). Partially
29 transparent input will be blended with this color. Color names are
30 based on those provided with X.Org. Defaults to black.
31 -C bool, --center bool
33 Center images [on, off]. Defaults to off.
34 --clear
36 Clear screen before processing each file.
37 -c mode, --colors mode
39 Set output color mode; one of [none, 2, 8, 16, 240, 256, full].
40 Defaults to full (24-bit). The 240-color mode is recommended over
41 the 256-color one, since the lower 16 colors are unreliable and
42 tend to differ between terminals. 16-color mode will use aixterm
43 extensions to produce 16 foreground and background colors. 2-color
44 mode will only emit the ANSI codes for reverse color and attribute
45 reset, while "none" will emit no ANSI color codes whatsoever.
46 In sixel mode, "full" will dynamically generate a 256-color palette
48 for each image or animation frame. The other modes refer to
49 built-in palettes. "none" and "2" are interchangeable and will use
50 the specified foreground/background colors (see --fg and --bg).
51 --color-extractor extractor
53 Method for extracting color from an area; one of [average, median].
54 Median normally produces crisper output, while average may perform
55 better on noisy images. Defaults to average.
56 --color-space cs
58 Color space used for quantization; one of [rgb, din99d]. Defaults
59 to rgb, which is faster but less accurate.
60 --dither type
62 Type of dithering to apply during quantization. One of [none,
63 ordered, diffusion]. "Bayer" is a synonym for "ordered", and "fs"
64 (Floyd-Steinberg) is a synonym for "diffusion".
65 --dither-grain widthxheight
67 Dimensions of grain used when dithering. Specified as width x
68 height, where each can be one of [1, 2, 4, 8] pixels. One character
69 cell is by definition 8 pixels across in both dimensions. Defaults
70 to 4x4 in symbol mode and 1x1 in sixel mode.
71 --dither-intensity intensity
73 Intensity of dithering pattern. Ranges from 0.0 to infinity, with
74 1.0 considered neutral. Lower values tend to reduce the amount of
75 dithering done, while higher values increase it. In practice,
76 values higher than 10.0 are unlikely to produce useful results.
77 -d, --duration seconds
79 Time to show each file, in seconds. Defaults to zero for still
80 images and for animations when multiple files are specified. If a
81 single animation is specified, defaults to infinite. Animations
82 will always be played through at least once, even if duration is
83 e.g. zero.
84 --fg color
86 Foreground color of display (color name or hex). Together with the
87 background color specified by --bg, this specifies the terminal's
88 palette in color modes 2 and none. Color names are based on those
89 provided with X.Org. Defaults to white.
90 --fg-only
92 Leave the background color untouched. This produces character-cell
93 output using foreground colors only, and will avoid resetting or
94 inverting the colors.
95 --fill symbols
97 Specify character symbols to use for fill/gradients. Defaults to
98 none. Usage is similar to that of --symbols; see below.
99 --font-ratio width/height
101 Target font's width/height ratio. Can be specified as a real number
102 or a fraction. Defaults to 1/2.
103 -f, --format format
105 Set output format; one of [iterm, kitty, sixels, symbols]. The
106 default is iterm, kitty or sixels if the connected terminal
107 supports one of these, falling back to symbols ("ANSI art")
108 otherwise.
109 --glyph-file file
111 Load glyph information from file, which can be any font file
112 supported by FreeType (TTF, PCF, etc). The glyph outlines will
113 replace any existing outlines, including builtins. Useful in symbol
114 mode for custom font support or for improving quality with a
115 specific font. Note that this only makes sense if the output
116 terminal is using a matching font. Can be specified multiple times.
117 -h, --help
119 Show a brief help text.
120 --invert
122 Invert video. For display with bright backgrounds in color modes 2
123 and none. Swaps --fg and --bg.
124 --margin-bottom num
126 When terminal size is detected, reserve at least this many rows at
127 the bottom as a safety margin. Can be used to prevent images from
128 scrolling out. Defaults to 1.
129 --margin-right num
131 When terminal size is detected, reserve at least this many columns
132 on the right-hand side as a safety margin. Defaults to 0.
133 -O num, --optimize num
135 Compress the output by using control sequences intelligently [0-9].
136 0 disables, 9 enables every available optimization. Defaults to 5,
137 except for when used with "-c none", where it defaults to 0.
138 --polite bool
140 Polite mode [on, off]. Defaults to on. Turning this off may enhance
141 presentation and prevent interference from other programs, but
142 risks leaving the terminal in an altered state (rude).
143 -p bool, --preprocess bool
145 Image preprocessing [on, off]. Defaults to on with 16 colors or
146 lower, off otherwise. This enhances colors and contrast prior to
147 conversion, which can be useful in low-color modes.
148 -s widthxheight, --size widthxheight
150 Set maximum output dimensions in columns and rows. By default this
151 will be the size of your terminal, or 80x25 if size detection
152 fails.
153 --speed speed
155 Set the speed animations will play at. This can be either a
156 unitless multiplier (fractions are allowed), or a real number
157 followed by "fps" to apply a specific framerate.
158 --stretch
160 Stretch image to fit output dimensions; ignore aspect. Implies
161 --zoom.
162 --symbols symbols
164 Specify character symbols to employ in final output. See below for
165 full usage and a list of symbol classes.
166 --threads num
168 Maximum number of CPU threads to use. If left unspecified or
169 negative, this will equal available CPU cores.
170 -t threshold, --threshold threshold
172 Threshold above which full transparency will be used [0.0 - 1.0].
173 Setting this to 0.0 will render a blank image, while a value of 1.0
174 will replace any transparency with the background color
175 (configurable with --bg).
176 --version
178 Show version, feature and copyright information.
179 --watch
181 Watch a single input file, redisplaying it whenever its contents
182 change. Will run until manually interrupted or, if --duration is
183 set, until it expires.
184 -w num, --work num
186 How hard to work in terms of CPU and memory [1-9]. 1 is the
187 cheapest, 9 is the most accurate. Defaults to 5.
188 --zoom
190 Allow scaling up beyond one character per pixel.
191
193 Accepted classes for --symbols are [all, none, space, solid, stipple,
194 block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted,
195 braille, technical, geometric, ascii, legacy, sextant, wedge, wide,
196 narrow]. Some symbols belong to multiple classes, e.g. diagonals are
197 also borders.
198 You can specify a list of classes separated by commas, or prefix them
200 with + and - to add or remove symbols relative to the existing set. The
201 ordering is significant.
202 The default symbol set is block+border+space-wide-inverted for all
204 modes except "none", which uses block+border+space-wide (including
205 inverse symbols).
206
208 chafa in.gif
209 Show a potentially animated GIF image in the terminal. If this is
210 an animation, it will run until the user generates an interrupt
211 (typically ctrl-c). All parameters will be autodetected based on
212 the current environment.
213 chafa -c full -s 200 in.gif
215 Like the above, but force truecolor output that is 200 characters
216 wide and calculate the height preserving the aspect of the original
217 image.
218 chafa -c 16 --color-space din99d --symbols -dot in.jpg
220 Generate 16-color output with perceptual color picking and avoid
221 using dot symbols.
222 chafa -c none --symbols block+border-solid in.png
224 Generate uncolored output using block and border symbols, but avoid
225 the solid block symbol.
226
228 See the Chafa homepage[1] for more information.
229
231 Written by Hans Petter Jansson[2] <hpj@hpjansson.org>.
232
234 1. Chafa homepage
235 https://hpjansson.org/chafa/
236 2. Hans Petter Jansson
238 https://hpjansson.org/
239chafa CHAFA(1)