'\" t .\" Title: chafa .\" Author: Hans Petter Jansson .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 01/19/2024 .\" Manual: User Commands .\" Source: chafa .\" Language: English .\" .TH "CHAFA" "1" "" "chafa" "User Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" chafa \- Character art facsimile generator .SH "SYNOPSIS" .HP \w'\fBchafa\fR\ 'u \fBchafa\fR [OPTION...] [IMAGE...] .SH "DESCRIPTION" .PP \fBchafa\fR is a command\-line utility that converts image data, including animated GIFs, into graphics formats or ANSI/Unicode character art suitable for display in a terminal\&. It has broad feature support, allowing it to be used on devices ranging from historical teleprinters to modern terminal emulators and everything in between\&. .PP You can specify one or more input files, but the default behavior is slightly different with multiple files \-\- for instance, animations will not loop forever when there is more than one input file\&. .SH "GENERAL OPTIONS" .PP \fB\-h, \-\-help\fR .RS 4 Show a brief help text\&. .RE .PP \fB\-\-version\fR .RS 4 Show version, feature and copyright information\&. .RE .SH "OUTPUT ENCODING" .PP \fB\-f, \-\-format \fR\fB\fIformat\fR\fR .RS 4 Set output format; one of [iterm, kitty, sixels, symbols]\&. The default is iterm, kitty or sixels if the connected terminal supports one of these, falling back to symbols ("ANSI art") otherwise\&. .RE .PP \fB\-O \fR\fB\fInum\fR\fR\fB, \-\-optimize \fR\fB\fInum\fR\fR .RS 4 Compress the output by using control sequences intelligently [0\-9]\&. 0 disables, 9 enables every available optimization\&. Defaults to 5, except for when used with "\-c none", where it defaults to 0\&. .RE .PP \fB\-\-relative \fR\fB\fIbool\fR\fR .RS 4 Use relative cursor positioning [on, off]\&. When on, control sequences will be used to position images relative to the cursor\&. When off, newlines will be used to separate rows instead for e\&.g\&. \*(Aqless \-R\*(Aq interop\&. Defaults to off\&. .RE .PP \fB\-\-passthrough \fR\fB\fImode\fR\fR .RS 4 Graphics protocol passthrough [auto, none, screen, tmux]\&. Used to show pixel graphics from within multiplexers\&. Defaults to auto, which will enable passthrough if the Kitty terminal is detected along with one of the supported multiplexers\&. Other combinations must be enabled manually; use with the \-f option to select the appropriate graphics protocol\&. .RE .PP \fB\-\-polite \fR\fB\fIbool\fR\fR .RS 4 Polite mode [on, off]\&. Inhibits escape sequences that on rare occasions may confuse the terminal or other programs\&. Defaults to off\&. .RE .SH "SIZE AND LAYOUT" .PP \fB\-\-align \fR\fB\fIALIGN\fR\fR .RS 4 Align images in viewport\&. The following alignments are understood: left, right, top, bottom, hcenter, vcenter, center\&. Two orthogonal alignments can be separated by a comma, e\&.g\&. "center,right"\&. The meaning of "center" depends on context, and defaults to "hcenter" if ambiguous\&. "center,center" will center along both axes\&. .sp Centering vertically makes sense when used together with "\-\-clear", or possibly as part of a scheme where the cursor is pre\-positioned at the top\-left corner of the view, or a subview when used with "\-\-relative on"\&. .RE .PP \fB\-C \fR\fB\fIbool\fR\fR\fB, \-\-center \fR\fB\fIbool\fR\fR .RS 4 Center images horizontally in the view [on, off]\&. Defaults to off\&. This option is deprecated; use "\-\-align center" instead\&. .RE .PP \fB\-\-clear\fR .RS 4 Clear screen before processing each file\&. .RE .PP \fB\-\-exact\-size \fR\fB\fImode\fR\fR .RS 4 Try to match the input\*(Aqs size exactly [auto, on, off]\&. When on, this will override other sizing options and produce output images at the exact pixel size of the inputs\&. In auto mode, scaling will be avoided (in exchange for padding) if the output size is equal to or slightly bigger than the input\&. When off, padding will never be added, and the image is scaled to fit the containing cell extent\&. Defaults to auto\&. .RE .PP \fB\-\-fit\-width\fR .RS 4 Fit images to the view\*(Aqs width, potentially exceeding its height\&. .RE .PP \fB\-\-font\-ratio \fR\fB\fIwidth\fR\fR\fB/\fR\fB\fIheight\fR\fR .RS 4 Target font\*(Aqs width/height ratio\&. Can be specified as a real number or a fraction\&. Defaults to 1/2\&. .RE .PP \fB\-\-margin\-bottom \fR\fB\fInum\fR\fR .RS 4 When terminal size is detected, reserve at least this many rows at the bottom as a safety margin\&. Can be used to prevent images from scrolling out\&. Defaults to 1\&. .RE .PP \fB\-\-margin\-right \fR\fB\fInum\fR\fR .RS 4 When terminal size is detected, reserve at least this many columns on the right\-hand side as a safety margin\&. Defaults to 0\&. .RE .PP \fB\-\-scale \fR\fB\fInum\fR\fR .RS 4 Scale image, respecting terminal\*(Aqs maximum dimensions\&. 1\&.0 approximates original pixel dimensions\&. Specify "max" to use all available space\&. Defaults to 1\&.0 for pixel graphics and 4\&.0 for symbols\&. .RE .PP \fB\-s \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR\fB, \-\-size \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR .RS 4 Set maximum output image dimensions in columns and rows\&. By default this will be equal to the view size (see \-\-view\-size)\&. .RE .PP \fB\-\-stretch\fR .RS 4 Stretch image to fit output dimensions; ignore aspect\&. Implies \-\-scale max\&. .RE .PP \fB\-\-view\-size \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR .RS 4 Set the view size in columns and rows\&. By default this will be the size of your terminal, or 80x25 if size detection fails\&. If one dimension is omitted (by providing a size of e\&.g\&. 80x or x25), it will be set to a reasonable approximation of infinity\&. .RE .SH "ANIMATION AND TIMING" .PP \fB\-\-animate \fR\fB\fIbool\fR\fR .RS 4 Whether to allow animation [on, off]\&. Defaults to on\&. When off, will show a still frame from each animation\&. .RE .PP \fB\-d, \-\-duration \fR\fB\fIseconds\fR\fR .RS 4 Time to show each file, in seconds\&. Defaults to zero for still images and for animations when multiple files are specified\&. If a single animation is specified, defaults to infinite, or "inf"\&. Animations will always be played through at least once, even if duration is e\&.g\&. zero\&. See the "Duration" section for more\&. .RE .PP \fB\-\-speed \fR\fB\fIspeed\fR\fR .RS 4 Set the speed animations will play at\&. This can be either a unitless multiplier (fractions are allowed), or a real number followed by "fps" to apply a specific framerate\&. .RE .PP \fB\-\-watch\fR .RS 4 Watch a single input file, redisplaying it whenever its contents change\&. Will run until manually interrupted or, if \-\-duration is set, until it expires\&. .RE .SH "COLORS AND PROCESSING" .PP \fB\-\-bg \fR\fB\fIcolor\fR\fR .RS 4 Background color of display (color name or hex)\&. Partially transparent input will be blended with this color\&. Color names are based on those provided with X\&.Org\&. Defaults to black\&. .RE .PP \fB\-c \fR\fB\fImode\fR\fR\fB, \-\-colors \fR\fB\fImode\fR\fR .RS 4 Set output color mode; one of [none, 2, 8, 16/8 16, 240, 256, full]\&. The 240\-color mode is recommended over the 256\-color one, since the lower 16 colors are unreliable and tend to differ between terminals\&. 16\-color mode will use aixterm extensions to produce 16 foreground and background colors\&. The 16/8 mode allows for 8 colors plus another "bright" 8 colors in the foreground implemented with the "bold" escape sequence\&. 2\-color mode will only emit the ANSI codes for reverse color and attribute reset, while "none" will emit no escape sequences at all\&. .sp In sixel mode, "full" will dynamically generate a 256\-color palette for each image or animation frame\&. The other modes refer to built\-in palettes\&. "none" and "2" are interchangeable and will use the specified foreground/background colors (see \-\-fg and \-\-bg)\&. .sp If left unspecified, an optimal default will be chosen based on the current environment\&. .RE .PP \fB\-\-color\-extractor \fR\fB\fIextractor\fR\fR .RS 4 Method for extracting color from an area; one of [average, median]\&. Median normally produces crisper output, while average may perform better on noisy images\&. Defaults to average\&. .RE .PP \fB\-\-color\-space \fR\fB\fIcs\fR\fR .RS 4 Color space used for quantization; one of [rgb, din99d]\&. Defaults to rgb, which is faster but less accurate\&. .RE .PP \fB\-\-dither \fR\fB\fItype\fR\fR .RS 4 Type of dithering to apply during quantization\&. One of [none, ordered, diffusion]\&. "Bayer" is a synonym for "ordered", and "fs" (Floyd\-Steinberg) is a synonym for "diffusion"\&. .RE .PP \fB\-\-dither\-grain \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR .RS 4 Dimensions of grain used when dithering\&. Specified as width x height, where each can be one of [1, 2, 4, 8] pixels\&. One character cell is by definition 8 pixels across in both dimensions\&. Defaults to 4x4 in symbol mode and 1x1 in sixel mode\&. .RE .PP \fB\-\-dither\-intensity \fR\fB\fIintensity\fR\fR .RS 4 Intensity of dithering pattern\&. Ranges from 0\&.0 to infinity, with 1\&.0 considered neutral\&. Lower values tend to reduce the amount of dithering done, while higher values increase it\&. In practice, values higher than 10\&.0 are unlikely to produce useful results\&. .RE .PP \fB\-\-fg \fR\fB\fIcolor\fR\fR .RS 4 Foreground color of display (color name or hex)\&. Together with the background color specified by \-\-bg, this specifies the terminal\*(Aqs palette in color modes 2 and none\&. Color names are based on those provided with X\&.Org\&. Defaults to white\&. .RE .PP \fB\-\-invert\fR .RS 4 Invert video\&. For display with bright backgrounds in color modes 2 and none\&. Swaps \-\-fg and \-\-bg\&. .RE .PP \fB\-p \fR\fB\fIbool\fR\fR\fB, \-\-preprocess \fR\fB\fIbool\fR\fR .RS 4 Image preprocessing [on, off]\&. Defaults to on with 16 colors or lower, off otherwise\&. This enhances colors and contrast prior to conversion, which can be useful in low\-color modes\&. .RE .PP \fB\-t \fR\fB\fIthreshold\fR\fR\fB, \-\-threshold \fR\fB\fIthreshold\fR\fR .RS 4 Threshold above which full transparency will be used [0\&.0 \- 1\&.0]\&. Setting this to 0\&.0 will render a blank image, while a value of 1\&.0 will replace any transparency with the background color (configurable with \-\-bg)\&. .RE .SH "RESOURCE ALLOCATION" .PP \fB\-\-threads \fR\fB\fInum\fR\fR .RS 4 Maximum number of CPU threads to use\&. If left unspecified or negative, this will equal available CPU cores\&. .RE .PP \fB\-w \fR\fB\fInum\fR\fR\fB, \-\-work \fR\fB\fInum\fR\fR .RS 4 How hard to work in terms of CPU and memory [1\-9]\&. 1 is the cheapest, 9 is the most accurate\&. Defaults to 5\&. .RE .SH "EXTRA OPTIONS FOR SYMBOL ENCODING" .PP \fB\-\-fg\-only\fR .RS 4 Leave the background color untouched\&. This produces character\-cell output using foreground colors only, and will avoid resetting or inverting the colors\&. .RE .PP \fB\-\-fill \fR\fB\fIsymbols\fR\fR .RS 4 Specify character symbols to use for fill/gradients\&. Defaults to none\&. Usage is similar to that of \-\-symbols; see below\&. .RE .PP \fB\-\-glyph\-file \fR\fB\fIfile\fR\fR .RS 4 Load glyph information from file, which can be any font file supported by FreeType (TTF, PCF, etc)\&. The glyph outlines will replace any existing outlines, including builtins\&. Useful in symbol mode for custom font support or for improving quality with a specific font\&. Note that this only makes sense if the output terminal is using a matching font\&. Can be specified multiple times\&. .RE .PP \fB\-\-symbols \fR\fB\fIsymbols\fR\fR .RS 4 Specify character symbols to employ in final output\&. See below for full usage and a list of symbol classes\&. .RE .SH "EXIT STATUS" .PP \fBchafa\fR will return 0 on success, 1 on partial failure or 2 on complete failure (including when invoked with no arguments)\&. .\" line length increase to cope w/ tbl weirdness .ll +(\n(LLu * 62u / 100u) .TS ll. \fIStatus\fR \fIMeaning\fR T{ 0 T} T{ Success T} T{ 1 T} T{ Some files failed to display T} T{ 2 T} T{ All files failed to display T} .TE .\" line length decrease back to previous value .ll -(\n(LLu * 62u / 100u) .sp .SH "SYMBOLS" .PP Accepted classes for \-\-symbols and \-\-fill are [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical, geometric, ascii, legacy, sextant, wedge, wide, narrow]\&. Some symbols belong to multiple classes, e\&.g\&. diagonals are also borders\&. .PP You can add specific characters with the letter "u" followed by a hexadecimal code point, e\&.g\&. "ue080", or a range of code points by separating the first and last index by "\&.\&.", e\&.g\&. "u100\&.\&.u200"\&. .PP Symbol sets can also be specified as a string of UTF\-8 characters in square brackets, e\&.g\&. [abcd]\&. To include a closing bracket in the set, escape it with a backslash\&. .PP You can specify a list of classes separated by commas, or prefix them with + and \- to add or remove symbols relative to the existing set\&. The ordering is significant\&. .PP The default symbol set is block+border+space\-wide\-inverted for all modes except "none", which uses block+border+space\-wide (including inverse symbols)\&. .SH "DURATION" .PP In order to accommodate both interactive use and batch processing, an animation\*(Aqs duration is determined according to a few simple rules: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} If one or more \fB\-\-duration\fR arguments are present, the final instance is respected and applied to every file\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} Otherwise, if there\*(Aqs a controlling terminal attached (indicating there\*(Aqs an interactive session), and only a single file argument is provided, and that file is an animation, it will have infinite duration\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} Otherwise (no controlling terminal, multiple files, file is a still image), duration will be zero, causing animations to play once and then stop\&. .RE .SH "EXAMPLES" .PP \fBchafa in\&.gif\fR .RS 4 Show a potentially animated GIF image in the terminal\&. If this is an animation, it will run until the user generates an interrupt (typically ctrl\-c)\&. All parameters will be autodetected based on the current environment\&. .RE .PP \fBchafa \-c full \-s 200 in\&.gif\fR .RS 4 Like the above, but force truecolor output that is 200 characters wide and calculate the height preserving the aspect of the original image\&. .RE .PP \fBchafa \-c 16 \-\-color\-space din99d \-\-symbols \-dot in\&.jpg\fR .RS 4 Generate 16\-color output with perceptual color picking and avoid using dot symbols\&. .RE .PP \fBchafa \-c none \-\-symbols block+border\-solid in\&.png\fR .RS 4 Generate uncolored output using block and border symbols, but avoid the solid block symbol\&. .RE .SH "FURTHER READING" .PP See the \m[blue]\fBChafa homepage\fR\m[]\&\s-2\u[1]\d\s+2 for more information\&. .SH "AUTHOR" .PP Written by \m[blue]\fBHans Petter Jansson\fR\m[]\&\s-2\u[2]\d\s+2 \&. .SH "NOTES" .IP " 1." 4 Chafa homepage .RS 4 \%https://hpjansson.org/chafa/ .RE .IP " 2." 4 Hans Petter Jansson .RS 4 \%https://hpjansson.org/ .RE