viu

Simple terminal image viewer written in Rust


Keywords
cli, image-viewer, rust, terminal
License
MIT
Install
brew install viu

Documentation

Description

A small command-line application to view images from the terminal written in Rust. It is basically the front-end of viuer. It uses either iTerm or Kitty graphics protocol, if supported. If not, lower half blocks (▄ or \u2584) are displayed instead.

Based on the value of $TERM, viuer decides which protocol to use. For half blocks, $COLORTERM is inspected. If it contains either truecolor or 24bit, truecolor (16 million colors) will be used. If not, it will fallback to using only ansi256. A nice explanation can be found in this gist.

Features

  • Native iTerm and Kitty support
  • Animated GIF support
  • Accept media through stdin
  • Custom dimensions
  • Transparency

Installation

From source (recommended)

Installation from source requires a local Rust environment. Please note that at least Rust 1.39 is required.

git clone https://github.com/atanunq/viu.git

# Build & Install
cd viu/
cargo install --path .

# Use
viu img/giphy.gif

Or without cloning:

cargo install viu

Binary

A precompiled binary can be downloaded from the release page. GPG fingerprint is B195BADA40BEF20E4907A5AC628280A0217A7B0F.

Wapm

Viu can be installed in Linux, macOS and Windows using wapm:

wapm install -g viu

Packages

Arch Linux

There is an AUR package available for Arch Linux.

NetBSD

Available in graphics/viu.

Usage

Examples

On a Kitty terminal:

Kitty

On a Mac with iTerm:

iTerm

Using half blocks (Kitty protocol and tmux do not get along):

Demo

Demo

Demo

Ctrl-C was pressed to stop the GIFs.

When viu receives only one file and it is GIF, it will be displayed over and over until Ctrl-C is pressed. However, when couple of files are up for display (second example) the GIF will be displayed only once.

iTerm note

iTerm can handle GIFs by itself with better performance, but configuration through --once and --frame-rate will have no effect there.

Aspect Ratio

If no flags are supplied to viu it will try to get the size of the terminal where it was invoked. If it succeeds it will fit the image and preserve the aspect ratio. The aspect ratio will be changed only if both options -w and -h are used together.

Command line options

USAGE:
    viu [FLAGS] [OPTIONS] [FILE]...
    When FILE is -, read standard input.

FLAGS:
    -m, --mirror         Display a mirror of the original image
    -n, --name           Output the name of the file before displaying
    -1, --once           Only loop once through the animation
    -r, --recursive      Recurse down directories if passed one
    -s, --static         Show only first frame of gif
    -t, --transparent    Display transparent image with transparent background
    -v, --verbose        Output what is going on

OPTIONS:
    -f, --frame-rate <frames-per-second>    Play gif at the given frame rate
    -h, --height <height>    Resize the image to a provided height
    -w, --width <width>      Resize the image to a provided width

ARGS:
    <FILE>...    The image to be displayed