A terminal image and video viewer.
A user-friendly terminal image viewer that uses graphic capabilities of terminals (Sixel, Kitty or iterm2), or 24-Bit color capabilities and unicode character blocks if these are not available.
On terminals that implement the [sixel] protocol, the [Kitty Graphics Protocol], or the [iTerm2 Graphics Protocol] this displays images in full resolution.
But even the fallback block display is usable.
Displays regular images, plays animated gifs, scrolls static images and plays videos.
Useful if you want to have a quick visual check without leaving the comfort of your shell and having to start a bulky image viewer. Sometimes this is the only way if your terminal is connected remotely via ssh. And of course if you don't need the resolution. While icons typically fit pixel-perfect, larger images are scaled down to match the resolution.
The command line accepts any number of image/video filenames that it shows
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
it).
On a regular terminal, block-characters are used to output images. Half blocks present pixels color-accurately, and quarter blocks provide a higher spatial resolution at the expense of slightly worse color accuracy. These modes should be compatible with most common terminals that support UTF8 and 24Bit color.
If you are on a [Kitty][Kitty Graphics Protocol], [iTerm2], or [wezterm] terminal, or a terminal that supports the sixel protocol, images can be shown in full resolution.
| -p kitty, -p iterm2, or -p sixel | -p quarter | -p half |
|---|---|---|
Images can be shown in a grid, which is very useful if you quickly want to
browse through a lot of images. You can choose to show the filename as title,
so it is easy to find exactly the filename you're looking for (The following
grid uses --grid=2 and is pixelated -p iterm2).
…
…
| -b auto | -b lightgreen | -b lightgreen -B yellow | -b none |
|---|---|---|---|
| --pattern-size=1 | --pattern-size=4 |
|---|---|
There are many terminal based file-browsers. Adding timg to their
configuration is usually straight forward.
…
…
This section contains some details that you only might need to ever look at if the output is not as expected.
The [Kitty], [iTerm2], and [wezterm] terminals as well as other modern terminals such as [Konsole] or the terminal in [vscode] allow to directly display high-resolution pictures.
If timg is running in such a terminal, it will attempt to auto-detect that
feature and use that mode. If your terminal does support the feature but
can't be auto-detected, you can explicitly choose the pixelation option
in question with command line flag or environment variable (see timg --help).
(Please file an issue with timg if auto-detect does not work).
The terminal in [vscode] to display images in high-resolution, you
need to enable the Terminal > Integrated: Enable Images setting in vscode.
Otherwise you have to explicitly choose -pq to show the 'block' images.
The terminal multiplexer tmux prevents high-resolution images as it filters
out the escape codes.
However, with some ... workarounds, timg can show such pictures
in tmux >= version 3.3 iff in a [kitty]-terminal.
So if you need hi-res pictures in tmux, use a kitty terminal; you
also have to explicitly set the pixelation to -pk (see timg --help for
details).
Other terminals support an older high-resolution [sixel]-protocol, which you
can choose with -ps. Note, for this to work in xterm, you need to invoke it
with xterm -ti vt340.
If watching hi-res videos remotely is too slow (due to high bandwidth
requirements or simply because your terminal has to do more work), try
setting the environment variable TIMG_ALLOW_FRAME_SKIP=1 to allow timg
leaving out frames to stay on track (see timg --help, environment variable
section). You can also attempt to set the --compress level higher.
Terminals that do not support high-resolution image output can still show images by virtue of showing colored blocks.
The half block pixelation (-p half) uses the the unicode
character [▄](U+2584 - 'Lower Half Block')
or [▀](U+2580 - 'Upper Half Block') (depending on the
TIMG_USE_UPPER_BLOCK
environment variable). If the top and bottom color is the same, a simple
space with background color is used.
The quarter block pixelation (-p quarter) uses eight different blocks.
With both of these pixelations, choosing the foreground color and background
24-bit color, timg can simulate 'pixels'. With the half-block pixelation,
this can assign the correct color to the two 'pixels' available in one
character cell, in the quarter pixelation, four 'pixels' have to share two
colors, so the color accuracy is slighlty worse but it allows for higher spatial
resolution.
The -p command line flag allows to choose between -p half, -p quarter,
also possible to just shorten to -ph and -pq. Default is -pq
(see above how this looks like).
Terminals that don't support Unicode or 24 bit color will probably not show
a very pleasant output. For terminals that only do 8 bit color, use the
--color8 command line option.
By default, timg uses the 'lower half block' to show the pixels in -p half
mode. Depending on the font the terminal is using, using the upper block might
look better, so it is possible to change the default with an environment
variable.
Play around with this value if the output looks poor on your terminal. I found
that on my system there is no difference for [konsole][konsole] or xterm but the
[cool-retro-term][cool-retro-term] looks better with the lower block, this is why it is the default.
In some terminals, such as [alacritty] (and only with certain font sizes), there seems to be the opposite working better. To change, set this environment variable:
export TIMG_USE_UPPER_BLOCK=1 # change default to use upper block.
(this only will work fully with -p half. In -p quarter mode, there are
additional blocks that can't be worked around)
The image generally looks a bit 'glitchy' if the terminal leaves little space between blocks, so that the wrong background color shows on a single line between pixels. This is likely not intended by the terminal emulator and possibly happening on rounding issues of font height or similar.
Anyway, we can work around it (fully in -p half, partially in -p quarter
mode). In the following illustration you see how that looks like. If you
see that, change the TIMG_USE_UPPER_BLOCK environment variable.
| Glitchy. Change TIMG_USE_UPPER_BLOCK | Looks good |
|---|
| |
Some terminals leave one pixel of horizontal space between characters that result in fine vertical lines in the image. That can't be worked around, send a bug or better pull request to your terminal emulator.
Usually, timg attempts to determine the font aspect ratio and apply some
correction if it is off from the nominal 1:2. But if you notice that the
image displayed is not quite the right aspect ratio because of the terminals
font used, you can set an environment variable TIMG_FONT_WIDTH_CORRECT with
a factor to make it look correctly.
Increasing the visual width by 10% would be setting the value to 1.1 for instance.
export TIMG_FONT_WIDTH_CORRECT=1.1
timg myimage.jpg
This is an environment variable, so that you can set it once to best fit your terminal emulator of choice and don't have to worry about later.
| Terminal font too narrow | Correct. Here with TIMG_FONT_WIDTH_CORRECT=1.375 |
|---|---|
If you have a Sixel terminal in which you observe artifacts such as videos
'scrolling' or the grid view not having images vertically aligned, you might
need to set the TIMG_SIXEL_NEWLINE_WORKAROUND=1 environment variable.
Unfortuantely, some Sixel terminals disagree if there is a newline after an image or not.
sudo apt install timg
nix-env -i timg
brew install timg
The timg release page also
has a minimal binary in the [AppImage package format][AppImage].
To keep the size small, it does not include video decoding or some more
fancy image formats. It is good for many contexts or if you want to try out
timg, but for a full-featured binary, use one from your distribution or
build from source.
…
The dependencies are set-up in the shell.nix, so you're ready to go opening a nix shell
nix-shell
sudo dnf install cmake git g++ pkg-config
sudo dnf install GraphicsMagick-c++-devel turbojpeg-devel libexif-devel libswscale-free-devel librsvg2-devel cairo-devel libdeflate-devel poppler-glib-devel libsixel-devel qoi-devel
# If you want to include video decoding, also install these additional libraries
sudo dnf install libavcodec-free-devel libavformat-free-devel libavdevice-free-devel openslide-devel
sudo dnf install pandoc # If you want to recreate the man page
# Homebrew needs to be available to install required dependencies
brew install cmake git GraphicsMagick webp jpeg-turbo libexif librsvg cairo # needed libs
# If you want to include video decoding, install these additional libraries
brew install ffmpeg
# If you want to add OpenSlide images support
brew install openslide
brew install pandoc # If you want to recreate the man page
In the script below you see that the build system allows for some compile-time choices:
WITH_LIBSIXEL Use libsixel to output images in [sixel] graphics
format. Default ON.WITH_VIDEO_DECODING allow for video decoding. Requires ffmpeg-related
libraries. You typically want this ON (default)WITH_VIDEO_DEVICE this allows for accessing connected video
devices, e.g. you can watch your webcam input (requires
WITH_VIDEO_DECODING).WITH_GRAPHICSMAGICK This is the main image loading library so you
typically want this ON (default).WITH_TURBOJPEG If enabled, uses this for faster jpeg file loading.
You typiNo open issues yet, or sync has not completed.