Welcome to TermVisage’s documentation!#

Attention

🚧 Under Construction - There might be incompatible changes between minor versions of version zero!

Installation#

Requirements#

Steps#

The latest version can be installed from PyPI using pipx with:

pipx install termvisage

and upgraded with:

pipx upgrade termvisage

Note

pip can also be used but pipx is recommended.

Supported Terminal Emulators#

Some terminals emulators that have been tested to meet the requirements for at least one render style include:

  • libvte-based terminal emulators such as:

    • Gnome Terminal

    • Terminator

    • Tilix

  • Kitty

  • Konsole

  • iTerm2

  • WezTerm

  • Alacritty

  • Windows Terminal

  • MinTTY (on Windows)

  • Termux (on Android)

For render style-specific support, see Render Styles.

Note

Some terminal emulators support truecolor escape sequences but have a 256-color palette. This will limit color reproduction.

General Concepts#

The image viewer is started from the command line using the termvisage command.

Image Sources#

The viewer accepts the following kinds of sources:

  • A path to an image file on a local filesystem.

  • A path to a directory on a local filesystem.

  • An Image URL.

Any thing else given as a source is reported as invalid. If no valid source is given, the process exits with code NO_VALID_SOURCE (see Exit Codes).

Modes#

The viewer can be used in two modes:

  1. CLI mode

    In this mode, images are directly printed to standard output. It is used when

    • output is not a terminal (even if --tui is specified)

    • there is only a single image source

    • --cli is specified

    If there are multiple image sources, animations are skipped (except when --itn is used with the iterm2 render style)

  2. TUI mode

    In this mode, a Terminal/Text-based User Interface is launched, within which images and directories can be browsed and viewed in different ways. It is used when

    • there is at least one non-empty directory source

    • there are multiple image sources

    • --tui is specified

Render Styles#

See render style.

By default, the best style supported by the active terminal is automatically detected. A particular render style can be specified using style or -S.

If the specified render style is:

  • graphics-based and not supported, an error notification is emitted and the process exits with code FAILURE (see Exit Codes).

  • text-based and not [fully] supported, a warning notification is emitted but execution still proceeds with the style.

The available render styles are:

auto

Selects the best style is based on the detected terminal support.

kitty

Uses the kitty graphics protocol. Currently supported terminal emulators include (but might not be limited to):

  • Kitty >= 0.20.0

  • Konsole >= 22.04.0

iterm2

Uses the iTerm2 inline image protocol. Currently supported terminal emulators include (but might not be limited to):

  • iTerm2

  • Konsole >= 22.04.0

  • WezTerm

block

Uses unicode half blocks with truecolor color escape codes to represent images with a density of two pixels per character cell.

Using a render style not supported by the active terminal is not allowed by default. To force the use of such a render style, add --force-style.

Cell Ratio#

The cell ratio is taken into consideration when setting image sizes for text-based render styles, in order to preserve the aspect ratio of images drawn to the terminal.

This value is determined by cell ratio OR either of -C or --auto-cell-ratio. The command-line options are mutually exclusive and override the config option.

By default (i.e without changing the config option value or specifying either command-line option), termvisage tries to determine the value from the active terminal which works on most modern terminal emulators (currently supported on UNIX-like platforms only). This is probably the best choice, except the terminal emulator or platform doesn’t support this feature.

If termvisage is unable to determine this value automatically, it falls back to 0.5, which is a reasonable value in most cases.

In case auto cell ratio is not supported and the fallback value does not give expected results, a different value can be specified using the config or command-line option.

Attention

If using auto cell ratio and the active terminal is not the controlling terminal of the termvisage process (e.g output is redirected to another terminal), ensure no process that might read input (e.g a shell) is currently running in the active terminal, as such a process might interfere with determining the cell ratio on some terminal emulators (e.g VTE-based ones).

For instance, the sleep command can be executed if a shell is currently running in the active terminal.

Notifications#

Notifications are event reports meant to be brought to the immediate knowledge of the user.

Notifications have two possible destinations:

  • Standard output/error stream: This is used while the TUI is not launched.

  • TUI notification bar: This is used while the TUI is launched.

    • Notifications sent here automatically disappear after 5 seconds.

Logging#

Logs are more detailed event reports meant for troubleshooting and debugging purporses.

Logs are written to a file on a local filesystem.

  • for all sessions, using log file

  • per session, using -l

A log record has the following format (< and > mark placeholders, they’re not part of the record itself):

(<pid>) (<date> <time>) [<level>] <process>: <thread>: <module>: <function>: <message>

  • pid: The process ID of the session.

  • date and time: System date and time at which the record was created, in the format %Y-%m-%d %H:%M:%S,<ms>, where <ms> is in milliseconds.

  • level: The level of the record, this indicates it’s importance.

  • process and thread: The names of the python process and thread that produced the record.

  • module: The package submodule from which it originated, or “termvisage” for session-level logs.

  • function: The function from which it originated.

  • message: The actual report describing the event that occurred.

Note

  • Certain logs and some extra info are only provided when logging level is set to DEBUG.

  • Log files are appended to, so it’s safe use the same file for multiple sessions.

  • Log files are rotated upon reaching a size of 1MiB.

    • Only the current and immediate previous log file are kept.

  • The Process ID of the each session precedes its log entries, so this can be used to distinguish between logs from different sessions running simultaneously while using the same log file.

Exit Codes#

termvisage returns the following exit codes with the specified meanings:

  • 0 (SUCCESS): Exited normally and successfully.

  • 1 (FAILURE): Exited due to an unhandled exception or a non-specific error.

  • 2 (INVALID_ARG): Exited due to an invalid command-line argument value or option combination.

  • 3 (INTERRUPTED): The program received an interrupt signal i.e SIGINT.

  • 4 (NO_VALID_SOURCE): Exited due to lack of any valid source.

Command-Line Interface#

Run termvisage --help to see the basic help message or termvisage --long-help for the full help message.

Note

Some options are only applicable in a specific mode. If used with the other mode, they’re simply ignored.

Shell Completion#

Run termvisage --completions for instructions on enabling tab completion for options and arguments of termvisage in your preferred shell.

Options and Arguments#

usage: termvisage [--help | --long-help] [--version] [--completions]
                  [--query-timeout N] [-S {auto,block,iterm2,kitty}]
                  [--force-style] [-C N | --auto-cell-ratio]
                  [--swap-win-size | --no-swap-win-size] [--cli | --tui]
                  [-f N] [-R N]
                  [--anim-cache N | --cache-all-anim | --cache-no-anim]
                  [--no-anim] [--no-alpha | -A N | -b [COLOR]] [--h-allow N]
                  [--v-allow N] [--scroll] [-O]
                  [-w N | -h N | --fit | --fit-to-width | --original-size | -s N | -x N | -y N]
                  [--no-align] [-H {left,center,right}] [--pad-width N]
                  [-V {top,middle,bottom}] [--pad-height N] [-a] [-r] [-d N]
                  [--thumbnail | --no-thumbnail] [--max-pixels N]
                  [--multi | --no-multi] [--config FILE | --no-config]
                  [-l FILE]
                  [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} | -q | -v | --verbose-log | --debug]
                  [--kz N] [--kc N] [--itn] [--itnmb N] [--itc N] [--itjq N]
                  [--itnrff]
                  [source ...]

-- should be used to separate positional arguments that begin with an - from options/flags, to avoid ambiguity. For example, $ termvisage [options] -- -image.jpg --image.png.

See https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html for supported image formats.

See https://termvisage.readthedocs.io/en/stable/cli.html for the complete CLI description.

Positional Arguments#

source#

Image file path(s), directory path(s) and/or image URL(s). If no source is provided, the current working directory is used.

General Options#

--help#

Show the basic help message and exit

--long-help#

Show this help message and exit

--version#

Show the program version and exit

--completions#

Show instructions to enable shell completions and exit

--query-timeout <n>#

Timeout (in seconds) for all terminal queries (default: query timeout config)

-S {auto,block,iterm2,kitty}, --style {auto,block,iterm2,kitty}#

Image render style (default: style config) [1]

--force-style#

Use the specified render style even if it’s reported as unsupported by the active terminal

-C <n>, --cell-ratio <n>#

The cell ratio (width-to-height ratio of a character cell) in the terminal; to preserve image aspect ratio (default: cell ratio config)

--auto-cell-ratio#

Determine the cell ratio from the terminal emulator, if possible (default: cell ratio config)

--swap-win-size, --no-swap-win-size#

Enable/Disable a workaround for auto cell ratio on some terminal emulators (e.g older VTE-based ones) that wrongly report window dimensions swapped (default: swap win size config)

--cli#

Do not launch the TUI. Instead, draw all image sources to the terminal directly [2]

--tui#

Launch the TUI, even for a single image

Animation Options (General)#

-f <n>, --frame-duration <n>#

The time (in seconds) between frames for all animated images (default: determined per image from the metadata OR 0.1)

-R <n>, --repeat <n>#

Number of times to repeat all frames of an animated image; A negative count implies an infinite loop (default: -1)

--anim-cache <n>#

Maximum frame count for animation frames to be cached (Better performance at the cost of memory) (default: anim cache config) [3]

--cache-all-anim#

Cache frames for all animations (beware, the higher the frame count per image, the higher the memory usage)

--cache-no-anim#

Disable frame caching (Less memory usage but reduces performance)

--no-anim#

Disable image animation. Animated images are displayed as just their first frame.

Transparency Options (General)#

NOTE: These are mutually exclusive

--no-alpha#

Disable image transparency (alpha channel is removed)

-A <n>, --alpha <n>#

Alpha ratio above which pixels are taken as opaque (0 <= x < 1), for text-based render styles (default: 0.156863)

-b <color>, --alpha-bg <color>#

Hex color (without #) to replace transparent backgrounds with (omit COLOR to use the active terminal's default BG color)

CLI-only Options#

These options apply only when there is only one valid image source or --cli is specified

--h-allow <n>#

Horizontal allowance i.e minimum number of columns to leave unused (default: 0)

--v-allow <n>#

Vertical allowance i.e minimum number of lines to leave unused (default: 2)

--scroll#

Allow an image’s height to be greater than the terminal height. Not needed when --fit-to-width is specified.

-O, --oversize#

Allow an image’s size to be greater than the terminal size (To be used with -w or --original-size)

Sizing Options (CLI-only)#

These apply to all images and are mutually exclusive [4]

-w <n>, --width <n>#

Image width

-h <n>, --height <n>#

Image height

--fit#

Fit each image optimally within the available terminal size

--fit-to-width#

Fit each image to the available terminal width, --v-allow has no effect i.e vertical allowance is ignored

--original-size#

Render each image using its original size (See -O, USE WITH CAUTION!)

-s <n>, --scale <n>#

Image scale (overrides -x and -y) [5]

-x <n>, --scale-x <n>#

Image horizontal scale (overridden by -s) (default: 1.0)

-y <n>, --scale-y <n>#

Image vertical scale (overridden by -s) (default: 1.0)

Alignment Options (CLI-only)#

These apply to all images

--no-align#

Output image without alignment or padding. Overrides all other alignment options.

-H {left,center,right}, --h-align {left,center,right}#

Horizontal alignment (default: center)

--pad-width <n>#

Number of columns within which to align each image (default: terminal width, minus horizontal allowance)

-V {top,middle,bottom}, --v-align {top,middle,bottom}#

Vertical alignment (default: middle)

--pad-height <n>#

Number of lines within which to align each image (default: none)

TUI-only Options#

These options apply only when there is at least one valid directory source, multiple valid sources or --tui is specified

-a, --all#

Include hidden file and directories

-r, --recursive#

Scan for local images recursively

-d <n>, --max-depth <n>#

Maximum recursion depth (default: 950)

--thumbnail, --no-thumbnail#

Enable or disable thumbnail generation for the image grid; if enabled, thumbnails are cached on disk and cleaned up upon exit (default: thumbnail config)

Performance Options#

--max-pixels <n>#

The maximum pixel-count for images that should be rendered (default: max pixels config)

--multi, --no-multi#

Enable (if supported) or disable multiprocessing (default: multi config)

Config Options#

NOTE: These are mutually exclusive

--config <file>#

The config file to use for this session (default: Searches XDG Base Dirs)

--no-config#

Use the default configuration

Logging Options#

NOTE: All these, except -l, are mutually exclusive

-l <file>, --log-file <file>#

The file to write logs to (default: log file config)

--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}#

Logging level for the session (default: WARNING) [6]

-q, --quiet#

No notifications, except fatal errors

-v, --verbose#

More detailed event reporting. Also sets logging level to INFO

--verbose-log#

Like -v but only applies to the log file

--debug#

Implies --log-level=DEBUG with verbosity

Kitty Style Options#

These options apply only when the kitty render style is used

--kz <n>, --kitty-z-index <n>#

Image stacking order [CLI-only]; >= 0 -> above text, < 0 -> below text, < -(2**31)/2 -> below cells with non-default background (default: 0)

--kc <n>, --kitty-compress <n>#

ZLIB compression level; 0 -> no compression, 1 -> best speed, 9 -> best compression (default: 4)

iTerm2 Style Options#

These options apply only when the iterm2 render style is used

--itn, --iterm2-native#

Use the protocol’s animation support; animations will not be skipped [CLI-only]

--itnmb <n>, --iterm2-native-max-bytes <n>#

Maximum size (in bytes) of image data for native animation [CLI-only] (default: 2097152)

--itc <n>, --iterm2-compress <n>#

ZLIB compression level, for images re-encoded in PNG format 0 -> no compression, 1 -> best speed, 9 -> best compression (default: 4)

--itjq <n>, --iterm2-jpeg-quality <n>#

JPEG compression status and quality; < 0 -> disabled, 0 <= x <= 95 -> quality (default: -1) [7]

--itnrff, --iterm2-no-read-from-file#

Never use image data directly from file; always re-encode images [8]


Footnotes

Terminal User Interface#

The TUI is developed using urwid.

UI Components#

The UI consists of various areas which are each composed using one or more widgets.
The components of the UI might change depending on the current context and some actions.

The following are the key components that make up the UI.

  • Banner:

    • At the top of the UI.

    • Fixed height of 4 lines.

    • Contains the project title with a surrounding color fill and a line-box decoration.

    • Hidden in full image views.

  • Viewer:

    • Immediately below the title banner.

    • Consists of two sub-components (described below) arranged horizontally:

      • Menu

      • View

  • Menu:

    • Sub-component of the viewer to the left.

    • Fixed width of 20 columns.

    • Contains a list of image and directory entries which can be scrolled through.

    • Used to scroll through images in a directory and navigate back and forth through directories, among other actions.

  • View:

    • Sub-component of the viewer to the right.

    • Images are displayed in here.

    • The content can be one of these two, depending on the type of item currently selected in the menu:

      • An image: When the item selected in the menu is an image.

      • An image grid: When the item selected in the menu is a directory.

    • The view component can also be used to scroll through images.

  • Notification Bar:

    • Immediately above the Action/Key Bar.

    • Notifications about various events are displayed here.

    • Hidden in full image views.

    • Hidden in all views, in QUIET mode (-q).

  • Action/Key Bar:

    • Contains a list of actions in the current context.

    • Each action has the symbol of the assigned key beside its name.

    • If the actions are too much to be listed on one line, the bar can be expanded/collapsed using the key indicated at the far right.

  • Overlays:

    • These are used for various purposes such as help menu, confirmations, etc.

    • They are shown only when certain actions are triggered.

  • Info Bar:

    • Used for debugging.

    • This is a 1-line bar immediately above the action/key bar.

    • Only shows (in all views) when --debug is specified.

Full/Maximized image views consist of only the view and action/key bar components.

Contexts#

A context is simply a set of actions.

The active context might change due to one of these:

  • Triggering certain actions.

  • Change of viewer sub-component (i.e menu or view) in focus.

  • Type of menu entry selected.

  • An overlay is shown.

The active context determines which actions are available and displayed in the action/key bar at the bottom of the UI.

The following are the contexts available:

  • global: The actions in this context are available when any other context is active, with a few exceptions.

  • menu: This context is active when the menu UI component is in focus and non-empty.

  • image: This context is active if the view UI component is in focus and was switched to (from the menu) while an image entry was selected.

  • image-grid: This context is active if the view UI component is in focus and was switched to (from the menu) while a directory entry was selected.

  • full-image: This context is active when an image entry is maximized from the image context (using the Maximize action) or from the menu context using the Open action.

  • full-grid-image: This context is active when an image grid cell is maximized from the image-grid context (using the Open action).

  • confirmation: This context is active only when specific actions that require confirmation are triggered e.g the Delete action in some contexts.

  • overlay: This context is active only when an overlay UI component (e.g the help menu) is shown.

Actions#

An action is a single entry in a context, it represents a functionality available in that context.

An action has the following defining properties:

  • name: The name of the action.

  • key: The key/combination used to trigger the action.

  • symbol: A string used to represent the key.

  • description: A brief description of what the action does.

  • visibility: Determines if the action is displayed in the action/key bar or not.

  • state: Determines if the action is enabled or not.

    • If an action is disabled, pressing its key will trigger the terminal bell.

Tip

All contexts and their actions (excluding navigation actions) with default properties can be found here.

Configuration#

The configuration is divided into the following categories:

  • Options (applies to both the CLI and the TUI Modes)

  • Keybindings (applies to only the TUI mode)

The configuration file is written in JSON format, using a partial config style i.e only the fields to be modified need to be present in the config file.

By default, termvisage searches the following locations, in the specified order, for $DIR/termvisage/termvisage.json (a file named termvisage.json within a directory named termvisage):

  • All valid directories specified in the XDG_CONFIG_DIRS environment variable, in reverse order or /etc/xdg if not set.

  • The directory specified by the XDG_CONFIG_HOME environment variable or ~/.config if not set (where ~ is the current user’s home directory).

If multiple config files are found (i.e in different locations), they’re applied on top of one another in the order in which they were found. Hence, a field present in the latter, if valid, will override the same field also present in the former.

An alternative config file can be specified per-session using --config.

To use the default configuration and not load any config file, use --no-config.

Tip

termvisage performs [quite] thorough validation on the values specified in a config file and reports any errors. To see information about how the errors are resolved (if resolvable), use -v.

This is a sample config file with all options and keybindings at their defaults. Note that this is only for reference, using any field within it as-is has no effect.

Options#

These are top-level fields whose values control various settings of the viewer.

anim cache#

anim cache#

The maximum frame count of an image for which frames will be cached during animation.

Type: integer
Valid values: x > 0
Default: 100

Note

Overridden by --anim-cache, --cache-all-anim and --cache-no-anim.

cell ratio#

cell ratio#

The cell ratio.

Type: null or float
Valid values: null or x > 0.0
Default: null

If null, the ratio is determined from the active terminal such that the aspect ratio of any image is always preserved. If this is not supported in the active terminal or on the platform, 0.5 is used instead.

Note

Overridden by -C and --auto-cell-ratio.

cell width#

cell width#

The initial width of (no of columns for) grid cells, in the TUI.

Type: integer
Valid values: 10 <= x <= 50 and x is even
Default: 30

checkers#

checkers#

Maximum number of subprocesses for checking directory sources.

Type: null or integer
Valid values: null or x >= 0
Default: null

If null, the number of subprocesses is automatically determined based on the amount of logical processors available. CPU affinity is also taken into account on supported platforms.

If less than 2, directory sources are checked within the main process.

getters#

getters#

Number of threads for downloading images from URL sources.

Type: integer
Valid values: x > 0
Default: 4

grid renderers#

grid renderers#

Number of subprocesses for rendering grid cells.

Type: integer
Valid values: x >= 0
Default: 1

If 0 (zero), grid cells are rendered by a thread of the main process.

log file#

log file#

The file to which logs are written.

Type: string
Valid values: A writable/creatable file path
Default: "{$XDG_STATE_HOME}/termvisage/termvisage.log"

If the file:

  • doesn’t exist, at least one of the parents must be a directory and be writable, so the file can be created.

  • exists, it is appended to, not overwritten.

Supports tilde expansion i.e a leading ~ (tilde) character is expanded to the current user’s home directory.

The environment variable $XDG_STATE_HOME defaults to ~/.local/state if undefined.

Warning

Relative paths are allowed but this will cause the log file to be written (or created) relative to the current working directory every time a session is started.

Note

Overridden by -l.

See also

Logging

max notifications#

max notifications#

The maximum number of TUI notifications that can be shown at a time.

Type: integer
Valid values: x >= 0
Default: 2

Adjusts the height of the notification bar.

max pixels#

max pixels#

The maximum pixel-count for images that should be rendered.

Type: integer
Valid values: x >= 0
Default: 0

If zero, all images will be rendered normally, regardless of their resolution. Otherwise, any image having more pixels than the specified value will be:

  • skipped in CLI mode.

  • replaced in TUI mode (except in the full-grid-image context), with a placeholder (filled with exclamation marks) but can be forced to render using the Force Render action in contexts with a full-sized image view.

    In the image-grid context, such images have a yellow border (when selected) and title.

Note

Overridden by --max-pixels.

multi#

multi#

Enable (if supported) or disable multiprocessing.

Type: boolean
Valid values: true, false
Default: true

If false, the checkers and grid renderers options have no effect.

Note

Overridden by --multi and --no-multi.

query timeout#

query timeout#

Timeout (in seconds) for all terminal queries.

Type: float
Valid values: x > 0.0
Default: 0.1

Note

Overridden by --query-timeout.

style#

style#

Image render style.

Type: string
Valid values: "auto", "block", "iterm2", "kitty"
Default: "auto"

If set to any value other than "auto" and is not overridden by -S, the style is used regardless of whether it’s supported or not.

Note

Overridden by -S.

swap win size#

swap win size#

A workaround for some terminal emulators (e.g older VTE-based ones) that wrongly report window dimensions swapped.

Type: boolean
Valid values: true, false
Default: false

If true, the window dimensions reported by the terminal emulator are swapped.

Note

thumbnail#

thumbnail#

Enable or disable thumbnailing for the image grid.

Type: boolean
Valid values: true, false
Default: true

If true, thumbnails are generated for some images (based on their resolution), cached on disk and cleaned up upon exit. Otherwise, all images in the grid are rendered directly from the original image files.

Note

  • Overridden by --thumbnail and --no-thumbnail.

  • Thumbnails are generated on demand i.e a thumbnail will be generated for an image only if its grid cell has come into view at least once.

  • Thumbnails are deduplicated i.e only one thumbnail is cached and used for different images having exactly identical thumbnails.

thumbnail cache#

thumbnail cache#

The maximum amount of thumbnails that can be cached per time.

Type: integer
Valid values: x >= 0
Default: 0

If 0, the cache size is infinite i.e no eviction. Otherwise, older thumbnails will be evicted to accommodate newer ones when the cache is full (i.e the specified size limit is reached).

Note

Unused if thumbnail is false or --no-thumbnail is specified.

thumbnail size#

thumbnail size#

Maxiumum thumbnail dimension.

Type: integer
Valid values: 32 <= x <= 512
Default: 256

Thumbnails generated will have a maximum of x pixels in the long dimension.

Note

Unused if thumbnail is false or --no-thumbnail is specified.

Keybindings#

The key assigned to every action in the TUI can be modified in the config file.

Keybindings are set by the keys top-level field, the value of which is a mapping containing fields each mapping a context to a mapping of actions and their respective properties.

The format of the keys field is thus:

"keys": {
   "<context>": {
      "<action>": [ "<key>", "<symbol>" ],
      ...
   },
   ...
}

  • context is the name of a context or navigation.

  • action is the name of an action.

  • Both key and symbol may contain Unicode characters and Python unicode escape sequences (\uXXXX and \UXXXXXXXX).

  • ‘…’ means continuous repetition of the format may occur.

Tip

If using a Unicode character that occupies multiple columns in symbol, you might have to add after it as many spaces as are required to cover-up for the extra columns.

Note

The navigation field is not actually a context. Instead, it’s the universal navigation configuration from which navigation actions in actual contexts are derived.

The base navigation actions are:

  • Left

  • Up

  • Right

  • Down

  • Page Up

  • Page Down

  • Home

  • End

Attention

  1. Keys used in the global context cannot be used in any other context (including navigation).

  2. Keys used in the navigation “context” cannot be used in any other context.

  3. All keys in a context must be unique.

  4. If a key is invalid or already used, the former and default keys for that action are tried as a fallback but if that fails (because they’re already used), all keybindings from that config file are considered invalid and any changes already made are reverted.

Here is a sample config file with Vim-style (majorly navigation) keybindings.

Below is a list of all valid values for key:

" "
"!"
"""
"#"
"$"
"%"
"&"
"'"
"("
")"
"*"
"+"
","
"-"
"."
"/"
"0"
"1"
"2"
"3"
"4"
"5"
"6"
"7"
"8"
"9"
":"
";"
"<"
"="
">"
"?"
"@"
"["
"\\"
"]"
"^"
"_"
"`"
"A"
"a"
"ctrl a"
"B"
"b"
"ctrl b"
"C"
"c"
"D"
"d"
"ctrl d"
"E"
"e"
"ctrl e"
"F"
"f"
"ctrl f"
"G"
"g"
"ctrl g"
"H"
"h"
"ctrl h"
"I"
"i"
"ctrl i"
"J"
"j"
"ctrl j"
"K"
"k"
"ctrl k"
"L"
"l"
"ctrl l"
"M"
"m"
"ctrl m"
"N"
"n"
"ctrl n"
"O"
"o"
"ctrl o"
"P"
"p"
"ctrl p"
"Q"
"q"
"ctrl q"
"R"
"r"
"ctrl r"
"S"
"s"
"ctrl s"
"T"
"t"
"ctrl t"
"U"
"u"
"ctrl u"
"V"
"v"
"ctrl v"
"W"
"w"
"ctrl w"
"X"
"x"
"ctrl x"
"Y"
"y"
"ctrl y"
"Z"
"z"
"{"
"|"
"}"
"~"
"f1"
"ctrl f1"
"shift f1"
"shift ctrl f1"
"f2"
"ctrl f2"
"shift f2"
"shift ctrl f2"
"f3"
"ctrl f3"
"shift f3"
"shift ctrl f3"
"f4"
"ctrl f4"
"shift f4"
"shift ctrl f4"
"f5"
"ctrl f5"
"shift f5"
"shift ctrl f5"
"f6"
"ctrl f6"
"shift f6"
"shift ctrl f6"
"f7"
"ctrl f7"
"shift f7"
"shift ctrl f7"
"f8"
"ctrl f8"
"shift f8"
"shift ctrl f8"
"f9"
"ctrl f9"
"shift f9"
"shift ctrl f9"
"up"
"ctrl up"
"shift up"
"shift ctrl up"
"end"
"ctrl end"
"shift end"
"shift ctrl end"
"esc"
"f10"
"ctrl f10"
"shift f10"
"shift ctrl f10"
"f11"
"ctrl f11"
"shift f11"
"shift ctrl f11"
"f12"
"ctrl f12"
"shift f12"
"shift ctrl f12"
"tab"
"down"
"ctrl down"
"shift down"
"shift ctrl down"
"home"
"ctrl home"
"shift home"
"shift ctrl home"
"left"
"ctrl left"
"shift left"
"shift ctrl left"
"enter"
"right"
"ctrl right"
"shift right"
"shift ctrl right"
"delete"
"ctrl delete"
"shift delete"
"shift ctrl delete"
"insert"
"backspace"
"page up"
"ctrl page up"
"page down"
"ctrl page down"

Any value other than these will be flagged as invalid.

Planned Features#

In no particular order:

  • STDIN source

  • Open image in external viewer

  • Pattern-based file and directory exclusion

  • Minimum and maximum file size

  • Optionally following/skipping symlinks

  • Distinguished color for symlinked entries in the list view

  • Full grid view [TUI]

  • Grid cells for directory entries [TUI]

  • CLI grid view

  • Interactive CLI mode

  • Slideshow

  • Zoom/Pan [TUI], Rotate, Flip/Mirror

  • Sorting options

  • Search in iist view

  • Filter in list and grid views

  • Alpha backaground adjustment per image

  • Frame duration adjustment per animated image

  • Copy:

    • Image data

    • File/Directory name

    • Full path

    • Parent directory path

  • Theme customization

  • Configuration menu

  • Also check the library's Planned Features since this viewer is based on it.

  • etc…

Known Issues#

  1. The TUI is not supported on Windows.

  2. Drawing images and animations doesn’t work completely well with Python for windows (tested in Windows Terminal and MinTTY). See the library's Known Issues for details.

    In CLI mode, use --h-allow to specify a horizontal allowance.

  3. Some animations with the kitty render style within the Kitty terminal emulator might be glitchy at the moment. See the library's Known Issues for details.

FAQs#

What about Windows support?

  • Firstly, only the new Windows Terminal seems to have proper truecolor support and modern terminal emulator features.

  • The CLI mode currently works (with a few quirks), i.e using cmd or powershell, if the other requirements are satisfied but can’t guarantee it’ll always be so.

    • Drawing images and animations doesn’t work completely well in cmd and powershell. See the library's Known Issues for details.

  • The TUI doesn’t work due to the lack of fcntl on Windows, which is used by urwid.

  • If stuck on Windows and want to use all features, you could use WSL + Windows Terminal.

Why are colours not properly reproduced?

  • Some terminals support truecolor escape sequences but have a 256-color palette. This limits color reproduction.

Why are images out of scale?
Why is the TUI unresponsive or slow in drawing images?

  • Drawing (not rendering) speed is entirely dependent on the terminal emulator itself.

  • Some terminal emulators block upon input, so rapidly repeated input could cause the terminal to be unresponsive.

Glossary#

Below are definitions of terms used in the CLI help text, info/warning/error messages and the documentation.

Note

For contributors, some of these terms are also used in the source code, as variable names, in comments, docstrings, etc.

active terminal#

The terminal emulator connected to the first TTY device discovered at startup.

At times, this may also be used to refer to the TTY device itself.

alignment#

The position of a primary render output within its padding.

allowance#

The amount of space to be left unused on the terminal screen.

alpha threshold#

Alpha ratio/value above which a pixel is taken as opaque (applies only to text-based render styles).

See also

-A

animated#

Having multiple frames.

The frames of an animated image are generally meant to be displayed in rapid succession, to give the effect of animation.

available height#

The remainder after vertical allowance is subtracted from the maximum amount of lines.

available size#

The remainder after allowances are subtracted from the maximum frame size.

available width#

The remainder after horizontal allowance is subtracted from the maximum amount of columns.

cell ratio#

The aspect ratio (i.e the ratio of width to height) of a character cell on a terminal screen.

See also

Cell Ratio

horizontal alignment#

The horizontal position of a primary render output within its padding width.

See also

--h-align

horizontal allowance#

The amount of columns to be left unused on the terminal screen.

See also

--h-allow

padding#

Amount of lines and columns within which to fit a primary render output.

padding height#

Amount of lines within which to fit a primary render output.

Excess lines on either or both sides of the render output (depending on the vertical alignment) will be filled with spaces.

See also

--pad-height

padding width#

Amount of columns within which to fit a primary render output.

Excess columns on either or both sides of the render output (depending on the horizontal alignment) will be filled with spaces.

See also

--pad-width

render#
rendered#
rendering#

The process of encoding pixel data into a byte/character string (possibly including escape sequences to reproduce colour and transparency).

This string is also called the primary render output and excludes padding.

render style#
render styles#
style#
styles#

A specific technique for rendering or displaying pixel data (including images) in a terminal emulator.

See also

Render Styles

rendered height#

The amount of lines that’ll be occupied by a primary render output when drawn (written) onto a terminal screen.

rendered size#

The amount of space (columns and lines) that’ll be occupied by a primary render output when drawn (written) onto a terminal screen.

rendered width#

The amount of columns that’ll be occupied by a primary render output when drawn (written) onto a terminal screen.

scale#

The fraction/ratio of an image’s size that’ll actually be used to render it.

See also

-s, -x and -y

source#

The resource from which an image instance is initialized.

See also

Image Sources

terminal height#

The amount of lines on a terminal screen at a time i.e without scrolling.

terminal size#

The amount of columns and lines on a terminal screen at a time i.e without scrolling.

terminal width#

The amount of columns on a terminal screen at a time.

vertical alignment#

The vertical position of a primary render output within its padding height.

See also

--v-align

vertical allowance#

The amount of lines to be left unused on the terminal screen.

See also

--v-allow

Indices and tables#