Simple Terminal PreViewer (STPV)

Preview as many possible kinds of files.

Dependencies

One of the following is needed for image previews

ueberzug	Used for image previews in X11
kitty	Kitty’s icat is used if available
jp2a	ASCII-art previews in the terminal
chafa	ANSI-art previews in the terminal
chafa	Also used for sixel *

• Note that sixel doesn’t work well under tmux, lf, fzf, and many others. Forks exist like lf-sixel, sixel-tmux.

The following programs. Note that the names are the command names and not the package names

type	cli program	image program
directory	ls	-
archive	xzcat,zcat,atool,bsdtar	-
rar	unrar	-
7z+iso	7z	-
html	w3m,lynx,elinks,pandoc	-
json	jq,=text-source	-
markdown	pandoc,=text-source	-
csv	pandoc,cat	-
diff	delta,diff-so-fancy,=text-source	-
pdf	pdftotext,mutool,exiftool	pdftoppm
epub	epub2txt	-
text-source	mdcat,bat,highlight,source-highlight,cat	-
image	exiftool	convert,identify
video	exiftool	ffmpegthumbnailer
audio	exiftool	-
office	pandoc,libreoffice	libreoffice
xounralpp	-	xournalpp
torrent	transmission-show	-
stl	-	openscad+convert

Overall, it should work fine without most dependencies, it will fallback to simpler previews.

Usage

stpv

Note: stpvimg should be run first as mentioned below for image previews to work

stpv $FILE $H $W $X $Y $ID # all arguments except FILE are optional
stpv --clear $ID # only if stpvimg is running

stpvimg

ID=$$
stpvimg --listen $ID &
stpvimg --add $ID 1.png
stpvimg --add $ID 2.png $X $Y $W $H
stpvimg --clear $ID
stpvimg --end $ID

Integration with fmz

stpv is already integrated with fmz. Just install stpv and fmz will use it.

Integration with lf

lf now support image previews. All what is needed is to add the following to lfrc:

set previewer stpv
set cleaner stpvimgclr
&stpvimg --listen $id
cmd on-quit $stpvimg --end $id

Integration with fzf

fzfp

Installation

sudo make install

Configuration

The configuration file is typically located in ~/.config/stpv/config.sh. It is a simple shell script that gets sourced in stpv.

Options are listed below. Use any string for true, leave empty for false.

PV_IMAGE_ENABLED=1        # show image previews when possible
PV_TYPE=img               # (ueberzug|kitty|sixel|ansi|ascii|img|text)
PREFER_TEXT=              # prefer text over images when displaying documents
DARK_DOCS=                # invert documents preview color in image previews
SAFE=1                    # kill itself if needed (check main for details)
AUTO_ORIENT=1             # auto orient images
MAX_IMG_CACHE_SIZE=300kb  # max image cache size
MAX_IMG_CACHE_W=1920      # max image cached image width
MAX_IMG_CACHE_H=1080      # max image cached image height
TIMEOUT=5                 # maximum time in seconds stpv should take, approximately

The last 3 options control how images are cached. Setting them to empty values will improve performance but at the same time might increase cache size.

Custom previews can be added to your config.sh file as well. Below is an example that shows any file ending with a .moo in cowsay.

#       function    type dep    dep-image
add_top handle_cows cows cowsay -
handle_cows() {
    [ "$file_extension_lower" = moo ] ||
        return "$RET_NO_MATCH"

    cowsay < "$file_path"
}

However, if you think you wrote a nice previewer, pull requests are more than welcomed. Check the main stpv file for more examples.

Related work

ctpv is a remake of stpv in C. It’s faster compared to stpv and has some great potential.

Video

https://youtu.be/MXkjcgzILIc

License

GPL3