Provided by: timg_1.5.2-1build2_amd64 
NAME
timg - A terminal image and video viewer
SYNOPSIS
timg [<options>] <image/video> [<image/video>...]
DESCRIPTION
Show images, play animated gifs, scroll static images or play videos in the terminal.
Even show PDFs.
View images without leaving the comfort of your shell. Sometimes this is the only way if
your terminal is connected remotely via ssh.
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 --grid. The output is emitted in-line with minimally messing
with your terminal, so you can simply go back in history using your terminals’ scroll-bar
(Or redirecting the output to a file allows you to later simply cat that file to your
terminal. Even less -R seems to be happy with such output).
The special filename “-” stands for standard input, so you can read an image from a pipe.
If the input from a pipe is a video, use the -V option (see below).
Under the hood, timg 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 -I
or -V you can choose to use only one of these file decoders ({GraphicsMagick, turbojpeg,
qoi} or libav respectively).
OPTIONS
General Options
Most likely commonly needed options first.
-p <[h|q|s|k|i]>, --pixelation=[h|q|s|k|i]
Choice for pixelation of the content.
Available values
half (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'.
quarter (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.
sixel (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 timg optimizes for each image. You find the sixel
protocol implemented by xterm (invoke with -ti vt340) and mlterm or konsole.
Recently, more terminal emulators re-discovered this format and started
implementing it. This does not work in tmux, but there is a tmux fork with
sixel support around.
kitty (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 kitty
terminal but also e.g. konsole. You can even use this in tmux: This is the
only protocol that can work around the reluctance of tmux to allow graphics
protocols. Some creative workarounds (Unicode placeholders) are used that
are only implemented in kitty version >= 0.28 right now. Also needs tmux
version >= 3.3. You have to explicitly set the -pk option inside tmux as
timg would otherwise just use block-pixels there.
iterm2 (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 wezterm and konsole.
timg attempts to recognize the available terminal feature, but it might not be able
to auto-detect all full-resolution compatible terminals and fall back to quarter in
that case. In that case you’d pass the -p option to choose the best pixelation.
If you’re always working in the same terminal, maybe create an alias, e.g. alias
timg='timg -ps'.
--grid=<cols>[x<rows>]
Arrange images in a grid. If only one parameter is given, arranges in a square
grid (e.g. --grid=3 makes a 3x3 grid). Alternatively, you can choose columns and
rows that should fit on one terminal (e.g. --grid=3x2). This is a very useful
option if you want to browse images (see examples below).
-C, --center
Center image(s) and title(s) horizontally in their alotted space.
--title=[format-string]
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:
• %f = full filename
• %b = basename (filename without path)
• %w = image width
• %h = image height
• %D = internal decoder used (image, video, qoi, sta, openslide, ...)
If no format string is given, this is just the filename (%f) or, if set, what is
provided in the TIMG_DEFAULT_TITLE environment variable.
-f <filelist-file>
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.
Absolute filenames in the list are used as-is, relative filenames are resolved
relative to the current directory.
(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).
-F <filelist-file>
Like -f, but relative filenames are resolved relative to the directory the file
list resides in. 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 timg to resolve the relative paths.
-b <background-color>
Set the background color for transparent images. Common HTML/SVG/X11 color strings
are supported, such as purple, #00ff00 or rgb(0, 0, 255).
The special value none 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.
Another special value is auto:
• For graphics modes, this behaves like none, sending RGBA images for alpha-
blending directly in the terminal.
• 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'.
Default is auto.
-B <checkerboard-other-color>
Show the background of a transparent image in a checkerboard pattern with the given
color, which alternates with the -b color. The allows for HTTML/SVG/X11 colors
like -b.
The checkerboard pattern has square blocks one character cell wide and half a cell
high (see --pattern-size to change).
A common combination would be to use -bgray -Bdarkgray for backgrounds known from
image editors.
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...
--pattern-size=<size-factor>
Scale background checkerboard pattern by this factor.
--auto-crop[=<pre-crop>]
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.
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.
--rotate=<exif|off>
If `exif', rotate the image according to the exif data stored in the image. With
`off', no rotation is extracted or applied.
-W, --fit-width
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 and height.
-U, --upscale=[i]
Allow Upscaling. If an image is smaller than the terminal size, scale it up to fit
the terminal.
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).
The long option allows for an optional parameter --upscale=i that forces the
upscaling to be in integer increments to keep the `blocky' appearance of an
upscaled image without bilinear scale `fuzzing'.
--clear
Clear screen before first image. This places the image at the top of the screen.
There is an optional parameter `every' (--clear=every), which will clean the screen
before every image. This only makes sense if there is no --grid used and if you
allow some time to show the image of course, so good in combination with -w.
-V Tell timg that this is a video, directly read the content as video and don’t
attempt to probe image decoding first.
Usually, timg 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’t :)
Long story short: if you read a video from a pipe, use -V. See link in EXAMPLES
section for a an example.
-I This is an image, don’t attempt to fall back to video decoding. Somewhat the
opposite of -V.
-w<seconds>
Wait time in seconds between images when multiple images are given on the command
line. Fractional values such as -w0.3 are allowed.
-wr<seconds>
Similar to -w, but wait time between rows. If a --grid is chosen, this will wait
at the end of a completed row. If no grid is chosen, then this is equivalent to
-w. Both, -w and -wr can be provided to show each image individually, but also
have a wait time between rows.
-a 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.
-g <width>x<height>
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’t have to change this. The image is scaled to fit inside the available box to
fill the screen; see -W if you want to fill the width.
It is possible to only partially specify the size before or after the x-separator,
like -g<width>x or -gx<height>. The corresponding other value is then derived from
the terminal size.
-o <outfile>
Write terminal image to given filename instead of stdout.
-E Don’t hide the cursor while showing images.
--compress[=<level>]
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
--verbose to see the amount of data timg sent to the terminal.
--threads=<n>
Run image decoding in parallel with n threads. By default, up to 3/4 of the
reported CPU-cores are used.
--color8
For half and quarter block pixelation: Use 8 bit color mode for terminals that
don’t support 24 bit color (only shows 6x6x6 = 216 distinct colors instead of
256x256x256 = 16777216).
--version
Print version and exit.
--verbose
Print some useful information such as observed terminal cells, chosen pixelation,
or observed frame-rate.
-h Print command line option help and exit.
--help Page through detailed manpage-like help and exit.
--debug-no-frame-delay
Don’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’t want to wait.
For Animations, Scrolling, or Video
Usually, animations are shown in full in an infinite loop. These options limit infinity.
-t<seconds>
Stop an animation after these number of seconds. Fractional values are allowed.
--loops=<num>
Number of loops through a fully cycle of an animation or video. A value of -1
stands for `forever'.
If not 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 --loops is not set to prevent the output get stuck on the first
animation.
--frames=<frame-count>
Only render the first frame-count 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’d use it when you show a bunch of images to quickly browse without
waiting for animations to finish.
--frame-offset=<offset>
For animations or videos, start at this frame.
Scrolling
--scroll[=<ms>]
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 timg over the terminal.
--delta-move=<dx>:<dy>
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.
RETURN VALUES
Exit code is
0 On reading and displaying all images successfully.
1 If any of the images could not be read or decoded or if there was no image
provided.
2 If an invalid option or parameter was provided.
3 If timg could not determine the size of terminal (not a tty?). Provide -g option
to provide size of the output to be generated.
4 Could not write to output file provided with -o.
5 Could not read file list file provided with -f.
ENVIRONMENT
TIMG_DEFAULT_TITLE
The default format string used for --title. If not given, the default title format
string is "%f".
TIMG_USE_UPPER_BLOCK
If this environment variable is set to the value 1, timg will use the U+2580 -
`Upper Half Block' Unicode character.
To display pixels, timg 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.
TIMG_FONT_WIDTH_CORRECT
A floating point stretch factor in width direction to correct for fonts that don’t
produce quite square output.
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 TIMG_FONT_WIDTH_CORRECT=1.1 for
instance.
This is an environment variable, so that you can set it once to best fit your
terminal emulator of choice.
TIMG_ALLOW_FRAME_SKIP
Set this environment variable to 1 if you like to allow timg 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’t keep up with playing videos. Or if you have
a very slow CPU.
EXAMPLES
Some example invocations including scrolling text or streaming an online video are put
together at <https://timg.sh/#examples>
It might be useful to prepare some environment variables or aliases in the startup profile
of your shell. The timg author typically has these set:
# The default --title format
export TIMG_DEFAULT_TITLE="%b (%wx%h)"
# image list. An alias to quickly list images; invoke with ils images/*
alias ils='timg --grid=3x1 --upscale=i --center --title --frames=1 -bgray -Bdarkgray'
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.
The option -V should not be necessary for streaming video from stdin; timg should
internally buffer bytes it uses for probing.
BUGS
Report bugs at <http://github.com/hzeller/timg/issues>
COPYRIGHT
Copyright (c) 2016..2023 Henner Zeller. This program is free software, provided under the
GNU GPL version 2.0.
<https://gnu.org/licenses/gpl-2.0.html>
SEE ALSO
GraphicsMagick, ffmpeg(1), utf-8(7), unicode(7), kitty(1),
https://en.wikipedia.org/wiki/Sixel
AUTHORS
Henner Zeller.
Jul 2023 timg(1)