Terminal Image and Video Viewer

https://timg.sh/

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).

Pixelation

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 | ----------------------------------|------------|---------| | | |

Grid display

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).

Grid view of 4 pictures

<details> <summary>This is how the same grid looks if no high-res mode is available with - `-p quarter` ...</summary>

</details>

Synopsis

usage: timg [options] <image/video> [<image/video>...]
Options (most common first):
        -p<pixelation> : Pixelation: 'h' = half blocks    'q' = quarter blocks
                                     'k' = kitty graphics 'i' = iTerm2 graphics
                                     's' = sixel graphics
                         Default: Auto-detect graphics, otherwise 'quarter'.
        --grid=<cols>[x<rows>] : Arrange images in a grid ("contact sheet").
        -C, --center   : Center image horizontally in available cell.
        --title[=<fmt_str>]: Print title above each image. Accepts the following
                         format parameters: %f = full filename; %b = basename
                                            %w = image width; %h = height
                                            %D = internal decoder used
                         If no parameter is given, defaults to "%f"
                         Env-var override with TIMG_DEFAULT_TITLE
        -f<filelist>   : Read newline-separated list of image files to show.
                         Relative filenames are relative to current directory.
                         (-f and -F can be provided multiple times.)
        -F<filelist>   : like -f, but relative filenames considered relative
                         to the directory containing the filelist.
        -b<str>        : Background color to use behind alpha channel. Format
                         color name like 'yellow', '#rrggbb', 'auto' or 'none'.
                        'auto' is terminal background color. (default 'auto').
        -B<str>        : Checkerboard pattern color to use on alpha.
        --pattern-size=<n> : Integer factor scale of the checkerboard pattern.
        --auto-crop[=<pre-crop>] : Crop away all same-color pixels around image.
                         The optional pre-crop is the width of border to
                         remove beforehand to get rid of an uneven border.
        --rotate=<exif|off> : Rotate according to included exif orientation.
                              or 'off'. Default: exif.
        -W, --fit-width: Scale to fit width of available space, even if it
                         exceeds height.
        -U, --upscale[=i]: Allow Upscaling. If an image is smaller than the
                         available frame (e.g. an icon), enlarge it to fit.
                         Optional parameter 'i' only enlarges in integer steps.
        --clear[=every]: Clear draw area first. Optional argument 'every' will
                         clear before every image (useful with -w/-wr,
                         but not with --grid)
        -V             : Directly use Video subsystem. Don't probe image
                         decoding first (useful, if you stream video from stdin)
        -I             : Only  use Image subsystem. Don't attempt video decoding
        -w<seconds>    : Wait time between images (default: 0.0).
        -wr<seconds>   : like above, but wait time between rows in grid.
        -a             : Switch off anti-aliasing (default: on).
        -g<w>x<h>      : Output geometry in character cells. Partial geometry
                         leaving out one value -g<w>x or -gx<h> is possible,
                         the other value it then derived from the terminal size.
                         Default derived from terminal size is 160x50
        -o<outfile>    : Write to <outfile> instead of stdout.
        -E             : Don't hide the cursor while showing images.
        --compress[=level]: Only for -pk or -pi: Compress image data. More
                         CPU use, but less used bandwidth. (default: 1)
        --threads=<n>  : Run image decoding in parallel with n threads
                         (Default 3, 3/4 #cores on this machine)
        --color8       : Choose 8 bit color mode for -ph or -pq
        --version      : Print detailed version including used libraries.
                         (v1.5.3+)
        --verbose      : Print some stats after images shown.
        -h             : Print this help and exit.
        --help         : Page through detailed manpage-like help and exit.

  Scrolling
        --scroll[=<ms>]       : Scroll horizontally (optionally: delay ms (60)).
        --delta-move=<dx:dy>  : delta x and delta y when scrolling (default:1:0)

  For Animations, Scrolling, or Video
  These options influence how long/often and what is shown.
        --loops=<num> : Number of runs through a full cycle. -1 means 'forever'.
                        If not set, videos loop once, animated images forever
                        unless there is more than one file to show.
        --frames=<num>: Only show first num frames (if looping, loop only these)
        --frame-offset=<num>: Start animation/video at this frame
        -t<seconds>   : Stop after this time, independent of --loops or --frames

Examples

timg some-image.jpg                # display a static image
timg -g50x50 some-image.jpg        # display image fitting in box of 50x50 pixel

# Multiple images
timg *.jpg                         # display all *.jpg images
timg --title *.jpg                 # .. show name in title (short option -F)
timg --title="%b (%wx%h)" *.jpg    # show short filename and image size as title
timg --grid=3x2 *.jpg              # arrange in 3 columns, 2 rows in terminal
timg --fit-width --grid=3 *.jpg    # maximize use of column width (short: -W)
timg --grid=3 -t5 *.gif            # Load gifs one by one in grid. Play each for 5sec.

# Putting it all together; making an alias to list images; let's call it ils = 'image ls'
# This prints images two per row with a filename title. Only showing one frame
# so for animated gifs only the first frame is shown statically.
# With hi-res iTerm or Kitty terminals, consider more columns, e.g --grid=4x1
# Put this line in your ~/.bashrc
alias ils='timg --grid=2x1 --upscale=i --center --title --frames=1 '

# ... using this alias on images outputs a useful column view
ils *.jpg *.gif

# Read the list of images to load from a file. One filename per line.
locate "*.jpg" > /tmp/allimg.txt ; timg -f /tmp/allimg.txt

# Show a PDF document, use full width of terminal, trim away empty border
timg -W --auto-crop some-document.pdf
timg --frames=1 some-document.pdf    # Show a PDF, but only first page

# Reading images from a pipe. The filename '-' means 'read from stdin.
# In this example generating a QR code and have timg display it:
qrencode -s1 -m2 "http://timg.sh/" -o- | timg -

# Here, using gnuplot output right in the shell
echo "set terminal png; plot sin(x);" | gnuplot | timg -

# Open an image from a URL. URLs are internally actually handled by the
# video subsystem, so it is treated as

Timg

Install / Use

README