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, 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 --color-space cs
41 Color space used for quantization; one of [rgb, din99d]. Defaults
42 to rgb, which is faster but less accurate.
43 -d, --duration seconds
45 Time to show each file. If showing a single file, defaults to zero
46 for a still image and infinite for an animation. For multiple
47 files, defaults to 3.0. Animations will always be played through at
48 least once.
49 --fg color
51 Foreground color of display (color name or hex). Together with the
52 background color specified by --bg, this specifies the terminal's
53 palette in color modes 2 and none. Color names are based on those
54 provided with X.Org. Defaults to white.
55 --fill symbols
57 Specify character symbols to use for fill/gradients. Defaults to
58 none. Usage is similar to that of --symbols; see below.
59 --font-ratio width/height
61 Target font's width/height ratio. Can be specified as a real number
62 or a fraction. Defaults to 1/2.
63 -h, --help
65 Show a brief help text.
66 --invert
68 Invert video. For display with bright backgrounds in color modes 2
69 and none. Swaps --fg and --bg.
70 -p bool, --preprocess bool
72 Image preprocessing [on, off]. Defaults to on with 16 colors or
73 lower, off otherwise. This enhances colors and contrast prior to
74 conversion, which can be useful in low-color modes.
75 -s widthxheight, --size widthxheight
77 Set maximum output dimensions in columns and rows. By default this
78 will be the size of your terminal, or 80x25 if size detection
79 fails.
80 --stretch
82 Stretch image to fit output dimensions; ignore aspect. Implies
83 --zoom.
84 --symbols symbols
86 Specify character symbols to employ in final output. See below for
87 full usage and a list of symbol classes.
88 -t threshold, --threshold threshold
90 Threshold above which full transparency will be used [0.0 - 1.0].
91 Setting this to 0.0 will render a blank image, while a value of 1.0
92 will replace any transparency with the background color
93 (configurable with --bg).
94 --version
96 Show version, feature and copyright information.
97 --watch
99 Watch a single input file, redisplaying it whenever its contents
100 change. Will run until manually interrupted or, if --duration is
101 set, until it expires.
102 -w num, --work num
104 How hard to work in terms of CPU and memory [1-9]. 1 is the
105 cheapest, 9 is the most accurate. Defaults to 5.
106 --zoom
108 Allow scaling up beyond one character per pixel.
109
111 Accepted classes for --symbols are [all, none, space, solid, stipple,
112 block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted,
113 braille, technical, geometric, ascii]. Some symbols belong to multiple
114 classes, e.g. diagonals are also borders.
115 You can specify a list of classes separated by commas, or prefix them
117 with + and - to add or remove symbols relative to the existing set. The
118 ordering is significant.
119 The default symbol set is
121 all-stipple-braille-ascii+space-extra-inverted for all modes except for
122 "none", which uses all-stipple-braille-ascii+space-extra.
123
125 chafa in.gif
126 Show a potentially animated GIF image in the terminal. If this is
127 an animation, it will run until the user generates an interrupt
128 (typically ctrl-c). All parameters will be autodetected based on
129 the current environment.
130 chafa -c full -s 200 in.gif
132 Like the above, but force truecolor output that is 200 characters
133 wide and calculate the height preserving the aspect of the original
134 image.
135 chafa -c 16 --color-space din99d --symbols -dot in.jpg
137 Generate 16-color output with perceptual color picking and avoid
138 using dot symbols.
139 chafa -c none --symbols block+border-solid in.png
141 Generate uncolored output using block and border symbols, but avoid
142 the solid block symbol.
143
145 Written by Hans Petter Jansson <hpj@copyleft.no>.
146chafa CHAFA(1)