.\" Automatically generated by Pandoc 3.1.9
.\"
.TH "timg" "1" "Dec 2023" "" ""
.SH NAME
timg - A terminal image and video viewer
.SH SYNOPSIS
\f[B]timg\f[R] [<\f[I]options\f[R]>] <\f[I]image/video\f[R]>
[<\f[I]image/video\f[R]>\&...]
.SH DESCRIPTION
Show images, play animated gifs, scroll static images or play videos in
the terminal.
Even show PDFs.
.PP
View images without leaving the comfort of your shell.
Sometimes this is the only way if your terminal is connected remotely
via ssh.
.PP
The command line accepts any number of image/video filenames (or read a
list of filenames from a file) and shows these in sequence one per page
or in a grid in multiple columns, depending on your choice of
\f[B]--grid\f[R].
The output is emitted in-line with minimally messing with your terminal,
so you can simply go back in history using your terminals\[cq]
scroll-bar (Or redirecting the output to a file allows you to later
simply \f[B]cat\f[R] that file to your terminal.
Even \f[B]less -R\f[R] seems to be happy with such output).
.PP
The special filename \[lq]-\[rq] stands for standard input, so you can
read an image from a pipe.
If the input from a pipe is a video, use the \f[B]-V\f[R] option (see
below).
.PP
Under the hood, \f[CR]timg\f[R] uses various image libraries to open and
decode a wide range of image formats.
It uses threads to open and decode images in parallel for super-fast
viewing experience for many images.
To play videos, it uses libav from files and URLs.
With \f[B]-I\f[R] or \f[B]-V\f[R] you can choose to use only one of
these file decoders ({GraphicsMagick, turbojpeg, qoi} or libav
respectively).
.SH OPTIONS
.SS General Options
Most likely commonly needed options first.
.TP
\f[B]-p\f[R] \f[I]<[h|q|s|k|i]>\f[R], \f[B]--pixelation\f[R]=\f[I][h|q|s|k|i]\f[R]
Choice for pixelation of the content.
.RS
.PP
Available values
.TP
\f[B]half\f[R] (short `h')
Uses unicode half block characters, this is the lowest resolution.
Color is using a lower or upper half block and chooses the foreground
color and background color to make up two vertical pixels per character
cell.
Half blocks have a pixel aspect ratio of about 1:1 and represent colors
correctly, but they look more `blocky'.
.TP
\f[B]quarter\f[R] (short `q')
This chooses a Unicdoe character with small sub-blocks for four pixels
per characcter cell.
Quarter blocks will have a pixel aspect ratio of 1:2 (timg will stretch
the picture accordingly, no worries), and can only
represent colors approximately, as the four quadrant sub-pixels can only
be foreground or background color.
This increases the spatial resolution
in x-direction at expense of slight less color accuracy.
It makes it look less `blocky' and usually better.
.TP
\f[B]sixel\f[R] (short `s')
Sixel output allows a high resolution image output that dates back
to DEC VT200 and VT340 terminals.
This image mode provides full
resolution on a 256 color palette that \f[CR]timg\f[R] optimizes for
each image.
You find the sixel protocol implemented by \f[CR]xterm\f[R] (invoke
with \f[CR]-ti vt340\f[R]) and \f[CR]mlterm\f[R] or \f[CR]konsole\f[R].
Recently, more terminal
emulators re-discovered this format and started implementing it.
This does not work in \f[CR]tmux\f[R], but there is a tmux fork with
sixel
support around.
.TP
\f[B]kitty\f[R] (short `k')
The Kitty terminal implements an image protocol that allows for full
24Bit RGB/32 Bit RGBA images to be displayed.
This is implemented in the
\f[CR]kitty\f[R] terminal but also e.g.\ \f[CR]konsole\f[R].
You can even use this in \f[CR]tmux\f[R]: This is the only protocol that
can
work around the reluctance of \f[CR]tmux\f[R] to allow graphics
protocols.
Some creative workarounds (Unicode placeholders) are used that are
only implemented in \f[CR]kitty\f[R] version >= 0.28 right now.
Also needs \f[CR]tmux\f[R]
version >= 3.3.
You have to explicitly set the \f[CR]-pk\f[R] option inside
tmux as timg would otherwise just use block-pixels there.
.TP
\f[B]iterm2\f[R] (short `i')
The iterm2 graphics is another image protocol that allows for full
24 Bit RGB/32 Bit RGBA images.
It originated on the popular macOS
OpenSource iTerm2 terminal but is now also implemented by
\f[CR]wezterm\f[R] and
\f[CR]konsole\f[R] as well as in the \f[CR]VSCode\f[R]-terminal (enable
in vscode settings
at checkbox `Terminal > Integrated: Enable images').
.PP
If no option is given, default is taken from environment variable
\f[B]TIMG_PIXELATION\f[R].
If that is not set, \f[CR]timg\f[R] attempts to auto-detect the
available terminal feature.
Not all full-resolution compatible terminals can be auto-detected so it
will fall back to \f[B]quarter\f[R] in that case.
Consider passing the \f[CR]-p\f[R] option or set the
\f[CR]TIMG_PIXELATION\f[R] environment variable in that case.
.RE
.TP
\f[B]--grid\f[R]=<\f[I]cols\f[R]>[x<\f[I]rows\f[R]>]
Arrange images in a grid.
If only one parameter is given, arranges in a square grid
(e.g.\ \f[B]--grid=3\f[R] makes a 3x3 grid).
Alternatively, you can choose columns and rows that should fit on one
terminal (e.g.\ \f[B]--grid=3x2\f[R]).
This is a very useful option if you want to browse images (see examples
below).
.TP
\f[B]-C\f[R], \f[B]--center\f[R]
Center image(s) and title(s) horizontally in their alotted space.
.TP
\f[B]--title\f[R][=<\f[I]format-string\f[R]>]
Print title above each image.
It is possible to customize the title by giving a format string.
In this string, the following format specifiers are expanded:
.RS
.IP \[bu] 2
\f[CR]%f\f[R] = full filename
.IP \[bu] 2
\f[CR]%b\f[R] = basename (filename without path)
.IP \[bu] 2
\f[CR]%w\f[R] = image width
.IP \[bu] 2
\f[CR]%h\f[R] = image height
.IP \[bu] 2
\f[CR]%D\f[R] = internal decoder used (image, video, qoi, sta,
openslide, \&...)
.PP
If no format string is given, this is just the filename (\f[CR]%f\f[R])
or, if set, what is provided in the \f[CR]TIMG_DEFAULT_TITLE\f[R]
environment variable.
.RE
.TP
\f[B]-f\f[R] <\f[I]filelist-file\f[R]>
Read a list of image filenames to show from this file.
The list needs to be newline separated, so one filename per line.
This option can be supplied multiple times in which case it appends to
the end of the list of images to show.
If there are also filenames on the command line, they will also be shown
after the images from the file list have been shown.
.RS
.PP
Absolute filenames in the list are used as-is, relative filenames are
resolved relative to the \f[I]current directory\f[R].
.PP
(Note: this behavior changed between v1.5.0 and v1.5.1: previously, -f
was resolving relative to the filelist; this changed to current
directory.
Look-up relative to the file list is provided with with uppercase
\f[B]-F\f[R]).
.RE
.TP
\f[B]-F\f[R] <\f[I]filelist-file\f[R]>
Like \f[B]-f\f[R], but relative filenames are resolved relative to the
\f[I]directory the file list resides in\f[R].
This allows you to e.g.\ have a file list at the top of a directory
hierarchy with relative filenames but are not required to change into
that directory first for \f[CR]timg\f[R] to resolve the relative paths.
.TP
\f[B]-b\f[R] <\f[I]background-color\f[R]>
Set the background color for transparent images.
Common HTML/SVG/X11 color strings are supported, such as
\f[B]purple\f[R], \f[B]#00ff00\f[R] or \f[B]rgb(0, 0, 255)\f[R].
.RS
.PP
The special value \f[B]none\f[R] switches off blending background color
and relies on the terminal to provide alpha-blending.
This works well with kitty and iterm2 graphics, but might result in less
blended edges for the text-block based pixelations.
.PP
Another special value is \f[B]auto\f[R]:
.IP \[bu] 2
For graphics modes, this behaves like \f[CR]none\f[R], sending RGBA
images for alpha-blending directly in the terminal.
.IP \[bu] 2
For text-block modes, this attempts to query the terminal for its
background color (Best effort; not all terminals support that).
If detection fails, the fallback is `black'.
.PP
Default is \f[B]auto\f[R].
.RE
.TP
\f[B]-B\f[R] <\f[I]checkerboard-other-color\f[R]>
Show the background of a transparent image in a checkerboard pattern
with the given color, which alternates with the \f[B]-b\f[R] color.
The allows for HTTML/SVG/X11 colors like \f[B]-b\f[R].
.RS
.PP
The checkerboard pattern has square blocks one character cell wide and
half a cell high (see \f[CR]--pattern-size\f[R] to change).
.PP
A common combination would be to use \f[CR]-bgray -Bdarkgray\f[R] for
backgrounds known from image editors.
.PP
Sometimes setting such background is the only way to see an image, e.g.
if you have an image with a transparent background showing content with
the same color as your terminal background\&...
.RE
.TP
\f[B]--pattern-size\f[R]=<\f[I]size-factor\f[R]>
Scale background checkerboard pattern by this factor.
.TP
\f[B]--auto-crop\f[R][=<\f[I]pre-crop\f[R]>]
Trim same-color pixels around the border of image before displaying.
Use this if there is a boring even-colored space aorund the image which
uses too many of our available few pixels.
.RS
.PP
The optional pre-crop is number of pixels to unconditionally trim all
around the original image, for instance to remove a thin border.
The link in the EXAMPLES section shows an example how this improves
showing an xkcd comic with a border.
.RE
.TP
\f[B]--rotate\f[R]=<\f[I]exif\f[R]|\f[I]off\f[R]>
If `exif', rotate the image according to the exif data stored in the
image.
With `off', no rotation is extracted or applied.
.TP
\f[B]-W\f[R], \f[B]--fit-width\f[R]
Scale to fit width of the available space.
This means that the height can overflow, e.g.\ be longer than the
terminal, so might require scrolling to see the full picture.
Default behavior is to fit within the allotted width \f[I]and\f[R]
height.
.TP
\f[B]-U\f[R], \f[B]--upscale\f[R][=i]
Allow Upscaling.
If an image is smaller than the terminal size, scale it up to fit the
terminal.
.RS
.PP
By default, larger images are only scaled down and images smaller than
the available pixels in the terminal are left at the original size (this
helps assess small deliberately pixelated images such as icons in their
intended appearance).
This option scales up smaller images to fit available space
(e.g.\ icons).
.PP
The long option allows for an optional parameter \f[B]--upscale=i\f[R]
that forces the upscaling to be in integer increments to keep the
`blocky' appearance of an upscaled image without bilinear scale
`fuzzing'.
.RE
.TP
\f[B]--clear\f[R][=every]
Clear screen before \f[I]first\f[R] image.
This places the image at the top of the screen.
.RS
.PP
There is an optional parameter `\f[I]every\f[R]'
(\f[B]--clear=every\f[R]), which will clean the screen before every
image.
This only makes sense if there is no \f[B]--grid\f[R] used and if you
allow some time to show the image of course, so good in combination with
\f[B]-w\f[R].
.RE
.TP
\f[B]-V\f[R]
Tell \f[CR]timg\f[R] that this is a video, directly read the content as
video and don\[cq]t attempt to probe image decoding first.
.RS
.PP
Usually, \f[CR]timg\f[R] will first attempt to interpret the data as
image, but if it that fails, will fall-back to try interpret the file as
video.
However, if the file is coming from stdin, the first bytes used to probe
for the image have already been consumed so the fall-back would fail in
that case\&...
Arguably, this should be dealt with automatically but isn\[cq]t :)
.PP
Long story short: if you read a video from a pipe, use \f[B]-V\f[R].
See link in EXAMPLES section for a an example.
.RE
.TP
\f[B]-I\f[R]
This is an image, don\[cq]t attempt to fall back to video decoding.
Somewhat the opposite of \f[B]-V\f[R].
.TP
\f[B]-w\f[R]<\f[I]seconds\f[R]>
Wait time in seconds between images when multiple images are given on
the command line.
Fractional values such as \f[CR]-w0.3\f[R] are allowed.
.TP
\f[B]-wr\f[R]<\f[I]seconds\f[R]>
Similar to \f[CR]-w\f[R], but wait time between \f[I]rows\f[R].
If a \f[CR]--grid\f[R] is chosen, this will wait at the end of a
completed row.
If no grid is chosen, then this is equivalent to \f[CR]-w\f[R].
Both, \f[CR]-w\f[R] and \f[CR]-wr\f[R] can be provided to show each
image individually, but also have a wait time between rows.
.TP
\f[B]-a\f[R]
Switch off anti-aliasing.
The images are scaled down to show on the minimal amount of pixels, so
some smoothing is applied for best visual effect.
This option switches off that smoothing.
.TP
\f[B]-g\f[R] \f[I]<width>x<height>\f[R]
Geometry.
Scale output to fit inside given number of character cells.
By default, the size is determined by the available space in the
terminal, so you typically won\[cq]t have to change this.
The image is scaled to fit inside the available box to fill the screen;
see \f[B]-W\f[R] if you want to fill the width.
.RS
.PP
It is possible to only partially specify the size before or after the
\f[CR]x\f[R]-separator, like \f[B]-g<width>x\f[R] or
\f[B]-gx<height>\f[R].
The corresponding other value is then derived from the terminal size.
.RE
.TP
\f[B]-o\f[R] <\f[I]outfile\f[R]>
Write terminal image to given filename instead of stdout.
.TP
\f[B]-E\f[R]
Don\[cq]t hide the cursor while showing images.
.TP
\f[B]--compress\f[R][=<\f[I]level\f[R]>]
For the kitty and iterm2 graphics modes: this chooses the compression
for the transmission to the terminal.
This uses more CPU on timg, but is desirable when connected over a slow
network.
Default compression level is 1 which should be reasonable default in
almost all cases.
To disable, set to 0 (zero).
Use \f[CR]--verbose\f[R] to see the amount of data \f[CR]timg\f[R] sent
to the terminal.
.TP
\f[B]--threads\f[R]=<\f[I]n\f[R]>
Run image decoding in parallel with n threads.
By default, up to 3/4 of the reported CPU-cores are used.
.TP
\f[B]--color8\f[R]
For \f[CR]half\f[R] and \f[CR]quarter\f[R] block pixelation: Use 8 bit
color mode for terminals that don\[cq]t support 24 bit color (only shows
6x6x6 = 216 distinct colors instead of 256x256x256 = 16777216).
.TP
\f[B]--version\f[R]
Print version and exit.
.TP
\f[B]--verbose\f[R]
Print some useful information such as observed terminal cells, chosen
pixelation, or observed frame-rate.
.TP
\f[B]-h\f[R]
Print command line option help and exit.
.TP
\f[B]--help\f[R]
Page through detailed manpage-like help and exit.
.TP
\f[B]--debug-no-frame-delay\f[R]
Don\[cq]t delay frames in videos or animations but emit as fast as
possible.
This might be useful for developers of terminal emulations to do
performace tests or simply if you want to redirect the output to a file
and don\[cq]t want to wait.
.SS For Animations, Scrolling, or Video
Usually, animations are shown in full in an infinite loop.
These options limit infinity.
.TP
\f[B]-t\f[R]<\f[I]seconds\f[R]>
Stop an animation after these number of seconds.
Fractional values are allowed.
.TP
\f[B]--loops\f[R]=<\f[I]num\f[R]>
Number of loops through a fully cycle of an animation or video.
A value of \f[I]-1\f[R] stands for `forever'.
.RS
.PP
If \f[I]not\f[R] set, videos loop once, animated images forever unless
there is more than one file to show.
If there are multiple files on the command line, animated images are
only shown once if \f[B]--loops\f[R] is not set to prevent the output
get stuck on the first animation.
.RE
.TP
\f[B]--frames\f[R]=<\f[I]frame-count\f[R]>
Only render the first \f[I]frame-count\f[R] frames in an animation or
video.
If frame-count is set to 1, the output just is the first frame so
behaves like a static image.
Typically you\[cq]d use it when you show a bunch of images to quickly
browse without waiting for animations to finish.
.TP
\f[B]--frame-offset\f[R]=<\f[I]offset\f[R]>
For animations or videos, start at this frame.
.SS Scrolling
.TP
\f[B]--scroll\f[R][=<\f[I]ms\f[R]>]
Scroll horizontally with an optional delay between updates (default:
60ms).
In the EXAMPLES section is an example how to use ImageMagick to create a
text that you then can scroll with \f[B]timg\f[R] over the terminal.
.TP
\f[B]--delta-move\f[R]=<\f[I]dx\f[R]>:<\f[I]dy\f[R]>
Scroll with delta x and delta y.
The default of 1:0 scrolls it horizontally, but with this option you can
scroll vertically or even diagonally.
.SH RETURN VALUES
Exit code is
.TP
\f[B]0\f[R]
On reading and displaying all images successfully.
.TP
\f[B]1\f[R]
If any of the images could not be read or decoded or if there was no
image provided.
.TP
\f[B]2\f[R]
If an invalid option or parameter was provided.
.TP
\f[B]3\f[R]
If \f[CR]timg\f[R] could not determine the size of terminal (not a
tty?).
Provide \f[B]-g\f[R] option to provide size of the output to be
generated.
.TP
\f[B]4\f[R]
Could not write to output file provided with \f[B]-o\f[R].
.TP
\f[B]5\f[R]
Could not read file list file provided with \f[B]-f\f[R].
.SH ENVIRONMENT
.TP
\f[B]TIMG_DEFAULT_TITLE\f[R]
The default format string used for \f[CR]--title\f[R].
If not given, the default title format string is
\[dq]\f[CR]%f\f[R]\[dq].
.TP
\f[B]TIMG_PIXELATION\f[R]
The default pixelation if not provided by the \f[CR]-p\f[R] or
\f[CR]--pixelation\f[R] option (see choice of values there).
If neither the environment variable nor the option is given, timg
attempts to auto-detect the best pixelation for the terminal.
.TP
\f[B]TIMG_USE_UPPER_BLOCK\f[R]
If this environment variable is set to the value \f[B]1\f[R],
\f[CR]timg\f[R] will use the U+2580 - `Upper Half Block' Unicode
character.
.RS
.PP
To display pixels, \f[CR]timg\f[R] uses a Unicode half block and sets
the foreground color and background color to get two vertical pixels.
By default, it uses the U+2584 - `Lower Half Block' character to achieve
this goal.
This has been chosen as it resulted in the best image in all tested
terminals (konsole, gnome terminal and cool-retro-term).
So usually, there is no need to change that.
But if the terminal or font result in a funny output, this might be
worth a try.
This is an environment variable because if it turns out to yield a
better result on your system, you can set it once in your profile and
forget about it.
.RE
.TP
\f[B]TIMG_FONT_WIDTH_CORRECT\f[R]
A floating point stretch factor in width direction to correct for fonts
that don\[cq]t produce quite square output.
.RS
.PP
If you notice that the image displayed is not quite the right aspect
ratio because of the font used, you can modify this factor to make it
look correct.
Increasing the visual width by 10% would be setting it to
\f[I]TIMG_FONT_WIDTH_CORRECT=1.1\f[R] for instance.
.PP
This is an environment variable, so that you can set it once to best fit
your terminal emulator of choice.
.RE
.TP
\f[B]TIMG_ALLOW_FRAME_SKIP\f[R]
Set this environment variable to 1 if you like to allow \f[CR]timg\f[R]
to drop frames when play-back is falling behind.
This is particularly useful if you are on a very slow remote terminal
connection that can\[cq]t keep up with playing videos.
Or if you have a very slow CPU.
.SH EXAMPLES
Some example invocations including scrolling text or streaming an online
video are put together at \c
.UR https://timg.sh/#examples
.UE \c
.PP
It might be useful to prepare some environment variables or aliases in
the startup profile of your shell.
The \f[CR]timg\f[R] author typically has these set:
.IP
.EX
# The default --title format
export TIMG_DEFAULT_TITLE=\[dq]%b (%wx%h)\[dq]

# image list. An alias to quickly list images; invoke with ils images/*
alias ils=\[aq]timg --grid=3x1 --upscale=i --center --title --frames=1 -bgray -Bdarkgray\[aq]
.EE
.SH KNOWN ISSUES
This requires a terminal that can deal with Unicode characters and 24
bit color escape codes.
This will be problematic on really old installations or if you want to
display images on some limited text console.
.PP
The option \f[B]-V\f[R] should not be necessary for streaming video from
stdin; timg should internally buffer bytes it uses for probing.
.SH BUGS
Report bugs at \c
.UR http://github.com/hzeller/timg/issues
.UE \c
.SH COPYRIGHT
Copyright (c) 2016..2023 Henner Zeller.
This program is free software, provided under the GNU GPL version 2.0.
.PP
\c
.UR https://gnu.org/licenses/gpl-2.0.html
.UE \c
.SH SEE ALSO
GraphicsMagick, ffmpeg(1), utf-8(7), unicode(7), kitty(1),
https://en.wikipedia.org/wiki/Sixel
.SH AUTHORS
Henner Zeller.