ctpv/README.md

188 lines
3.9 KiB
Markdown
Raw Normal View History

2022-06-14 13:00:53 +02:00
# ctpv
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
* [Überzug][ueberzug] (X11 only)
2023-03-26 00:06:18 +01:00
* [Chafa][chafa] (X11 and Wayland)
* [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` |
| 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
```
### 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
(usually located at `~/.config/lf/lfrc`).
2022-06-14 13:00:53 +02:00
```
set previewer ctpv
set cleaner ctpvclear
&ctpv -s $id
&ctpvquit $id
2022-06-14 13:00:53 +02:00
```
#### Wayland
If you use Wayland, follow these steps:
* Make sure you use one of the [terminals that support sixel][sixel]
* 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`
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>
[ueberzug]: https://github.com/seebye/ueberzug
[kitty]: https://github.com/kovidgoyal/kitty
[chafa]: https://github.com/hpjansson/chafa
[lf]: https://github.com/gokcehan/lf
[lf-sixel]: https://github.com/horriblename/lf
[sixel]: https://www.arewesixelyet.com