2020-12-13 15:20:36 +00:00
|
|
|
- [Description](#description)
|
|
|
|
- [Features](#features)
|
|
|
|
- [Installation](#installation)
|
|
|
|
- [From source (recommended)](#from-source-recommended)
|
|
|
|
- [Binary](#binary)
|
|
|
|
- [Packages](#packages)
|
2021-09-16 06:47:38 +00:00
|
|
|
- [MacOS](#macos)
|
2020-12-13 15:20:36 +00:00
|
|
|
- [Arch Linux](#arch-linux)
|
|
|
|
- [NetBSD](#netbsd)
|
|
|
|
- [Usage](#usage)
|
|
|
|
- [Examples](#examples)
|
|
|
|
- [iTerm note](#iterm-note)
|
|
|
|
- [Aspect Ratio](#aspect-ratio)
|
|
|
|
- [Command line options](#command-line-options)
|
2020-12-13 15:13:26 +00:00
|
|
|
|
|
|
|
## Description
|
2020-10-11 21:10:36 +00:00
|
|
|
A small command-line application to view images from the terminal written in Rust. It is basically the
|
2020-12-13 15:13:26 +00:00
|
|
|
front-end of [`viuer`](https://github.com/atanunq/viuer). It uses either [iTerm](https://iterm2.com/documentation-images.html)
|
|
|
|
or [Kitty](https://sw.kovidgoyal.net/kitty/graphics-protocol.html) graphics protocol, if supported.
|
|
|
|
If not, lower half blocks (▄ or \u2584) are displayed instead.
|
2020-03-11 14:07:45 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
Based on the value of `$TERM`, `viuer` decides which protocol to use. For half
|
2020-10-23 21:14:35 +00:00
|
|
|
blocks, `$COLORTERM` is inspected. If it contains either `truecolor` or `24bit`,
|
2020-03-11 14:07:45 +00:00
|
|
|
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](https://gist.github.com/XVilka/8346728).
|
2019-05-01 00:49:23 +00:00
|
|
|
|
2019-05-06 23:17:08 +00:00
|
|
|
|
2020-12-13 15:20:36 +00:00
|
|
|
## Features
|
2020-12-13 15:13:26 +00:00
|
|
|
- Native iTerm and Kitty support
|
2019-05-06 23:17:08 +00:00
|
|
|
- Animated GIF support
|
|
|
|
- Accept media through stdin
|
|
|
|
- Custom dimensions
|
2020-03-11 14:07:45 +00:00
|
|
|
- Transparency
|
2022-05-01 07:22:11 +00:00
|
|
|
- Experimental Sixel support (behind the `sixel` feature flag)
|
2019-05-06 23:17:08 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
## Installation
|
2019-05-01 00:49:23 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
### From source (recommended)
|
2019-06-22 10:28:42 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
Installation from source requires a local [Rust environment](https://www.rust-lang.org/tools/install).
|
2019-05-01 00:49:23 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
git clone https://github.com/atanunq/viu.git
|
|
|
|
|
|
|
|
# Build & Install
|
|
|
|
cd viu/
|
|
|
|
cargo install --path .
|
|
|
|
|
|
|
|
# Use
|
2019-05-06 23:17:08 +00:00
|
|
|
viu img/giphy.gif
|
2019-05-01 00:49:23 +00:00
|
|
|
```
|
2019-05-05 00:39:17 +00:00
|
|
|
Or without cloning:
|
|
|
|
```bash
|
|
|
|
cargo install viu
|
|
|
|
```
|
2019-06-22 10:28:42 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
### Binary
|
2020-03-11 14:07:45 +00:00
|
|
|
A precompiled binary can be downloaded from the [release
|
|
|
|
page](https://www.github.com/atanunq/viu/releases/latest).
|
2020-12-13 15:45:35 +00:00
|
|
|
GPG fingerprint is B195BADA40BEF20E4907A5AC628280A0217A7B0F.
|
2019-05-02 20:52:39 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
### Packages
|
2019-05-03 05:13:30 +00:00
|
|
|
|
2021-09-16 06:43:47 +00:00
|
|
|
#### MacOS
|
|
|
|
Available in [`brew`](https://formulae.brew.sh/formula/viu).
|
|
|
|
```bash
|
|
|
|
brew install viu
|
|
|
|
```
|
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
#### Arch Linux
|
2023-11-21 12:56:59 +00:00
|
|
|
Available in [`extra/viu`](https://archlinux.org/packages/extra/x86_64/viu/).
|
2021-09-16 06:43:47 +00:00
|
|
|
```bash
|
|
|
|
pacman -S viu
|
|
|
|
```
|
2019-05-01 00:49:23 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
#### NetBSD
|
|
|
|
Available in [`graphics/viu`](http://cdn.netbsd.org/pub/pkgsrc/current/pkgsrc/graphics/viu/README.html).
|
|
|
|
|
|
|
|
## Usage
|
2020-12-13 15:20:36 +00:00
|
|
|
|
|
|
|
### Examples
|
2020-10-23 21:14:35 +00:00
|
|
|
On a [Kitty](https://github.com/kovidgoyal/kitty) terminal:
|
|
|
|
|
|
|
|
![Kitty](img/kittydemo.gif)
|
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
On a Mac with iTerm:
|
|
|
|
|
|
|
|
![iTerm](img/iterm.png)
|
|
|
|
|
2020-10-23 21:14:35 +00:00
|
|
|
|
|
|
|
Using half blocks (Kitty protocol and `tmux` do not get along):
|
|
|
|
|
2019-05-02 23:12:15 +00:00
|
|
|
![Demo](img/demo.gif)
|
|
|
|
|
2019-05-05 00:39:17 +00:00
|
|
|
|
|
|
|
![Demo](img/gifdemo.gif)
|
2019-05-06 23:17:08 +00:00
|
|
|
|
|
|
|
|
|
|
|
![Demo](img/curldemo.gif)
|
|
|
|
|
|
|
|
|
|
|
|
Ctrl-C was pressed to stop the GIFs.
|
2019-05-05 23:43:05 +00:00
|
|
|
|
2019-05-05 00:39:17 +00:00
|
|
|
|
2020-03-11 14:07:45 +00:00
|
|
|
When `viu` receives only one file and it is GIF, it will be displayed over and over until Ctrl-C is
|
2021-02-27 12:30:46 +00:00
|
|
|
pressed. However, when couple of files are up for display the GIF will be displayed only once.
|
2019-05-05 23:43:05 +00:00
|
|
|
|
2020-12-13 15:20:36 +00:00
|
|
|
### iTerm note
|
|
|
|
iTerm can handle GIFs by itself with better performance, but configuration through `--once`
|
|
|
|
and `--frame-rate` will have no effect there.
|
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
### Aspect Ratio
|
2020-03-11 14:07:45 +00:00
|
|
|
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.
|
2019-05-01 00:49:23 +00:00
|
|
|
|
2020-12-13 15:13:26 +00:00
|
|
|
### Command line options
|
2019-05-01 00:49:23 +00:00
|
|
|
```
|
2022-10-23 07:58:45 +00:00
|
|
|
View images right from the terminal.
|
|
|
|
|
2022-10-20 22:06:34 +00:00
|
|
|
Usage: viu [OPTIONS] [file]...
|
|
|
|
|
|
|
|
Arguments:
|
|
|
|
[file]... The images to be displayed. Set to - for standard input.
|
|
|
|
|
|
|
|
Options:
|
2022-10-23 07:58:45 +00:00
|
|
|
-w, --width <width>
|
|
|
|
Resize the image to a provided width
|
|
|
|
-h, --height <height>
|
|
|
|
Resize the image to a provided height
|
|
|
|
-x <x>
|
|
|
|
X offset [default: 0]
|
|
|
|
-y <y>
|
|
|
|
Y offset [default: 0]
|
|
|
|
-a, --absolute-offset
|
|
|
|
Make the x and y offset be relative to the top left terminal corner. If not set, they are relative to the cursor's position.
|
|
|
|
-r, --recursive
|
|
|
|
Recurse down directories if passed one
|
|
|
|
-b, --blocks
|
|
|
|
Force block output
|
|
|
|
-n, --name
|
|
|
|
Output the name of the file before displaying
|
|
|
|
-t, --transparent
|
|
|
|
Display transparent images with transparent background
|
|
|
|
-f, --frame-rate <frames-per-second>
|
|
|
|
Play the gif at a given frame rate
|
|
|
|
-1, --once
|
|
|
|
Loop only once through the gif
|
|
|
|
-s, --static
|
|
|
|
Show only the first frame of the gif
|
|
|
|
-H, --help
|
|
|
|
Print help information
|
|
|
|
-V, --version
|
|
|
|
Print version information
|
2019-05-01 00:49:23 +00:00
|
|
|
```
|