CTPV(1)

NAME
ctpv - terminal previewer

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

DESCRIPTION
ctpv is a previewer utility made for integration into other programs like lf.

When ctpv is given a file, it determines an appropriate preview for it and runs it. Depending on the preview and installed programs, it can print some text to standard output or display an image. Symbolic links are dereferenced.

  Built-in previews and 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
gpg-encrypted | gpg
html | elinks lynx w3m
image | ueberzug chafa
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 or Chafa (as seen in Built-in previews and dependencies) or using built-in image preview functionality of Kitty terminal.

When possible, ctpv will prefer Überzug over others image preview methods. You can override this behavior by using forcekitty or forcechafa options (see Preview options).

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

Then it creates a list of all previews respecting user configuration 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 program that is necessary for generating a preview content is not installed on the system), ctpv attempts to run another appropriate preview and so on. If the script exists with 0 or a any other status, both standard output and standard error are printed.

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 add previews or set different settings. Commands are separated by newlines. Comments start with number sign “#”.

Example:

    # Set an option
    set forcekitty

    # Add a new preview
    preview cow .moo {{
        cowsay < "$f"
    }}

    # Remove some previews
    remove w3m
    remove lynx
    remove elinks

  Preview options
An option can be set using set command.

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

forcekittyanim
    Always use Kitty terminal's built-in method of previewing images for animated images.

forcechafa
    Always use Chafa for image previews.

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

nosymlinkinfo
    Do not print resolved path of symbolic links.

showgpg
    Preview gpg(1) encrypted files. Filename must have “.gpg” extension.

  Defining custom previews
User-defined previews are added with preview command.

An example below defines a new preview with name “manpage” that applies to files with extension “.1”. A preview itself is a shell script enclosed within double curly braces.

        preview manpage .1 {{
            groff -man -tep -Tutf8 -rLL="${w}n" "${f}" | col -x
        }}

Running ctpv file.1 where file.1 is a source code for a manpage will run groff(1) to produce a formatted manpage like the one you are reading.

Manpages filenames may also end with other extensions: “.2”,“.3”,“.4” and so on. It's possible to make user-defines previews apply to several file types at once:

        preview manpage .1 .2 .3 .4 .5 .6 .7 .8 {{
            # groff command
        }}

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). There are also $m and $e which store MIME type and extension of file.

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

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

You 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 apply to 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 a built-in 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

It's useful if you have a program installed on your system but you don't want ctpv to use it for generating previews.

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.