FreeBSD Manual Pages

home | help

timg(1) timg(1)

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 redi-
recting 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 im-
age 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 par-
allel 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 reso-
lution. 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 cor-
rectly, 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 ac-
cordingly, no worries), and can only represent colors approx-
imately, as the four quadrant sub-pixels can only be fore-
ground or background color. This increases the spatial reso-
lution in x-direction at expense of slight less color accu-
racy. 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 pro-
vides full resolution on a 256 color palette that timg opti-
mizes for each image. You find the sixel protocol imple-
mented by xterm (invoke with -ti vt340) and mlterm or kon-
sole. 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 pro-
tocols. 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 im-
plemented by wezterm and konsole as well as in the VS-
Code-terminal (enable in vscode settings at checkbox `Termi-
nal > Integrated: Enable images').

If no option is given, default is taken from environment variable
TIMG_PIXELATION. If that is not set, timg attempts to auto-detect
the available terminal feature. Not all full-resolution compatible
terminals can be auto-detected so it will fall back to quarter in
that case. Consider passing the -p option or set the TIMG_PIXELA-
TION environment variable in that case.

--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 vari-
able.

-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 op-
tion 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 direc-
tory 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 re-
solve 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 al-
lows 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 back-
grounds 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 re-
quire 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[=every]
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 au-
tomatically 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 vi-
sual 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 compres-
sion 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 ter-
minals that don't support 24 bit color (only shows 6x6x6 = 216 dis-
tinct colors instead of 256x256x256 = 16777216).

--version
Print version and exit.

--verbose
Print some useful information such as observed terminal cells, cho-
sen 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 pos-
sible. This might be useful for developers of terminal emulations
to do performance 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 termi-
nal.

--delta-move=<dx>:<dy>
Scroll with delta x and delta y. The default of 1:0 scrolls it hor-
izontally, 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?). Pro-
vide -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 de-
fault title format string is "%f".

TIMG_PIXELATION
The default pixelation if not provided by the -p or --pixelation op-
tion (see choice of values there). If neither the environment vari-
able nor the option is given, timg attempts to auto-detect the best
pixelation for the terminal.

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 fore-
ground 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 set-
ting 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 use-
ful 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.

TIMG_SIXEL_NEWLINE_WORKAROUND
Set this environment variable if you are on a Sixel terminal and no-
tice that videos `scroll' or grid-view items are not perfectly
aligned vertically. Sometimes this manifests only for pictures of a
particular height. Valid values are 0, 1, 2, 3 which address vari-
ous subtle differences in which sixel terminals behave. Default 0.

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

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.

Dec 2023 timg(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=timg&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages