2022-06-14 13:00:53 +02:00
|
|
|
# ctpv
|
|
|
|
|
2023-03-20 20:00:17 +01:00
|
|
|
File previewer for a terminal
|
2022-06-14 13:00:53 +02:00
|
|
|
|
|
|
|
![showcase](doc/showcase.gif)
|
|
|
|
|
|
|
|
----
|
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
ctpv is a file previewer utility for a terminal.
|
2022-06-20 22:25:31 +02:00
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
It was made with integration into [lf file manager][lf] in mind,
|
|
|
|
but I believe that it can be easily integrated into other programs
|
|
|
|
as well.
|
2022-07-11 15:40:12 +02:00
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
It supports previews for source code, archives, PDF files, images,
|
|
|
|
videos, etc.
|
|
|
|
See [Previews](#previews) for more info.
|
|
|
|
|
|
|
|
Image previews are powered by one of these programs:
|
2022-06-20 22:25:31 +02:00
|
|
|
|
2023-03-20 20:00:17 +01:00
|
|
|
* [Überzug][ueberzug] (X11 only)
|
2023-03-26 00:06:18 +01:00
|
|
|
* [Chafa][chafa] (X11 and Wayland)
|
2023-03-20 20:00:17 +01:00
|
|
|
* [Kitty terminal][kitty]
|
2022-06-14 13:00:53 +02:00
|
|
|
|
2022-06-16 07:00:57 +02:00
|
|
|
ctpv is a remake of an awesome program named
|
2023-03-26 00:06:18 +01:00
|
|
|
[stpv](https://github.com/Naheel-Azawy/stpv).
|
|
|
|
stpv did everything I wanted, except it was a bit sluggish because
|
2022-06-14 13:00:53 +02:00
|
|
|
it was written in POSIX shell.
|
2023-03-26 00:06:18 +01:00
|
|
|
ctpv is written in C and is an attempt to make a faster version of
|
|
|
|
stpv with a few new features.
|
2022-06-21 17:09:07 +02:00
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
## Previews
|
2022-06-21 17:09:07 +02:00
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
Previewing each file type requires specific programs installed on
|
|
|
|
a system.
|
2022-06-19 17:21:52 +02:00
|
|
|
If a program is not found on the system, ctpv
|
|
|
|
will try to use another one.
|
|
|
|
Only one program is required for each file type.
|
|
|
|
For example, you only need either `elinks`, `lynx` or
|
|
|
|
`w3m` installed on your system to view HTML files.
|
2022-06-17 10:41:43 +02:00
|
|
|
|
2022-06-18 17:50:57 +02:00
|
|
|
<!-- This table is auto generated! -->
|
|
|
|
<!--TABLESTART-->
|
|
|
|
| File types | Programs |
|
2022-06-17 10:53:10 +02:00
|
|
|
| ---- | ---- |
|
2022-06-18 17:50:57 +02:00
|
|
|
| any | `exiftool` `cat` |
|
|
|
|
| archive | `atool` |
|
2022-11-27 02:54:38 +01:00
|
|
|
| audio | `ffmpegthumbnailer` `ffmpeg` |
|
2022-06-18 17:50:57 +02:00
|
|
|
| diff | `colordiff` `delta` `diff-so-fancy` |
|
|
|
|
| directory | `ls` |
|
2022-07-27 15:00:16 +02:00
|
|
|
| font | `fontimage` |
|
2022-07-13 11:59:22 +02:00
|
|
|
| gpg-encrypted | `gpg` |
|
2022-06-18 17:50:57 +02:00
|
|
|
| html | `elinks` `lynx` `w3m` |
|
2022-06-23 13:54:23 +02:00
|
|
|
| image | `ueberzug` `chafa` |
|
2022-06-18 17:50:57 +02:00
|
|
|
| json | `jq` |
|
2023-03-20 20:00:17 +01:00
|
|
|
| markdown | `glow` `mdcat` |
|
2022-07-31 14:16:08 +02:00
|
|
|
| office | `libreoffice` |
|
2022-06-18 17:50:57 +02:00
|
|
|
| pdf | `pdftoppm` |
|
2022-10-10 09:17:06 +02:00
|
|
|
| svg | `convert` |
|
2022-06-18 17:50:57 +02:00
|
|
|
| text | `bat` `cat` `highlight` `source-highlight` |
|
|
|
|
| torrent | `transmission-show` |
|
2022-10-10 09:17:06 +02:00
|
|
|
| video | `ffmpegthumbnailer` |
|
2022-06-18 17:50:57 +02:00
|
|
|
|
|
|
|
<!--TABLEEND-->
|
2022-06-17 10:41:43 +02:00
|
|
|
|
2022-06-14 13:00:53 +02:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
### Manual
|
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
If you are building from source, make sure to install these libraries!
|
|
|
|
Depending on your system, you probably will also need "devel" versions
|
|
|
|
of the same libraries.
|
|
|
|
|
|
|
|
* `libcrypto`
|
|
|
|
* `libmagic`
|
|
|
|
|
|
|
|
Install:
|
|
|
|
|
|
|
|
```console
|
2022-06-14 13:00:53 +02:00
|
|
|
git clone https://github.com/NikitaIvanovV/ctpv
|
|
|
|
cd ctpv
|
2023-04-01 02:29:49 +02:00
|
|
|
make
|
2023-03-26 00:06:18 +01:00
|
|
|
sudo make install
|
2022-06-14 13:00:53 +02:00
|
|
|
```
|
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
Uninstall:
|
|
|
|
|
|
|
|
```console
|
|
|
|
sudo make uninstall
|
|
|
|
```
|
2022-06-14 13:00:53 +02:00
|
|
|
|
2022-06-21 17:07:01 +02:00
|
|
|
### AUR
|
|
|
|
|
|
|
|
If you are an Arch Linux user, you can install
|
2022-09-10 16:30:16 +02:00
|
|
|
[`ctpv-git`](https://aur.archlinux.org/packages/ctpv-git)
|
|
|
|
AUR package.
|
2022-06-21 17:07:01 +02:00
|
|
|
|
2023-03-26 00:06:18 +01:00
|
|
|
```console
|
2022-06-21 17:07:01 +02:00
|
|
|
yay -S ctpv-git
|
|
|
|
```
|
|
|
|
|
2023-03-20 20:50:45 +01:00
|
|
|
### MacPorts
|
|
|
|
|
|
|
|
With MacPorts, you can install the
|
|
|
|
[`ctpv`](https://ports.macports.org/port/ctpv)
|
|
|
|
package.
|
|
|
|
|
|
|
|
```console
|
|
|
|
sudo port install ctpv
|
|
|
|
```
|
|
|
|
|
2023-08-12 00:57:19 +02:00
|
|
|
### Homebrew
|
|
|
|
|
|
|
|
With Homebrew, you can install the
|
|
|
|
[`ctpv`](https://formulae.brew.sh/formula/ctpv)
|
|
|
|
package.
|
|
|
|
|
|
|
|
```console
|
|
|
|
brew install ctpv
|
|
|
|
```
|
|
|
|
|
2023-05-31 10:57:43 +02:00
|
|
|
### Nix
|
|
|
|
|
|
|
|
#### Nix package
|
|
|
|
|
|
|
|
```console
|
|
|
|
nix-env -ivf cptv
|
|
|
|
nix profile install nixpkgs#cptv # with flakes enabled
|
|
|
|
```
|
|
|
|
|
|
|
|
#### NixOS and HomeManager
|
|
|
|
|
|
|
|
If you don't need to call it directly and
|
|
|
|
just want to use it through lf:
|
|
|
|
|
|
|
|
```nix
|
|
|
|
programs.lf = {
|
|
|
|
previewer = {
|
|
|
|
keybinding = "i";
|
|
|
|
source = "${pkgs.ctpv}/bin/ctpv";
|
|
|
|
};
|
|
|
|
extraConfig = ''
|
|
|
|
&${pkgs.ctpv}/bin/ctpv -s $id
|
|
|
|
cmd on-quit %${pkgs.ctpv}/bin/ctpv -e $id
|
|
|
|
set cleaner ${pkgs.ctpv}/bin/ctpvclear
|
|
|
|
'';
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-06-14 13:00:53 +02:00
|
|
|
## Integration
|
|
|
|
|
|
|
|
### lf file manager
|
|
|
|
|
|
|
|
Add these lines to your lf config
|
2022-07-14 11:45:45 +02:00
|
|
|
(usually located at `~/.config/lf/lfrc`).
|
|
|
|
|
2022-06-14 13:00:53 +02:00
|
|
|
```
|
|
|
|
set previewer ctpv
|
|
|
|
set cleaner ctpvclear
|
|
|
|
&ctpv -s $id
|
2022-08-02 00:04:51 +02:00
|
|
|
&ctpvquit $id
|
2022-06-14 13:00:53 +02:00
|
|
|
```
|
|
|
|
|
2023-03-20 20:00:17 +01:00
|
|
|
#### Wayland
|
|
|
|
|
|
|
|
If you use Wayland, follow these steps:
|
|
|
|
|
2023-03-26 00:41:45 +01:00
|
|
|
* Make sure you use one of the [terminals that support sixel][sixel]
|
2023-03-20 20:00:17 +01:00
|
|
|
* Install [this fork of lf][lf-sixel]
|
|
|
|
* Install [Chafa][chafa]
|
2023-03-26 00:06:18 +01:00
|
|
|
* Add `set chafasixel` to `~/.config/ctpv/config`
|
2023-03-20 20:00:17 +01:00
|
|
|
|
|
|
|
As of 2023-03-19, original lf does not support sixel protocol,
|
|
|
|
which is why you need use the fork.
|
|
|
|
|
2022-06-14 13:00:53 +02:00
|
|
|
## Documentation
|
|
|
|
|
2022-06-20 22:25:31 +02:00
|
|
|
Full documentation on command line options,
|
2022-09-10 16:30:16 +02:00
|
|
|
configuration and how to define custom previews can be found here:
|
2023-03-26 00:06:18 +01:00
|
|
|
<https://www.nikitaivanov.com/man1/ctpv>
|
2022-07-14 11:45:45 +02:00
|
|
|
|
2023-03-20 20:00:17 +01:00
|
|
|
[ueberzug]: https://github.com/seebye/ueberzug
|
|
|
|
[kitty]: https://github.com/kovidgoyal/kitty
|
|
|
|
[chafa]: https://github.com/hpjansson/chafa
|
2022-07-14 11:45:45 +02:00
|
|
|
[lf]: https://github.com/gokcehan/lf
|
2023-03-20 20:00:17 +01:00
|
|
|
[lf-sixel]: https://github.com/horriblename/lf
|
2023-03-26 00:41:45 +01:00
|
|
|
[sixel]: https://www.arewesixelyet.com
|