1CHAFA(1) User Commands CHAFA(1)
2
6 chafa - Character art facsimile generator
7
10 chafa [OPTION...] [IMAGE...]
11
16 chafa is a utility that converts all kinds of images, including
17 animated image formats like GIFs, into (potentially animated)
18 ANSI/Unicode character output that can be displayed in a terminal. It
19 supports alpha transparency and multiple color modes and color spaces,
20 and combines a range of Unicode characters for optimal output.
21 You can specify one or more input files, but the default behavior is
23 slightly different with multiple files -- for instance, animations will
24 not loop forever when there is more than one input file.
25
29 --bg color
30 Background color of display (color name or hex). Partially
33 transparent input will be blended with this color. Color names are
34 based on those provided with X.Org. Defaults to black.
35 --clear
37 Clear screen before processing each file.
40 -c mode, --colors mode
42 Set output color mode; one of [none, 2, 16, 240, 256, full].
45 Defaults to full (24-bit). The 240-color mode is recommended over
46 the 256-color one, since the lower 16 colors are unreliable and
47 tend to differ between terminals. 16-color mode will use aixterm
48 extensions to produce 16 foreground and background colors. 2-color
49 mode will only emit the ANSI codes for reverse color and attribute
50 reset, while "none" will emit no ANSI color codes whatsoever.
51 --color-space cs
53 Color space used for quantization; one of [rgb, din99d]. Defaults
56 to rgb, which is faster but less accurate.
57 -d, --duration seconds
59 Time to show each file. If showing a single file, defaults to zero
62 for a still image and infinite for an animation. For multiple
63 files, defaults to 3.0. Animations will always be played through at
64 least once.
65 --fg color
67 Foreground color of display (color name or hex). Together with the
70 background color specified by --bg, this specifies the terminal's
71 palette in color modes 2 and none. Color names are based on those
72 provided with X.Org. Defaults to white.
73 --font-ratio width/height
75 Target font's width/height ratio. Can be specified as a real number
78 or a fraction. Defaults to 1/2.
79 -h, --help
81 Show a brief help text.
84 --invert
86 Invert video. For display with bright backgrounds in color modes 2
89 and none. Swaps --fg and --bg.
90 -p bool, --preprocess bool
92 Image preprocessing [on, off]. Defaults to on with 16 colors or
95 lower, off otherwise. This enhances colors and contrast prior to
96 conversion, which can be useful in low-color modes.
97 -s widthxheight, --size widthxheight
99 Set maximum output dimensions in columns and rows. By default this
102 will be the size of your terminal, or 80x25 if size detection
103 fails.
104 --stretch
106 Stretch image to fit output dimensions; ignore aspect. Implies
109 --zoom.
110 --symbols symbols
112 Specify character symbols to employ in final output. See below for
115 full usage and a list of symbol classes.
116 -t threshold, --threshold threshold
118 Threshold above which full transparency will be used [0.0 - 1.0].
121 Setting this to 0.0 will render a blank image, while a value of 1.0
122 will replace any transparency with the background color
123 (configurable with --bg).
124 --version
126 Show version, feature and copyright information.
129 -w num, --work num
131 How hard to work in terms of CPU and memory [1-9]. 1 is the
134 cheapest, 9 is the most accurate. Defaults to 5.
135 --zoom
137 Allow scaling up beyond one character per pixel.
140
145 Accepted classes for --symbols are [all, none, space, solid, stipple,
146 block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted]. Some
147 symbols belong to multiple classes, e.g. diagonals are also borders.
148 You can specify a list of classes separated by commas, or prefix them
150 with + and - to add or remove symbols relative to the existing set. The
151 ordering is significant.
152 The default symbol set is all-stipple-inverted for all modes except for
154 "none", which looks best when allowed to use inverted characters.
155
159 chafa in.gif
160 Show a potentially animated GIF image in the terminal. If this is
163 an animation, it will run until the user generates an interrupt
164 (typically ctrl-c). All parameters will be autodetected based on
165 the current environment.
166 chafa -c full -s 200 in.gif
168 Like the above, but force truecolor output that is 200 characters
171 wide and calculate the height preserving the aspect of the original
172 image.
173 chafa -c 16 --color-space din99d --symbols -dot in.jpg
175 Generate 16-color output with perceptual color picking and avoid
178 using dot symbols.
179 chafa -c none --symbols block+border-solid in.png
181 Generate uncolored output using block and border symbols, but avoid
184 the solid block symbol.
185
191 Written by Hans Petter Jansson <hpj@copyleft.no>.
192chafa CHAFA(1)