stpv

stpv copied to clipboard

• Simple Terminal PreViewer (STPV) Preview as many possible kinds of files.

  [[./screenshot.gif]]

** Dependencies One of the following is needed for image previews | [[https://github.com/seebye/ueberzug][ueberzug]] | Used for image previews in X11 | | [[https://sw.kovidgoyal.net/kitty/][kitty]] | Kitty's [[https://sw.kovidgoyal.net/kitty/kittens/icat/][icat]] is used if available | | jp2a | ASCII-art previews in the terminal | | [[https://github.com/hpjansson/chafa/][chafa]] | ANSI-art previews in the terminal | | [[https://github.com/hpjansson/chafa/][chafa]] | Also used for [[https://www.arewesixelyet.com/][sixel]] * |

• Note that sixel doesn't work well under tmux, lf, fzf, and many others. Forks exist like [[https://github.com/horriblename/lf][lf-sixel]], [[https://github.com/csdvrx/sixel-tmux][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 #+begin_src shell stpv $FILE $H $W $X $Y $ID # all arguments except FILE are optional stpv --clear $ID # only if stpvimg is running #+end_src

*** stpvimg #+begin_src shell ID=$$ stpvimg --listen $ID & stpvimg --add $ID 1.png stpvimg --add $ID 2.png $X $Y $W $H stpvimg --clear $ID stpvimg --end $ID #+end_src

*** Integration with [[https://github.com/Naheel-Azawy/fmz][fmz]] ~stpv~ is already integrated with ~fmz~. Just install ~stpv~ and ~fmz~ will use it.

*** Integration with [[https://github.com/gokcehan/lf][lf]] lf now support image previews. All what is needed is to add the following to lfrc: #+begin_src shell set previewer stpv set cleaner stpvimgclr &stpvimg --listen $id cmd on-quit $stpvimg --end $id #+end_src

*** Integration with [[https://github.com/junegunn/fzf][fzf]] #+begin_src shell fzfp #+end_src

** Installation #+begin_src shell sudo make install #+end_src

** 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. #+BEGIN_SRC shell 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 #+END_SRC

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

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

     cowsay < "$file_path"
 }

#+end_src

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 [[https://github.com/NikitaIvanovV/ctpv][ctpv]] is a remake of stpv in C. It's faster compared to stpv and has some great potential.

** Video [[https://youtu.be/MXkjcgzILIc][https://youtu.be/MXkjcgzILIc]]

** License GPL3