CTPV(1)

NAME
ctpv — terminal previewer

SYNOPSIS
file -l -m {-s|-c|-e} id

DESCRIPTION
ctpv is a previewer utility made for integration into other programs. It supports a variety of “previews” out of the box, as well as an option to define custom ones.

When ctpv is given a file, it determines an appropriate preview for it and runs its script. The script produces preview content and prints it to standard output. Symbolic links are dereferenced.

  Dependencies
Previewing each file type requires specific programs. 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.
File type | Programs
any | exiftool cat
archive | atool
diff | colordiff delta diff-so-fancy
directory | ls
html | elinks lynx w3m
image | ueberzug
json | jq
markdown | mdcat
odt | libreoffice
pdf | pdftoppm
text | bat cat highlight source-highlight
torrent | transmission-show
video | ffmpegthumbnailer

  Integration

lf file manager
    Add this snippet to lf configuration file (usually located at ~/.config/lf/lfrc).

set previewer ctpv set cleaner ctpvclear &ctpv -s $id cmd on-quit $ctpv -e $id

  Image previews
Image previews are enabled by either installing Überzug (as seen in Dependencies) or using built-in image preview functionality of Kitty terminal.

Note: if you use Kitty but Überzug is installed on the system, the latter will be the preferred method for previewing images. It can be changed using forcekitty option (see Preview options).

  How previews are selected
Initially, ctpv retrieves MIME type and extension from file passed in the first argument (MIME type is extracted using libmagic(3)).

Then it creates a list of all previews in a special order, where previews that are more specific appear at the top and more generic ones at the bottom. The list can be viewed by using -l option. The order can be changed, see Setting priority.

Finally, ctpv goes through the list starting with the first element and checks if a preview matches file's extension and MIME type. If it does, it runs a preview script. If the script exits with status 127 (which usually means that a command was not found), the next appropriate preview is selected, and so on.

OPTIONS

-l  List all previews.

Print extension and MIME type of specified files.

Start server with ID
    id.

Send
    clear command to server with ID id (usually, it removes image from terminal).

Kill server with ID
    id.

CONFIGURATION
ctpv uses a configuration file usually located at ~/.config/ctpv/config (see FILES). Its format somewhat resembles one used by lf. There are several “commands” that can be used to change previews or set different settings. Commands are separated by newlines. Comments start with number sign (#) like in many other formats.

  Preview options
An option can be set using set command.

forcekitty
    Always use Kitty terminal's built-in method of previewing images.

noimages
    Print only text and do not use any image previewing method.

  Defining custom previews
A snippet below defines a new preview with name cow that applies to files with extension .moo. A preview itself is a shell script enclosed within double curly braces (this particular one utilizes the famous cowsay program):

preview cow .moo {{ cowsay < "$f" }}

Running ctpv file.moo where file.moo contains “some text” will produce the following output:

___________ < some text > ----------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || ||

Variable $f stores file that was passed as a first argument to ctpv. It's strongly suggested to enclose $f with double quotes ("$f") because otherwise the script will not work as expected if $f stores a filename with whitespace.

There are other variables that are exported into preview script environment: $w, $h, $x, $y and $id. However, they are rarely used even by built-in previews and are only set if corresponding arguments were passed to ctpv command (see SYNOPSIS).

You can specify MIME type instead of filename extension in preview definition:

preview json_example application/json {{ # preview json files }}

And you also can omit subtype part of the MIME type by replacing it with *.

preview any_text_example text/* {{ # this one applies to all text files }}

Setting subtype to * will make the preview above work for any file which MIME type starts with text/.

  Setting priority
If there are several previews that apply to the same file type, only the top one in the list is chosen (see How previews are selected). To alter this behavior, you can use priority command to change preview priority:

priority cat

The snippet above sets priority of preview named “cat” to 1, thus now it's used for all text files. It's possible to specify an integer as the second argument to set priority other than 1 (may also be negative).

  Removing previews
remove command simply removes a preview (also works for built-in ones):

remove cat

FILES

$XDG_CONFIG_HOME/ctpv/config
    Configuration file. If $XDG_CONFIG_HOME is not set, defaults to ~/.config.

SEE ALSO
lf(1)

AUTHOR
Written by Nikita Ivanov.