CTPV(1)

NAME
ctpv - terminal previewer

SYNOPSIS
ctpv file [w] [h] [x] [y] [id]
ctpv -h
ctpv -l
ctpv -m file ...
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
audio | ffmpegthumbnailer ffmpeg
diff | colordiff delta diff-so-fancy
directory | ls
font | fontimage
gpg-encrypted | gpg
html | elinks lynx w3m
image | ueberzug chafa
json | jq
markdown | glow mdcat
office | libreoffice
pdf | pdftoppm
svg | convert
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
            &ctpvquit $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).

Überzug supports X11 only, so Wayland is not supported. To enable high-resolution image previews on Wayland, you need to follow these steps:

•   Make sure you use one of the terminals that support sixel (https://www.arewesixelyet.com)

•   Install lf-sixel (https://github.com/horriblename/lf).

•   Install Chafa

•   Add chafasixel configuration option (see Preview options)

The fork is required because, as of 2023-03-19, the original lf does not support sixel protocol.

  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

-h  Print help message.

-l  List all previews.

-m  file ... Print extension and MIME type of file.

-s  id Start server with ID id.

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

-e  id 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 some options
        set forcekitty
        set shell "/usr/bin/bash"

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

shell
    "path" Use path as a path to a shell to run previews with. Use it if you have a non-POSIX compliant shell installed as a default shell. The setting defaults to /bin/sh.

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.

chafasixel
    Set output format of Chafa to “sixels” instead of “symbols”. Use it if your file manager and terminal are capable of properly displaying sixel data.

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

ENVIRONMENT

id  id of a server to connect to (see -s option).

FILES

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

$XDG_CACHE_HOME/ctpv
    Directory to store cached image previews. It takes some time to generate an image preview for some file types, such as videos or PDF files, this is why the generated images are stored in the directory to be shown if the same file is previewed again. If $XDG_CACHE_HOME is not set, defaults to ~/.cache.

SEE ALSO
lf(1)

AUTHOR
Written by Nikita Ivanov.