1CHAFA(1) User Commands CHAFA(1)
2
3
4
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
18 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
28 --clear
29 Clear screen before processing each file.
30
31 -c mode, --colors mode
32 Set output color mode; one of [none, 2, 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
40 --color-space cs
41 Color space used for quantization; one of [rgb, din99d]. Defaults
42 to rgb, which is faster but less accurate.
43
44 --dither type
45 Type of dithering to apply during quantization. One of [none,
46 ordered, diffusion]. "Bayer" is a synonym for "ordered", and "fs"
47 (Floyd-Steinberg) is a synonym for "diffusion".
48
49 --dither-grain widthxheight
50 Dimensions of grain used when dithering. Specified as width x
51 height, where each can be one of [1, 2, 4, 8] pixels. One character
52 cell is by definition 8 pixels across in both dimensions. Defaults
53 to 4x4.
54
55 --dither-intensity intensity
56 Intensity of dithering pattern. Ranges from 0.0 to infinity, with
57 1.0 considered neutral. Lower values tend to reduce the amount of
58 dithering done, while higher values increase it. In practice,
59 values higher than 10.0 are unlikely to produce useful results.
60
61 -d, --duration seconds
62 Time to show each file. If showing a single file, defaults to zero
63 for a still image and infinite for an animation. For multiple
64 files, defaults to 3.0. Animations will always be played through at
65 least once.
66
67 --fg color
68 Foreground color of display (color name or hex). Together with the
69 background color specified by --bg, this specifies the terminal's
70 palette in color modes 2 and none. Color names are based on those
71 provided with X.Org. Defaults to white.
72
73 --fill symbols
74 Specify character symbols to use for fill/gradients. Defaults to
75 none. Usage is similar to that of --symbols; see below.
76
77 --font-ratio width/height
78 Target font's width/height ratio. Can be specified as a real number
79 or a fraction. Defaults to 1/2.
80
81 -h, --help
82 Show a brief help text.
83
84 --invert
85 Invert video. For display with bright backgrounds in color modes 2
86 and none. Swaps --fg and --bg.
87
88 -p bool, --preprocess bool
89 Image preprocessing [on, off]. Defaults to on with 16 colors or
90 lower, off otherwise. This enhances colors and contrast prior to
91 conversion, which can be useful in low-color modes.
92
93 -s widthxheight, --size widthxheight
94 Set maximum output dimensions in columns and rows. By default this
95 will be the size of your terminal, or 80x25 if size detection
96 fails.
97
98 --stretch
99 Stretch image to fit output dimensions; ignore aspect. Implies
100 --zoom.
101
102 --symbols symbols
103 Specify character symbols to employ in final output. See below for
104 full usage and a list of symbol classes.
105
106 -t threshold, --threshold threshold
107 Threshold above which full transparency will be used [0.0 - 1.0].
108 Setting this to 0.0 will render a blank image, while a value of 1.0
109 will replace any transparency with the background color
110 (configurable with --bg).
111
112 --version
113 Show version, feature and copyright information.
114
115 --watch
116 Watch a single input file, redisplaying it whenever its contents
117 change. Will run until manually interrupted or, if --duration is
118 set, until it expires.
119
120 -w num, --work num
121 How hard to work in terms of CPU and memory [1-9]. 1 is the
122 cheapest, 9 is the most accurate. Defaults to 5.
123
124 --zoom
125 Allow scaling up beyond one character per pixel.
126
128 Accepted classes for --symbols are [all, none, space, solid, stipple,
129 block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted,
130 braille, technical, geometric, ascii]. Some symbols belong to multiple
131 classes, e.g. diagonals are also borders.
132
133 You can specify a list of classes separated by commas, or prefix them
134 with + and - to add or remove symbols relative to the existing set. The
135 ordering is significant.
136
137 The default symbol set is
138 all-stipple-braille-ascii+space-extra-inverted for all modes except for
139 "none", which uses all-stipple-braille-ascii+space-extra.
140
142 chafa in.gif
143 Show a potentially animated GIF image in the terminal. If this is
144 an animation, it will run until the user generates an interrupt
145 (typically ctrl-c). All parameters will be autodetected based on
146 the current environment.
147
148 chafa -c full -s 200 in.gif
149 Like the above, but force truecolor output that is 200 characters
150 wide and calculate the height preserving the aspect of the original
151 image.
152
153 chafa -c 16 --color-space din99d --symbols -dot in.jpg
154 Generate 16-color output with perceptual color picking and avoid
155 using dot symbols.
156
157 chafa -c none --symbols block+border-solid in.png
158 Generate uncolored output using block and border symbols, but avoid
159 the solid block symbol.
160
162 Written by Hans Petter Jansson <hpj@copyleft.no>.
163
164
165
166chafa CHAFA(1)