<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>

<refentry id="chafa" xmlns:xlink="http://www.w3.org/1999/xlink">

<refentryinfo>
<title>chafa</title>
<productname>chafa</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Hans Petter</firstname>
<surname>Jansson</surname>
</author>
</authorgroup>
</refentryinfo>

<refmeta>
<refentrytitle>chafa</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>

<refnamediv>
<refname>chafa</refname>
<refpurpose>Character art facsimile generator</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis><command>chafa</command><arg choice="opt" rep="repeat">OPTION</arg><arg rep="repeat">IMAGE</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
<command>chafa</command> 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.
</para>
<para>
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.
</para>
</refsect1>

<refsect1><title>General options</title>
<variablelist>

<varlistentry>
<term><option>--files <replaceable>path</replaceable></option></term>
<listitem><para>
Read a list of paths to process from <replaceable>path</replaceable>,
or '-' for stdin. The paths must be separated by newlines.
</para><para>
Can be specified multiple times. Any additional paths on the command line
will be processed last.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--files0 <replaceable>path</replaceable></option></term>
<listitem><para>
Read a list of paths to process from <replaceable>path</replaceable>,
or '-' for stdin. The paths must be separated by NUL bytes. This is more
robust if your file system allows newlines in filenames (as POSIX does).
Useful in conjunction with other tools that support it, e.g.:
</para><para>
<command>find . -type f -print0 | chafa --files0 -</command>
</para><para>
Can be specified multiple times. Any additional paths on the command line
will be processed last.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-h, --help</option></term>
<listitem><para>
Show a brief help text.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--probe <replaceable>arg</replaceable></option></term>
<listitem><para>
Probe terminal's capabilities and wait for response [auto, on, off].
A positive real number denotes the maximum time to wait for a response,
in seconds. Defaults to 5.0.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Show version, feature and copyright information.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Output encoding</title>
<variablelist>

<varlistentry>
<term><option>-f, --format <replaceable>format</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-O <replaceable>num</replaceable>, --optimize <replaceable>num</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--relative <replaceable>bool</replaceable></option></term>
<listitem><para>
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. 'less -R' interop. Defaults to off.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--passthrough <replaceable>mode</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--polite <replaceable>bool</replaceable></option></term>
<listitem><para>
Polite mode [on, off]. Inhibits escape sequences that on rare occasions
may confuse the terminal or other programs. Defaults to off.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Size and layout</title>
<variablelist>

<varlistentry>
<term><option>--align <replaceable>ALIGN</replaceable></option></term>
<listitem><para>
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.
</para>
<para>
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".
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-C <replaceable>bool</replaceable>, --center <replaceable>bool</replaceable></option></term>
<listitem><para>
Center images horizontally in the view [on, off]. Defaults to off. This option
is deprecated; use "--align center" instead.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--clear</option></term>
<listitem><para>
Clear screen before processing each file.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--exact-size <replaceable>mode</replaceable></option></term>
<listitem><para>
Try to match the input's 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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--fit-width</option></term>
<listitem><para>
Fit images to the view's width, potentially exceeding its height.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--font-ratio <replaceable>width</replaceable>/<replaceable>height</replaceable></option></term>
<listitem><para>
Target font's width/height ratio. Can be specified as a real number or a
fraction. Defaults to 1/2. This will only be applied in symbol mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-g, --grid <replaceable>cols</replaceable>x<replaceable>rows</replaceable></option></term>
<listitem><para>
Lay out images in a grid of <replaceable>cols</replaceable> columns and
<replaceable>rows</replaceable> rows per screenful. Either
<replaceable>cols</replaceable> or <replaceable>rows</replaceable> may be
omitted, e.g. --grid 4 or --grid x4, in which case cell allocations
will be approximately square. If "auto" is specified, dimensions will be
picked automatically.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-l, --label <replaceable>bool</replaceable></option></term>
<listitem><para>
Labeling [on, off]. When this is enabled, each image will be labeled with
its filename. Defaults to off.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--margin-bottom <replaceable>num</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--margin-right <replaceable>num</replaceable></option></term>
<listitem><para>
When terminal size is detected, reserve at least this many columns on the
right-hand side as a safety margin. Defaults to 0.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--scale <replaceable>num</replaceable></option></term>
<listitem><para>
Scale image, respecting terminal's 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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-s <replaceable>width</replaceable>x<replaceable>height</replaceable>, --size <replaceable>width</replaceable>x<replaceable>height</replaceable></option></term>
<listitem><para>
Set maximum output image dimensions in columns and rows. By default this will
be equal to the view size (see --view-size).
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--stretch</option></term>
<listitem><para>
Stretch image to fit output dimensions; ignore aspect. Implies --scale max.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--view-size <replaceable>width</replaceable>x<replaceable>height</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Animation and timing</title>
<variablelist>

<varlistentry>
<term><option>--animate <replaceable>bool</replaceable></option></term>
<listitem><para>
Whether to allow animation [on, off]. Defaults to on. When off, will show a
still frame from each animation.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-d, --duration <replaceable>seconds</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--speed <replaceable>speed</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--watch</option></term>
<listitem><para>
Watch a single input file, redisplaying it whenever its contents change. Will run
until manually interrupted or, if --duration is set, until it expires.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Colors and processing</title>
<variablelist>

<varlistentry>
<term><option>--bg <replaceable>color</replaceable></option></term>
<listitem><para>
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, or the terminal's default background color when
probing is enabled (see --probe).
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-c <replaceable>mode</replaceable>, --colors <replaceable>mode</replaceable></option></term>
<listitem><para>
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.
</para>
<para>
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).
</para>
<para>
If left unspecified, an optimal default will be chosen based on the current
environment.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--color-extractor <replaceable>extractor</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--color-space <replaceable>cs</replaceable></option></term>
<listitem><para>
Color space used for quantization; one of [rgb, din99d]. Defaults to rgb,
which is faster but less accurate.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--dither <replaceable>type</replaceable></option></term>
<listitem><para>
Type of dithering to apply during quantization. One of [none, ordered,
diffusion, noise]. "Bayer" is a synonym for "ordered", and "fs" (Floyd-Steinberg)
is a synonym for "diffusion". Defaults to "noise" in sixel mode, otherwise
"none".
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--dither-grain <replaceable>width</replaceable>x<replaceable>height</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--dither-intensity <replaceable>intensity</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--fg <replaceable>color</replaceable></option></term>
<listitem><para>
Foreground color of display (color name or hex). Together with the background
color specified by --bg, this specifies the terminal's palette in color modes 2
and none. Color names are based on those provided with X.Org. Defaults to
white, or the terminal's default foreground color when probing is enabled
(see --probe).
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--invert</option></term>
<listitem><para>
Invert video. For display with bright backgrounds in color modes 2 and
none. Swaps --fg and --bg.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-p <replaceable>bool</replaceable>, --preprocess <replaceable>bool</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-t <replaceable>threshold</replaceable>, --threshold
<replaceable>threshold</replaceable></option></term>
<listitem><para>
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).
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Resource allocation</title>
<variablelist>

<varlistentry>
<term><option>--threads <replaceable>num</replaceable></option></term>
<listitem><para>
Maximum number of CPU threads to use. If left unspecified or negative,
this will equal available CPU cores.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-w <replaceable>num</replaceable>, --work <replaceable>num</replaceable></option></term>
<listitem><para>
How hard to work in terms of CPU and memory [1-9]. 1 is the cheapest, 9 is the
most accurate. Defaults to 5.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Extra options for symbol encoding</title>
<variablelist>

<varlistentry>
<term><option>--fg-only</option></term>
<listitem><para>
Leave the background color untouched. This produces character-cell output
using foreground colors only, and will avoid resetting or inverting the
colors.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--fill <replaceable>symbols</replaceable></option></term>
<listitem><para>
Specify character symbols to use for fill/gradients. Defaults to none.
Usage is similar to that of --symbols; see below.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--glyph-file <replaceable>file</replaceable></option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--symbols <replaceable>symbols</replaceable></option></term>
<listitem><para>
Specify character symbols to employ in final output. See below for full usage
and a list of symbol classes.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Exit Status</title>
<para>
<command>chafa</command> will return 0 on success, 1 on partial failure or
2 on complete failure (including when invoked with no arguments).
</para>
<segmentedlist>
<segtitle>Status</segtitle>
<segtitle>Meaning</segtitle>
<seglistitem><seg>0</seg><seg>Success</seg></seglistitem>
<seglistitem><seg>1</seg><seg>Some files failed to display</seg></seglistitem>
<seglistitem><seg>2</seg><seg>All files failed to display</seg></seglistitem>
</segmentedlist>
</refsect1>

<refsect1><title>Symbols</title>
<para>
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.
</para>
<para>
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".
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
The default symbol set is block+border+space-wide-inverted for all modes
except "none", which uses block+border+space-wide (including inverse symbols).
</para>
</refsect1>

<refsect1><title>Duration</title>
<para>
In order to accommodate both interactive use and batch processing, an animation's
duration is determined according to a few simple rules:
</para>
<orderedlist>
<listitem><para>
If one or more <command>--duration</command> arguments are present, the final
instance is respected and applied to every file.
</para></listitem>
<listitem><para>
Otherwise, if there's a controlling terminal attached (indicating there's
an interactive session), and only a single file argument is provided, and
that file is an animation, it will have infinite duration.
</para></listitem>
<listitem><para>
Otherwise (no controlling terminal, multiple files, file is a still image),
duration will be zero, causing animations to play once and then stop.
</para></listitem>
</orderedlist>
</refsect1>

<refsect1><title>Examples</title>
<variablelist>
<varlistentry>
<term><command>chafa in.gif</command></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><command>chafa -c full -s 200 in.gif</command></term>
<listitem><para>
Like the above, but force truecolor output that is 200 characters wide and
calculate the height preserving the aspect of the original image.
</para></listitem>
</varlistentry>
<varlistentry>
<term><command>chafa -c 16 --color-space din99d --symbols -dot in.jpg</command></term>
<listitem><para>
Generate 16-color output with perceptual color picking and avoid using dot symbols.
</para></listitem>
</varlistentry>
<varlistentry>
<term><command>chafa -c none --symbols block+border-solid in.png</command></term>
<listitem><para>
Generate uncolored output using block and border symbols, but avoid the solid
block symbol.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1><title>Further Reading</title>
<para>
See the <link xlink:href="https://hpjansson.org/chafa/">Chafa homepage</link>
for more information.
</para>
</refsect1>

<refsect1><title>Author</title>
<para>
    Written by <link xlink:href="https://hpjansson.org/">Hans Petter Jansson</link> <email>hpj@hpjansson.org</email>.
</para>
</refsect1>

</refentry>