CTPV(1)

📦 version 1.1, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

Okay bestie, welcome to the ctpv(1) page from the User's Reference Manuals 💖. This one is literally the terminal previewer manual, and we're gonna make it make sense.

ctpv — terminal previewer. Periodt.

✨ SYNOPSIS ✨

ctpv file [w] [h] [x] [y] [id]

ctpv -h

ctpv -l

ctpv -m file ...

ctpv {-s|-c|-e} id

💖 DESCRIPTION 💖

So ctpv is a previewer utility made for integration into other programs like lf. Like, it's the bestie that gives your file manager cute little previews ✨.

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

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

Here's the whole vibe check for file types and their 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). It's giving setup era 💅.

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

🌈 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)). Very main character energy.

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 exits with 0 or any other status, both standard output and standard error are printed. Fr fr.

💅 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 #. Obsessed with the structure, honestly.

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. Cute, right? 💖

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

Manpages filenames may also end with other extensions: “.2”, “.3”, “.4” and so on. It's possible to make user-defined 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. No cap, protect your filenames.

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 🎀

okay so ctpv keeps exactly two little spots on your disk and you should lowkey know about both 💅

  • $XDG_CONFIG_HOME/ctpv/config — this is the configuration file, the one where all your vibes live. If $XDG_CONFIG_HOME isn't set, it just defaults to ~/.config. no cap, that's the whole rule 🫶
  • $XDG_CACHE_HOME/ctpv — the directory where cached image previews get stored. bestie, listen: generating an image preview for some file types (videos, PDF files, the heavy hitters 😭) genuinely takes some time, which is exactly why the generated images get stashed away in this directory — so they can be shown again if you preview the same file a second time. instant slay, no re-rendering ✨. If $XDG_CACHE_HOME isn't set, it defaults to ~/.cache.

🌈 SEE ALSO 🌈

  • lf(1) — the file manager this whole thing is besties with 💖

👑 AUTHOR 👑

Written by Nikita Ivanov. we stan a legend, periodt 🌸

and that's the whole page, bestie — you're officially fluent in ctpv(1). this cutie is from the Linux manual, dated 2022 — go forth and preview literally everything 💅✨🦋

📦 where this page comes from