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.

Integration

lf file manager

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

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
• Install lf-sixel.
• 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.

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.